AI Agent 脚手架智能体配置表设计用 YML 编排 AiApi、ChatModel、Agent 与 Workflow【免费下载链接】CodeGuide:books: 本代码库是作者小傅哥多年从事一线互联网 Java 开发的学习历程技术汇总旨在为大家提供一个清晰详细的学习教程侧重点更倾向编写Java核心内容。如果本仓库能为您提供帮助请给予支持(关注、点赞、分享)项目地址: https://gitcode.com/gh_mirrors/code/CodeGuide在《AI Agent 脚手架》项目中智能体的装配并非通过硬编码完成而是通过一套通用的智能体配置表YML 文件驱动。本文围绕 第2-3节智能体配置表设计 展开讲解配置表的结构层次应用名称、智能体描述、智能体模块、各模块AiApi、ChatModel、MCP 工具、Agent、AgentWorkflow、Runner的字段含义与完整 YML 示例并联动装配域各节点源码说明一份配置如何被逐层解析、最终装配出一个可运行的智能体。读完本文你将掌握如何基于脚手架工程通过 YML 配置出属于自己的智能体以及这套配置即编排设计背后的规则树流转原理。一、本章诉求为什么用 YML 配置智能体智能体开发的传统方式是写死——在代码里硬编码 API 地址、模型名称、提示词与工具列表。一旦更换模型或调整流程就要改代码、重新构建、重新发布。本节的诉求非常明确定义一套使用工程 YML 文件配置的通用智能体配置表。用户基于脚手架创建出智能体工程后无需改动代码只需要在 YML 配置文件中声明自己需要的智能体再结合具体业务场景做衔接开发即可。这套设计同时解决了两个问题配置与代码分离模型、提示词、工具、编排关系全部外置到配置业务代码保持稳定可组合可编排通过配置中agent-workflows的loop循环、parallel并行、sequential串行组合可以配置出复杂程度不一的智能体无需硬编码即可完成工作流组装。需要说明的是本节介绍的 YML 配置方案面向工程内配置场景。如果业务需要把配置表抽取到数据库、由前端页面拖拉拽可视化配置则属于另一套方案如《DeepSeek RAG、MCP、Ai Agent 智能体》项目的前端可视化配置可作为扩展学习方向。两种方案配置语义一致差异仅在配置的存储与加载来源。二、流程设计智能体配置表的结构智能体配置表整体分为三层结构如下应用名称app-name └── 智能体描述agent └── 智能体模块module ├── AiApi —— 对接 AI 接口 ├── ChatModel —— 创建对话模型内部也会把 AiApi 接入 ├── MCP 工具 —— 为模型挂载外部工具能力 ├── Agents —— 单一智能体LlmAgent列表 ├── AgentWorkflow —— 工作流编排loop / parallel / sequential └── Runner —— 运行体装配应用名称整个智能体应用的标识对应 YML 中的app-name用于区分不同应用并作为会话创建的上下文智能体描述声明智能体的agent-id、agent-name、agent-desc是智能体注册到 Spring 容器后的身份信息智能体模块核心组件配置区。AiApi负责与 AI 接口建立连接配置 base-url、api-key 等ChatModel负责创建对话模型同时会把AiApi对接进来之后还要为模型创建 MCP 工具让智能体具备调用外部能力搜索、检索代码库等。在完成单一智能体的构建后可以顺序创建出很多个 Agent最后统一到AgentWorkflow中进行编排构建出一个完整的智能体。这部分配置结构映射了 第2-2节系统架构设计 中的流程设计以及 YML 设计——即api、model、agent、workflow、runner再到 Spring 容器的整条装配链路。三、YML 配置表完整示例下面是一份完整可运行的智能体配置parallel_research_app.yml的精简结构完整示例见 第2-13节增强装配-AgentWorkflowNode它配置了一个并行研究 串行汇总的智能体管道ai: agent: config: tables: testAgent02: app-name: ResearchAndSynthesisPipeline agent: agent-id: 100002 agent-name: 测试智能体02 agent-desc: 并行研究并汇总的智能体管道 module: ai-api: base-url: https://apis.itedus.cn api-key: sk-your-api-key completions-path: v1/chat/completions embeddings-path: v1/embeddings chat-model: model: gpt-4.1 tool-mcp-list: - sse: name: baidu-search base-uri: https://appbuilder.baidu.com/v2/ai_search/mcp/ sse-endpoint: sse?api_keybce-v3/your-bce-key request-timeout: 5000 agents: - name: RenewableEnergyResearcher description: Researches renewable energy sources. instruction: | You are an AI Research Assistant specializing in energy. Research the latest advancements in renewable energy sources. Use the Google Search tool provided. Summarize your key findings concisely (1-2 sentences). Output *only* the summary. output-key: renewable_energy_result - name: SynthesisAgent description: Combines research findings into a structured report. instruction: | You are an AI Assistant responsible for combining research findings into a structured report. **Crucially: Your entire response MUST be grounded *exclusively* on the information provided in the Input Summaries below.** **Input Summaries:** * **Renewable Energy:** {renewable_energy_result} **Output Format:** ## Summary of Recent Sustainable Technology Advancements Output *only* the structured report following this format. output-key: synthesis_result agent-workflows: - type: parallel name: ParallelWebResearchAgent description: Runs multiple research agents in parallel to gather information. sub-agents: - RenewableEnergyResearcher - type: sequential name: ResearchAndSynthesisPipeline description: Coordinates parallel research and synthesizes the results. sub-agents: - ParallelWebResearchAgent - SynthesisAgent runner: agent-name: ResearchAndSynthesisPipeline注意上例中api-key、sse-endpoint内的密钥已替换为占位符实际使用时请填入自己的凭据。base-url、completions-path、embeddings-path均为示例值可按所用大模型服务的真实端点调整。3.1 ai-api对接 AI 接口ai-api节点定义与 AI 服务建立 HTTP 连接所需的参数配置项含义base-urlAI 服务网关地址如 OpenAI 兼容网关api-key调用 AI 接口的密钥completions-path对话补全接口路径如v1/chat/completionsembeddings-path向量化接口路径如v1/embeddings供 RAG/向量检索场景使用在装配实现上该节点对应AiApiNode使用 Spring AI 框架提供的构建方法完成OpenAiApi实例的创建详见 第2-5节装配域节点-AiApiNode。项目中也对照引入了 LangChain4j如果希望切换框架可在 Agent 装配阶段做兼容替换。3.2 chat-model创建对话模型并挂载 MCPchat-model节点负责对话模型的创建并把模型所需的工具挂载进来model使用的模型名称如gpt-4.1tool-mcp-listMCP 工具列表支持sseServer-Sent Events、stdio、local等不同加载策略。以sse为例需要配置name工具名、base-uriMCP Server 地址、sse-endpointSSE 端点与鉴权参数、request-timeout请求超时单位为毫秒。对应装配节点为ChatModelNode见 第2-6节装配域节点-ChatModelNode。它从上下文获取AiApiNode创建的OpenAiApi实例填充到ChatModel的实例化中同时完成 MCP 客户端的构建——这套处理基于 Spring AI 框架完成。3.3 agents定义单一智能体LlmAgentagents是一个列表每一项定义一个LlmAgent配置项含义name智能体名称也是后续sub-agents引用它的 keydescription智能体职责描述帮助 LLM 理解该智能体的定位instruction系统提示词Prompt定义智能体的行为、输出格式与约束output-key输出结果在上下文中的存储键供下游智能体通过{output-key}引用当一个业务场景较复杂时会配置多个 LlmAgent 分别承担不同职责例如检索分析、绘图执行、质量审查再由工作流把它们组织起来。对应装配节点为AgentNode见 第2-7节装配域节点-AgentNode。3.4 agent-workflows工作流编排agent-workflows是配置表中编排能力的体现支持三类节点详见 第2-9节装配域节点-Loop、Parallel、Sequentialtype节点适用场景loopLoopAgent循环迭代处理如代码 diff 获取差异 → 检索召回 → 制定 review 计划 → 依次执行分析parallelParallelAgent并行处理多条链路同步完成数据获取、分析与决策显著提升复杂流程执行效率sequentialSequentialAgent串行编排子智能体可与 loop、parallel 组合出复杂流程最终通常以串行收尾以上例配置为例先并行执行多个研究智能体ParallelWebResearchAgent再通过串行管道ResearchAndSynthesisPipeline把并行结果汇总成结构化报告。这样并行研究 串行汇总的流程完全由配置声明无需编写编排代码。3.5 runner运行体装配runner.agent-name指定最终作为运行入口的智能体通常是串行工作流的名称。装配完成后Runner如InMemoryRunner承载会话创建与消息处理注册到 Spring 容器后即可对外提供对话能力。四、配置如何驱动装配规则树节点流转配置表本身只是数据真正把它变成可运行智能体的是装配域Armory。在 第2-4节装配域结构化定义 中项目通过单一职责、规则树组合模式、工厂、上下文对象、泛型等设计手段定义了智能体装配服务结构规则树组合模式节点流转框架节点包括RootNode、AiApiNode、ChatModelNode、AgentNode、AgentWorkflowNode、RunnerNode等IArmoryService 装配服务接口单一职责的装配入口通过工厂管理节点衔接服务上下文对象在各个节点间记录并流转数据如OpenAiApi、ChatModel、agentGroup、当前步骤索引等。节点流转的核心机制是处理完业务后执行 router 路由路由方法调用当前实现类的get方法获取下一个要执行的节点从而把**逻辑区doApply与流转区get**分离让代码更易维护。4.1 增强设计AgentWorkflowNode 作为分发中心在最初设计中LoopAgentNode、ParallelAgentNode、SequentialAgentNode各自负责自身之后的流转判断节点间交叉流转。第 2-13 节对 AgentWorkflowNode 做了增强三个功能节点处理完业务后都回到AgentWorkflowNode统一做流转决策使其成为分发中心职责更清晰也能组合出更复杂的智能体编排。增强后的AgentWorkflowNode.doApply类似一个 for 循环判断是否配置了agentWorkflows、当前步骤是否已到最后一项若是则setCurrentAgentWorkflow(null)路由到RunnerNode收尾否则从配置列表中取出当前步骤对象放入上下文并将步骤索引 1。其get方法则根据当前工作流对象的type路由到loopAgentNode、parallelAgentNode或sequentialAgentNodeOverride protected AiAgentRegisterVO doApply(ArmoryCommandEntity requestParameter, DefaultArmoryFactory.DynamicContext dynamicContext) throws Exception { AiAgentConfigTableVO aiAgentConfigTableVO requestParameter.getAiAgentConfigTableVO(); ListAiAgentConfigTableVO.Module.AgentWorkflow agentWorkflows aiAgentConfigTableVO.getModule().getAgentWorkflows(); // 未配置 agentWorkflows 或已到末尾则流转到 RunnerNode if (null agentWorkflows || agentWorkflows.isEmpty() || dynamicContext.getCurrentStepIndex() agentWorkflows.size()) { dynamicContext.setCurrentAgentWorkflow(null); return router(requestParameter, dynamicContext); } // 取出当前步骤对象步骤值 1 dynamicContext.setCurrentAgentWorkflow(agentWorkflows.get(dynamicContext.getCurrentStepIndex())); dynamicContext.addCurrentStepIndex(); return router(requestParameter, dynamicContext); } Override public StrategyHandlerArmoryCommandEntity, DefaultArmoryFactory.DynamicContext, AiAgentRegisterVO get( ArmoryCommandEntity requestParameter, DefaultArmoryFactory.DynamicContext dynamicContext) { AiAgentConfigTableVO.Module.AgentWorkflow currentAgentWorkflow dynamicContext.getCurrentAgentWorkflow(); if (null currentAgentWorkflow) { return runnerNode; // 没有下一个节点流转到结束节点 } String node AgentTypeEnum.fromType(currentAgentWorkflow.getType()).getNode(); return switch (node) { case loopAgentNode - loopAgentNode; case parallelAgentNode - parallelAgentNode; case sequentialAgentNode - sequentialAgentNode; default - runnerNode; }; }子智能体节点如LoopAgentNode的doApply从上下文获取currentAgentWorkflow通过dynamicContext.queryAgentList(subAgents)查出子 Agent 列表构建LoopAgent/ParallelAgent/SequentialAgent放入agentGroup随后路由回getBean(agentWorkflowNode)继续下一轮决策。4.2 上下文对象节点间数据流转的载体上下文DynamicContext是节点间数据流转的载体下述代码来自 第2-13节增强装配-AgentWorkflowNodepublic static class DynamicContext { private OpenAiApi openAiApi; // LLM API private ChatModel chatModel; // 对话模型 private AtomicInteger currentStepIndex new AtomicInteger(0); // 原子安全的递进步骤 private AiAgentConfigTableVO.Module.AgentWorkflow currentAgentWorkflow; // 当前的智能体 private MapString, BaseAgent agentGroup new HashMap(); // 智能体组 private MapString, Object dataObjects new HashMap(); // 数据对象 }增强后的设计去掉了整个 agentWorkflows 列表改为currentAgentWorkflow当前值 currentStepIndex步骤索引每完成一个步骤索引 1从agentWorkflows取出的当前对象存入currentAgentWorkflow判断与取值都更清晰。五、加载与验证启动装配、会话对话所有节点构建完成后在程序启动时进行自动化加载详见 第2-11节智能体加载使用验证将装配完成的智能体注册进 Spring 容器。之后即可通过测试代码验证整个配置 → 装配 → 对话链路Test public void test_handlerMessage_03(){ AiAgentRegisterVO aiAgentRegisterVO applicationContext.getBean(100002, AiAgentRegisterVO.class); String appName aiAgentRegisterVO.getAppName(); InMemoryRunner runner aiAgentRegisterVO.getRunner(); Session session runner.sessionService() .createSession(appName, xiaofuge) .blockingGet(); Content userMsg Content.fromParts(Part.fromText(你具备哪些能力)); FlowableEvent events runner.runAsync(xiaofuge, session.id(), userMsg); ListString outputs new ArrayList(); events.blockingForEach(event - outputs.add(event.stringifyContent())); log.info(测试结果:{}, JSON.toJSONString(outputs)); }测试中的关键点applicationContext.getBean(100002, AiAgentRegisterVO.class)对应配置表中的agent-id: 100002——配置的智能体已经以 Bean 形式注册进容器随后通过 Runner 创建会话、发送消息、订阅事件流输出结果。运行后可以看到各并行子智能体分别返回了各自的检索能力说明并由汇总智能体输出结构化报告验证了整个 YML 配置驱动的装配链路是正确可用的。六、设计思考与扩展配置即编排agent-workflows中 loop、parallel、sequential 的自由组合能力让不硬编码完成复杂工作流成为可能。这种设计对企业场景非常关键——业务需要什么能力就组装什么节点。多层嵌套验证可以尝试配置一个多层嵌套的智能体parallel 内嵌 sequential、sequential 内嵌 loop 等验证分发中心式流转的鲁棒性这也是掌握本节架构设计后的进阶练习。从 YML 到数据库若业务需要运维/产品自助配置智能体可把本文介绍的配置语义迁移到数据库表结构AiAgentConfigTableVO本身就是配置对象的映射再结合前端拖拽页面生成配置即演进为可视化编排方案。两者共享同一套装配域解析逻辑这正是配置表驱动装配抽象的价值所在。至此智能体配置表从结构设计 → YML 书写 → 节点装配 → 启动加载 → 会话验证的全链路已经打通。后续的对话服务接口service/trigger/ui将在此基础上把 Runner 的对话能力暴露为通用 HTTP 接口供前端页面与业务系统接入。相关实现可继续阅读 第2-17节会话服务接口实现-service 与 第2-19节会话服务接口对接-ui。【免费下载链接】CodeGuide:books: 本代码库是作者小傅哥多年从事一线互联网 Java 开发的学习历程技术汇总旨在为大家提供一个清晰详细的学习教程侧重点更倾向编写Java核心内容。如果本仓库能为您提供帮助请给予支持(关注、点赞、分享)项目地址: https://gitcode.com/gh_mirrors/code/CodeGuide创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考