...大约 7 分钟
一、本章介绍
在该脚手架中，智能体的配置采用工程内的 YML 文件方式进行统一定义，形成一套通用的智能体配置表。用户在通过脚手架完成基础工程搭建后，可以基于 YML 配置灵活定义所需的智能体，并结合具体业务场景进行扩展开发与集成。
如果进一步考虑将 YML 配置抽取到数据库中进行管理，通过前端可视化（拖拽式）页面来完成智能体配置。这种方式更适合复杂场景下的动态配置与管理。
二、流程设计
如图，智能体配置表结构；
首先，一个智能体的基础配置需要包含以下核心信息：应用名称、智能体描述以及智能体模块。其中，主要的组件类配置集中在“智能体模块”中：
AiApi：负责对接具体的 AI 接口；ChatModel：负责模型的创建，同时会依赖并封装AiApi；MCP 工具：用于扩展智能体能力，需要单独进行定义与创建。
在完成基础配置后，就可以进入单一智能体（Agent）的构建阶段。这里可以按顺序创建多个独立的智能体。随后，在
AgentWorkflow中对这些智能体进行编排，从而构建出一个完整的智能体系统。这一过程整体上对应了【第 2-2 节：系统架构设计】中的流程设计以及 YML 配置设计。
三、功能实现
1. 工程结构
在 domain 模块中新增 agent 领域层，并设计值对象
AiAgentConfigTableVO，用于表示智能体配置表。该配置表通过加载 YML 文件的方式完成数据映射。之所以将配置表定义在领域层，是为了使领域服务能够直接注入并使用这些配置数据，从而更好地支撑业务逻辑的实现。
2. 对象设计
/**
* Ai Agent 智能体配置表值对象
*/
@Data
public class AiAgentConfigTableVO {
/**
* 应用名称
*/
private String appName;
/**
* 智能体配置
*/
private Agent agent;
/**
* 智能体模块
*/
private Module module;
@Data
public static class Agent {
/**
* 智能体ID
*/
private String agentId;
/**
* 智能体名称
*/
private String agentName;
/**
* 智能体描述
*/
private String agentDesc;
}
@Data
public static class Module {
private AiApi aiApi;
private ChatModel chatModel;
private List<Agent> agents;
private List<AgentWorkflow> agentWorkflows;
@Data
public static class AiApi {
private String baseUrl;
private String apiKey;
private String completionsPath = "/v1/chat/completions";
private String embeddingsPath = "/v1/embeddings";
}
@Data
public static class ChatModel {
private String model;
private List<ToolMcp> toolMcpList;
@Data
public static class ToolMcp {
private SSEServerParameters sse;
private StdioServerParameters stdio;
@Data
public static class SSEServerParameters {
private String name;
private String baseUri;
private String sseEndpoint;
private Integer requestTimeout = 3000;
}
@Data
public static class StdioServerParameters {
private String name;
private Integer requestTimeout = 3000;
private ServerParameters serverParameters;
@Data
public static class ServerParameters {
private String command;
private List<String> args;
private Map<String, String> env;
}
}
}
}
@Data
public static class Agent {
private String name;
private String instruction;
private String description;
private String outputKey;
}
@Data
public static class AgentWorkflow {
/**
* 类型；loop、parallel、sequential
*/
private String type;
private String name;
private List<String> subAgents;
private String description;
private Integer maxIterations = 3;
}
}
}AiAgentConfigTableVO是一个面向智能体应用的配置值对象，用于承载应用名称、智能体元信息，以及与大模型和工具链相关的模块化配置。其顶层结构主要包含三部分：
appName、agent和module，分别对应应用标识、智能体基础信息以及功能模块配置。其中：顶层的
agent表示主智能体的元信息；module.agent则用于定义编排过程中的子智能体，用于实现职责划分与能力拆分。
在工具集成方面，
ChatModel.ToolMcp同时支持 SSE 与 Stdio 两种服务模式，能够覆盖远程工具调用与本地工具集成的场景。后续也可以扩展对本地自定义 MCP 业务服务的接入能力。
3. 配置案例（yml）
# 数据库配置；启动时配置数据库资源信息
spring:
config:
import:
# - classpath:agent/test-agent-02.yml
- classpath:agent/test-agent.ymlai:
agent:
config:
tables:
testAgent:
app-name: testAgent
agent:
agent-id: 100001
agent-name: 测试智能体01
agent-desc: 一个测试的智能体
module:
ai-api:
base-url: https://api1.oaipro.com
api-key: sk-Sp2jx3yeq7x7HJ663bDc9bF0D34b4f609f833840271519B1
completions-path: v1/chat/completions
embeddings-path: v1/embeddings
chat-model:
model: gpt-5.5-mini
tool-mcp-list:
- sse:
name: baidu-search
base-uri: http://appbuilder.baidu.com/v2/ai_search/mcp/
sse-endpoint: sse?api_key=bce-v3/ALTAK-6SyOtHHftyPsWLoIpz3WL/e7a0d8c2e39e9596b0f1e183cd985da1c32a0d67
request-timeout: 5000
agents:
- name: CodeWriterAgent
description: Writes initial Java code based on a specification.
instruction: |
You are a Java Code Generator.
Based *only* on the user's request, write Java code that fulfills the requirement.
Output *only* the complete Java code block, enclosed in triple backticks (```java ... ```).
output-key: generated_code
- name: CodeReviewerAgent
description: Reviews code and provides feedback.
instruction: |
You are an expert Java Code Reviewer.
Your task is to provide constructive feedback on the provided code.
**Code to Review:**
```java
{generated_code}
```
**Review Criteria:**
1. **Correctness:** Does the code work as intended? Are there logic errors?
2. **Readability:** Is the code clear and easy to understand? Follows Java style guidelines?
3. **Efficiency:** Is the code reasonably efficient? Any obvious performance bottlenecks?
4. **Edge Cases:** Does the code handle potential edge cases or invalid inputs gracefully?
5. **Best Practices:** Does the code follow common Java best practices?
**Output:**
Provide your feedback as a concise, bulleted list. Focus on the most important points for improvement.
If the code is excellent and requires no changes, simply state: "No major issues found."
Output *only* the review comments or the "No major issues" statement.
output-key: review_comments
- name: CodeRefactorerAgent
description: Refactors code based on review comments.
instruction: |
You are a Java Code Refactoring AI.
Your goal is to improve the given Java code based on the provided review comments.
**Original Code:**
```java
{generated_code}
```
**Review Comments:**
{review_comments}
**Task:**
Carefully apply the suggestions from the review comments to refactor the original code.
If the review comments state "No major issues found," return the original code unchanged.
Ensure the final code is complete, functional, and includes necessary imports and docstrings.
**Output:**
Output *only* the final, refactored Java code block, enclosed in triple backticks (```java ... ```).
Do not add any other text before or after the code block.
output-key: refactored_code
agent-workflows:
- type: sequential
name: CodePipelineAgent
description: Executes a sequence of code writing, reviewing, and refactoring.
sub-agents:
- CodeWriterAgent
- CodeReviewerAgent
- CodeRefactorerAgent这是一个用于测试的 Agent 智能体配置，涵盖了智能体描述、AiApi、chatModel 模型，以及 MCP 服务、单一 Agent 和编排配置（agent-workflows）。
本质上，这部分内容是将
cn.cactusli.ai.test.api.agent.SequentialAgentTest中的硬编码逻辑，通过配置化的方式进行抽象与实现。通过这种方式，可以灵活组合，构建适用于不同业务场景的多类型智能体。
4. 配置加载
@Slf4j
@Configuration
@EnableConfigurationProperties(AiAgentAutoConfigProperties.class)
public class AiAgentAutoConfig implements ApplicationListener<ApplicationReadyEvent> {
@Resource
private AiAgentAutoConfigProperties aiAgentAutoConfigProperties;
@Override
public void onApplicationEvent(ApplicationReadyEvent event) {
try {
log.info("Ai Agent 智能体装配 {}", JSON.toJSONString(aiAgentAutoConfigProperties.getTables().values()));
} catch (Exception e) {
throw new RuntimeException(e);
}
}
}在 app 模块的 config 目录中新增 AiAgentAutoConfig。同时，需要添加注解：@EnableConfigurationProperties(AiAgentAutoConfigProperties.class)，否则无法正确加载 yml 中定义的 AiAgentAutoConfigProperties 配置项。
四、功能测试
1. pom 配置
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>- 在 app 模块下 pom 里，增加 validation 配置。
2. 调试验证
26-05-07.16:34:16.757 [main ] INFO AiAgentAutoConfig - Ai Agent 智能体装配 [{"agent":{"agentDesc":"一个测试的智能体","agentId":"100001","agentName":"测试智能体01"},"appName":"testAgent","module":{"agentWorkflows":[{"description":"Executes a sequence of code writing, reviewing, and refactoring.","maxIterations":3,"name":"CodePipelineAgent","subAgents":["CodeWriterAgent","CodeReviewerAgent","CodeRefactorerAgent"],"type":"sequential"}],"agents":[{"description":"Writes initial Java code based on a specification.","instruction":"You are a Java Code Generator.\nBased *only* on the user's request, write Java code that fulfills the requirement.\nOutput *only* the complete Java code block, enclosed in triple backticks (```java ... ```).\n","name":"CodeWriterAgent","outputKey":"generated_code"},{"description":"Reviews code and provides feedback.","instruction":"You are an expert Java Code Reviewer.\nYour task is to provide constructive feedback on the provided code.\n\n**Code to Review:**\n```java\n{generated_code}\n```\n\n**Review Criteria:**\n1. **Correctness:** Does the code work as intended? Are there logic errors?\n2. **Readability:** Is the code clear and easy to understand? Follows Java style guidelines?\n3. **Efficiency:** Is the code reasonably efficient? Any obvious performance bottlenecks?\n4. **Edge Cases:** Does the code handle potential edge cases or invalid inputs gracefully?\n5. **Best Practices:** Does the code follow common Java best practices?\n\n**Output:**\nProvide your feedback as a concise, bulleted list. Focus on the most important points for improvement.\nIf the code is excellent and requires no changes, simply state: \"No major issues found.\"\nOutput *only* the review comments or the \"No major issues\" statement.\n","name":"CodeReviewerAgent","outputKey":"review_comments"},{"description":"Refactors code based on review comments.","instruction":"You are a Java Code Refactoring AI.\nYour goal is to improve the given Java code based on the provided review comments.\n\n**Original Code:**\n```java\n{generated_code}\n```\n\n**Review Comments:**\n{review_comments}\n\n**Task:**\nCarefully apply the suggestions from the review comments to refactor the original code.\nIf the review comments state \"No major issues found,\" return the original code unchanged.\nEnsure the final code is complete, functional, and includes necessary imports and docstrings.\n\n**Output:**\nOutput *only* the final, refactored Java code block, enclosed in triple backticks (```java ... ```).\nDo not add any other text before or after the code block.\n","name":"CodeRefactorerAgent","outputKey":"refactored_code"}],"aiApi":{"apiKey":"sk-Sp2jx3yeq7x7HJ663bDc9bF0D34b4f609f833840271519B1","baseUrl":"https://api1.oaipro.com","completionsPath":"v1/chat/completions","embeddingsPath":"v1/embeddings"},"chatModel":{"model":"gpt-5.5-mini","toolMcpList":[{"sse":{"baseUri":"http://appbuilder.baidu.com/v2/ai_search/mcp/","name":"baidu-search","requestTimeout":5000,"sseEndpoint":"sse?api_key=bce-v3/ALTAK-6SyOtHHftyPsWLoIpz3WL/e7a0d8c2e39e9596b0f1e183cd985da1c32a0d67"}}]}}}]- 通过 debug 方式调试，在 AiAgentAutoConfig 的 25 行打断点，观察配置文件的加载。
赞助