AI 智能体脚手架：从 YAML 配置到多 Agent 协同的工程实践

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

为什么接口契约层和触发层要分开？因为接口契约层定义的是**对外的 API 契约**，将来如果要从 HTTP 换成 RPC，只需要新增一个触发层实现，接口契约层完全不动。而且其他服务要调用我们，只需要依赖这一个契约模块，不会碰到任何实现代码。

## 二、双框架适配：为什么要同时用两个框架

这个项目同时用了 Google ADK 和 Spring AI，各取所长：

| 框架 | 擅长的事 | 在项目中的角色 |
|------|---------|---------------|
| Google ADK | 多智能体编排、会话管理 | 上层，管调度 |
| Spring AI | 多模型接入、工具自动执行 | 下层，管调用 |

问题来了：两套框架的消息格式不一样。ADK 用的是 Content / Part 结构，Spring AI 用的是 Prompt / Message 结构。所以中间需要一个适配器来做转换。

这个适配器是整个项目的**枢纽**，它的核心方法做三件事：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

## MySpringAI 适配器

### 为什么需要它

`LlmAgent` 来自 Google ADK 框架，它要求的模型接口是 `LlmModel`（Google 自己定义的）。`ChatModel` 来自 Spring AI 框架，方法名、参数类型、返回类型全都不一样。直接把 `ChatModel` 塞给 `LlmAgent`，编译都过不了。

`MySpringAI` 就是一个翻译官（适配器），对上实现 Google ADK 的 `LlmModel` 接口，对下内部调用 Spring AI 的 `ChatModel` 方法：

```java
public class MySpringAI implements LlmModel {
    private final ChatModel chatModel;  // 内部持有 Spring AI 的模型

    public LlmResponse generate(LlmRequest request) {
        Prompt springPrompt = convertToSpringPrompt(request);  // Google格式 → Spring格式
        ChatResponse response = chatModel.call(springPrompt);   // 用Spring AI真正调LLM
        return convertToAdkResponse(response);                  // Spring格式 → Google格式
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

根节点（空节点，哨兵）
  │
  ▼
API 节点
  │  读取配置中的 URL 和密钥
  │  创建 API 连接对象 → 存入上下文
  ▼
模型节点
  │  取出 API 连接 + 模型名称
  │  遍历 MCP 工具列表（远程SSE/本地命令行/本地JavaBean）
  │  遍历 Skills 技能文件（文档+脚本）
  │  所有工具统一构建为 ToolCallback → 放入同一个列表
  │  创建 ChatModel 对象 → 存入上下文
  ▼
智能体节点
  │  遍历配置中的每个智能体
  │  取名称、描述、提示词、输出键
  │  用适配器包装 ChatModel
  │  创建 LLMAgent → 存入上下文的 Map 集合
  ▼
编排节点（1 主节点 + 3 子节点，逻辑循环）
  │  详见 3.3 节
  ▼
运行器节点
  │  取出配置指定的入口智能体
  │  创建 InMemoryRunner
  │  包装成注册对象 → 动态注册为 Spring Bean
  ▼
  装配完成 ✓

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

         ┌──────────────┐
         │   主节点      │
         │              │
         │ 计数器 >= 总数?│──── 是 ────→ 运行器节点
         │              │
         │   否，按类型   │
         │   路由到子节点  │
         └──┬───┬───┬───┘
            │   │   │
     ┌──────┘   │   └──────┐
     ▼          ▼          ▼
  串行子节点  并行子节点  循环子节点
     │          │          │
     └──────┬───┘──────────┘
            │
            │  创建完 → 存入集合 → 路由回主节点
            ▼
         ┌──────────────┐
         │   主节点      │  ← 继续循环
         └──────────────┘

1
2
3
4
5
6
7

// 子节点的路由方法
@Override
public StrategyHandler get(...) {
    // 不用 @Resource 注入，而是运行时从容器取
    // 因为主节点持有子节点引用，子节点再注入主节点就循环了
    return getBean("agentWorkflowNode");
}

1
2
3
4
5
6
7

DynamicContext（共享黑板）
├── API 连接对象      ← API 节点写入，模型节点读取
├── ChatModel 对象    ← 模型节点写入，智能体节点读取
├── 智能体 Map 集合   ← 智能体节点 + 编排节点共同写入
├── 编排步骤计数器    ← 编排节点用来控制循环
└── 当前编排配置      ← 编排节点用来判断类型和路由

1
2
3
4
5
6
7
8

if ("directory".equals(type)) {
    // 从文件系统绝对路径加载——适合本地开发
    SkillsTool.builder().addSkillsDirectory(path).build();
}
if ("resource".equals(type)) {
    // 从 classpath 资源路径加载——适合打包部署
    SkillsTool.builder().addSkillsResource(new ClassPathResource(path)).build();
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

YAML（原材料）
  │
  ▼
第1站 RootNode        → 纯入口，像链表头指针，什么都不做
  │
  ▼
第2站 AiApiNode       → 创建 OpenAiApi（API连接对象）
  │
  ▼
第3站 ChatModelNode   → 创建 ChatModel（聊天模型 + MCP/Skills工具）
  │
  ▼
第4站 AgentNode       → 创建 20 个基础 LlmAgent，全部放入 agentGroup 货架
  │
  ▼
第5站 AgentWorkflowNode → 循环处理 8 个工作流配置，每次根据类型分发到子节点
  │     ├── LoopAgentNode       → 处理 loop 类型 → 回到 AgentWorkflowNode
  │     ├── ParallelAgentNode   → 处理 parallel 类型 → 回到 AgentWorkflowNode
  │     └── SequentialAgentNode → 处理 sequential 类型 → 回到 AgentWorkflowNode
  │
  ▼
第6站 RunnerNode      → 取出最终入口 Agent，包装成 InMemoryRunner，注册到 Spring
  │
  ▼
成品：AiAgentRegisterVO（包着 runner 的信封）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

@Configuration
@EnableConfigurationProperties(AiAgentAutoConfigProperties.class)
public class AiAgentAutoConfig implements ApplicationListener<ApplicationReadyEvent> {

    @Override
    public void onApplicationEvent(ApplicationReadyEvent event) {
        // 从配置类（Bean）里取出配置数据（不是Bean，只是普通Java对象）
        // 传给装配服务开始组装
        armoryService.acceptArmoryAgents(
            new ArrayList<>(aiAgentAutoConfigProperties.getTables().values()));
    }
}

1
2
3
4
5
6
7

public static class DynamicContext {
    private OpenAiApi openAiApi;          // 第2站放入
    private ChatModel chatModel;          // 第3站放入
    private Map<String, BaseAgent> agentGroup = new HashMap<>();  // 第4站开始持续放入
    private AtomicInteger currentStepIndex = new AtomicInteger(0); // 第5站的循环计数器
    private AgentWorkflow currentAgentWorkflow;  // 第5站每次循环覆盖写入
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// AgentWorkflowNode.doApply() 核心逻辑
if (dynamicContext.getCurrentStepIndex() >= agentWorkflows.size()) {
    // 全部处理完了，跳到 RunnerNode
    dynamicContext.setCurrentAgentWorkflow(null);
    return router(requestParameter, dynamicContext);
}
// 取出当前索引对应的 workflow，放入上下文
dynamicContext.setCurrentAgentWorkflow(agentWorkflows.get(dynamicContext.getCurrentStepIndex()));
dynamicContext.addCurrentStepIndex();  // 索引 +1
return router(requestParameter, dynamicContext);

1
2
3
4
5
6

return switch (node) {
    case "loopAgentNode"       -> loopAgentNode;
    case "parallelAgentNode"   -> parallelAgentNode;
    case "sequentialAgentNode" -> sequentialAgentNode;
    default -> runnerNode;
};

1
2
3
4
5
6

InMemoryRunner
├── 入口智能体     （可以是 LLMAgent 也可以是编排智能体）
├── 智能体名称
├── 工具列表       （所有 MCP + Skills）
└── 会话服务       （管理用户会话的生命周期和对话历史）

1
2
3
4
5

// 注册逻辑（伪代码）
if (容器中已存在同名 Bean) {
    先移除旧的;  // 支持热替换
}
注册新的 Bean(agentId, 注册对象);

1
2
3
4
5
6
7

InputEchoAgent 执行完 → session.state.put("request_brief", "目标：分析AI趋势...")

QuestionDecomposerAgent 即将执行：
  instruction 里有 {request_brief}
  → 从 session.state 取出 "request_brief" 的值
  → 替换占位符后发给 LLM

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

我们代码管理的（外层）：
┌────────────────────────────────────┐
│  ConcurrentHashMap<用户ID, 会话ID>  │
│                                    │
│  "xiaofuge"  →  "a3f6-..."        │
│  "admin"     →  "b7e2-..."        │
└────────────────────────────────────┘
    ↑ 作用：快速查找用户有没有会话
    ↑ 只存映射关系，不存聊天内容

SDK 内部管理的（内层）：
┌────────────────────────────────────┐
│  SessionService                    │
│                                    │
│  Session "a3f6-..." {              │
│    events: [                       │
│      { role: user,  text: "你好" }  │
│      { role: model, text: "你好！" }│
│      { role: user,  text: "1+1" }  │
│      { role: model, text: "等于2" } │
│    ]                               │
│  }                                 │
└────────────────────────────────────┘
    ↑ 作用：存储真正的对话历史

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

【注入】我们的代码 ──────────────────────────────────
  装配时遍历 MCP + Skills
  构建 ToolCallback 列表
  注入到 ChatModel 对象中

【触发】Spring AI 自动完成 ──────────────────────────
  调用大模型时，把工具描述一起发过去
  大模型自己决定是否调用
  如果要调用，返回工具名称 + 参数

【执行】Spring AI 自动完成 ──────────────────────────
  从 ToolCallback 列表中匹配对应工具
  执行工具，拿到结果
  把结果连同之前的消息再发给大模型
  ↑ 这个过程可能多轮循环，直到大模型返回最终回答

1
2
3
4
5
6
7

ChatCommandEntity
├── texts: ["请分析这张图片"]          → 转为文本类型 Part
├── inlineDatas: [{bytes, mimeType}]  → 转为内联数据类型 Part
└── fileUris: [{url, mimeType}]       → 转为 URI 类型 Part
                                           ↓
                                    合并为一个 Content 消息体

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

原始消息（包含文本 + 图片）
        │
        ├──① 先把多媒体数据提取出来暂存
        │
        ├──② 调用父类的转换方法（多媒体会丢失）
        │
        ├──③ 把暂存的多媒体数据补回到转换结果的媒体字段
        │
        ▼
Spring AI 格式的消息（文本 + 图片都在）

1
2
3
4
5
6
7

public interface StrategyHandler<T, D, R> {
    // 对外暴露的执行入口——外界调用这个来启动节点
    R apply(T requestParameter, D dynamicContext) throws Exception;

    // 获取下一个节点——每个节点必须告诉框架"下一站是谁"
    StrategyHandler<T, D, R> get(T requestParameter, D dynamicContext) throws Exception;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

public abstract class AbstractMultiThreadStrategyRouter<T, D, R>
        implements StrategyHandler<T, D, R> {

    // 子类必须实现的"干活"方法
    protected abstract R doApply(T requestParameter, D dynamicContext) throws Exception;

    // apply() 的实现——框架帮你写好了
    @Override
    public R apply(T requestParameter, D dynamicContext) throws Exception {
        return doApply(requestParameter, dynamicContext);
    }

    // ★ router()——找到下一个节点并执行它
    protected R router(T requestParameter, D dynamicContext) throws Exception {
        StrategyHandler<T, D, R> nextHandler = get(requestParameter, dynamicContext);
        if (nextHandler != null) {
            return nextHandler.apply(requestParameter, dynamicContext);
        }
        return null;
    }
}

1
2
3
4
5
6
7
8
9

LLM 调用异常
    │
    ├── 记录到监控组件
    ├── 错误映射（统一格式）
    ├── 包装成 RuntimeException 向上抛
    │
    ├── 非流式 → 返回错误 JSON
    └── 流式 → emitter.completeWithError() 中断连接

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

步骤 1：前端调用文件上传接口
POST /api/v1/files/upload  (multipart/form-data)
返回：{ "fileUri": "https://oss.xxx/dog.png", "mimeType": "image/png" }

步骤 2：前端调用对话接口（JSON，不变）
POST /api/v1/chat
{
  "agentId": "100003",
  "userId": "admin",
  "message": "请分析这张图片",
  "files": [
    { "fileUri": "https://oss.xxx/dog.png", "mimeType": "image/png" }
  ]
}