AI Agent 脚手架智能体配置表设计：用 YML 编排 AiApi、ChatModel、Agent 与 Workflow

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 配置文件中声明自己需要的智能体，再结合具体业务场景做衔接开发即可。这套设计同时解决了两个问题：

1. 配置与代码分离：模型、提示词、工具、编排关系全部外置到配置，业务代码保持稳定；
2. 可组合可编排：通过配置中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_key=bce-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 连接所需的参数：

在装配实现上，该节点对应AiApiNode，使用 Spring AI 框架提供的构建方法完成OpenAiApi实例的创建（详见 第2-5节：装配域节点-AiApiNode）。项目中也对照引入了 LangChain4j，如果希望切换框架，可在 Agent 装配阶段做兼容替换。

3.2 chat-model：创建对话模型并挂载 MCP

chat-model节点负责对话模型的创建，并把模型所需的工具挂载进来：

• model：使用的模型名称（如gpt-4.1）；
• tool-mcp-list：MCP 工具列表，支持sse（Server-Sent Events）、stdio、local等不同加载策略。以sse为例，需要配置name（工具名）、base-uri（MCP Server 地址）、sse-endpoint（SSE 端点与鉴权参数）、request-timeout（请求超时，单位为毫秒）。

对应装配节点为ChatModelNode（见 第2-6节：装配域节点-ChatModelNode）。它从上下文获取AiApiNode创建的OpenAiApi实例，填充到ChatModel的实例化中，同时完成 MCP 客户端的构建——这套处理基于 Spring AI 框架完成。

3.3 agents：定义单一智能体（LlmAgent）

agents是一个列表，每一项定义一个LlmAgent：

当一个业务场景较复杂时，会配置多个 LlmAgent 分别承担不同职责（例如：检索分析、绘图执行、质量审查），再由工作流把它们组织起来。对应装配节点为AgentNode（见 第2-7节：装配域节点-AgentNode）。

3.4 agent-workflows：工作流编排

agent-workflows是配置表中"编排能力"的体现，支持三类节点（详见 第2-9节：装配域节点-Loop、Parallel、Sequential）：

以上例配置为例：先并行执行多个研究智能体（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或sequentialAgentNode：

@Override protected AiAgentRegisterVO doApply(ArmoryCommandEntity requestParameter, DefaultArmoryFactory.DynamicContext dynamicContext) throws Exception { AiAgentConfigTableVO aiAgentConfigTableVO = requestParameter.getAiAgentConfigTableVO(); List<AiAgentConfigTableVO.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 StrategyHandler<ArmoryCommandEntity, 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节：增强装配-AgentWorkflowNode）：

public static class DynamicContext { private OpenAiApi openAiApi; // LLM API private ChatModel chatModel; // 对话模型 private AtomicInteger currentStepIndex = new AtomicInteger(0); // 原子安全的递进步骤 private AiAgentConfigTableVO.Module.AgentWorkflow currentAgentWorkflow; // 当前的智能体 private Map<String, BaseAgent> agentGroup = new HashMap<>(); // 智能体组 private Map<String, 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("你具备哪些能力")); Flowable<Event> events = runner.runAsync("xiaofuge", session.id(), userMsg); List<String> 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 配置驱动的装配链路是正确可用的。

六、设计思考与扩展

1. 配置即编排：agent-workflows中 loop、parallel、sequential 的自由组合能力，让"不硬编码完成复杂工作流"成为可能。这种设计对企业场景非常关键——业务需要什么能力，就组装什么节点。
2. 多层嵌套验证：可以尝试配置一个多层嵌套的智能体（parallel 内嵌 sequential、sequential 内嵌 loop 等），验证分发中心式流转的鲁棒性，这也是掌握本节架构设计后的进阶练习。
3. 从 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