Subagent Framework（子智能体框架）提供了一套协议无关抽象层，用于将各类智能体通信协议与 TaskTool 集成。开发者可以通过统一接口，编排来自不同后端的异构智能体：本地基于大模型的子智能体、遵循A2A协议的远程智能体，或是自定义实现的智能体。
服务提供者接口（SPI）全部定义在 spring‑ai‑agent‑utils‑common 模块中。这样不同子智能体实现可以放在独立模块开发，模块之间不存在互相依赖。
设计理念
本框架遵循一条核心原则：将智能体发现与智能体执行解耦。 通过该分离设计，可以实现：
- 多协议支持：Claude Markdown、A2A、MCP、自定义HTTP API
- 本地与远程混合：本地LLM子智能体可以和远程专用智能体协同工作
- 协议专属元数据：每种协议可定义自身独有的配置格式
- 可插拔执行层：无需修改智能体定义，即可替换底层传输层
架构
TaskTool 架构如下：
核心抽象接口
所有SPI接口都位于包 org.springaicommunity.agent.common.task.subagent（spring‑ai‑agent‑utils‑common 模块）。
SubagentReference 子智能体引用
指向智能体定义资源的轻量指针。
|
1 2 3 4 5 |
public record SubagentReference( String uri, // 资源位置（URL、类路径、文件路径） String kind, // 协议标识 ("CLAUDE", "A2A", "MCP" 等) Map<String, String> metadata // 协议专属元数据 ) {} |
代码示例
|
1 2 3 4 5 6 7 |
// Claude Markdown 文件 new SubagentReference("classpath:/agents/explorer.md", "CLAUDE") // A2A远程智能体 new SubagentReference("http://agent.example.com:10001/myagent", "A2A") // 自定义协议，附带元数据 new SubagentReference("grpc://agents.internal:443/analyzer", "CUSTOM", Map.of("auth", "mtls", "timeout", "30s")) |
SubagentResolver 子智能体解析器
策略接口，负责将引用解析为完整智能体定义。
|
1 2 3 4 5 6 |
public interface SubagentResolver { /** 如果该解析器可以处理此类型的引用，则返回true */ boolean canResolve(SubagentReference subagentRef); /** 将引用解析为完整的智能体定义 */ SubagentDefinition resolve(SubagentReference subagentRef); } |
SubagentDefinition 子智能体定义
完整的智能体元数据与配置信息。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
public interface SubagentDefinition { /** 子智能体唯一标识 */ String getName(); /** 在TaskTool可用智能体列表中展示的描述 */ String getDescription(); /** 协议类型（例如 "CLAUDE", "A2A"） */ String getKind(); /** 生成该定义所使用的原始引用 */ SubagentReference getReference(); /** 用于TaskTool注册展示的格式化输出 */ default String toSubagentRegistrations() { return "-%s: /%s".formatted(getName(), getDescription()); } } |
SubagentExecutor 子智能体执行器
使用对应协议通信，执行具体任务。
|
1 2 3 4 5 6 |
public interface SubagentExecutor { /** 返回该执行器负责处理的子智能体类型 */ String getKind(); /** 执行任务并返回响应文本 */ String execute(TaskCall taskCall, SubagentDefinition subagent); } |
SubagentType 子智能体类型
将解析器与执行器绑定为一组，用于向 TaskTool.builder().subagentTypes(...) 注册。
|
1 2 3 4 5 6 |
public record SubagentType( SubagentResolver resolver, SubagentExecutor executor ) { public String kind() { return executor.getKind(); } } |
TaskCall 任务调用
描述待执行任务的数据记录，TaskTool 和 SubagentExecutor 均使用该对象。
|
1 2 3 4 5 6 7 8 |
public record TaskCall( String description, // 简短任务描述，3‑5个词 String prompt, // 下发给子智能体的任务提示词 String subagent_type, // 要调用的子智能体类型 String model, // 可选：覆盖使用的模型 String resume, // 可选：恢复上一次子智能体会话 Boolean run_in_background // 可选：后台异步运行 ) {} |
内置实现：Claude子智能体
默认实现遵循 Claude Code 的 Markdown + YAML 前置元数据格式。
智能体定义文件格式
文件格式如下：
|
1 2 3 4 5 6 7 8 9 10 |
--- name: spring‑ai‑expert description: Spring AI框架问题答疑专家 model: sonnet # 可选：指定路由模型 tools: Read, Grep, WebFetch # 可选：允许使用工具 disallowedTools: Edit, Write # 可选：禁止使用工具 skills: ai‑tutor # 可选：预加载技能集 permissionMode: default # 可选：权限处理模式 --- 你是一名Spring AI领域专家…… |
Claude相关组件
| 类名 | 功能说明 |
|---|---|
ClaudeSubagentDefinition |
解析YAML前置元数据（model、tools、skills等字段） |
ClaudeSubagentResolver |
从类路径或者文件系统加载Markdown子智能体文件 |
ClaudeSubagentExecutor |
基于Spring AI ChatClient执行，完成工具过滤、预加载技能 |
ClaudeSubagentReferences |
工厂方法，扫描发现智能体配置文件 |
ClaudeSubagentType |
便捷构建器，生成带有默认工具集的SubagentType |
注册示例代码
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
// 构建Claude子智能体类型，配置ChatClient与技能资源 SubagentType claudeType = ClaudeSubagentType.builder() .chatClientBuilder("default", chatClientBuilder) .skillsResources(skillPaths) .braveApiKey(braveApiKey) .build(); // 扫描资源目录，获取全部Claude子智能体引用 List<SubagentReference> refs = ClaudeSubagentReferences.fromResources(agentResources); // 向TaskTool注册（内置通用子智能体会自动注册） TaskTool.builder() .subagentTypes(claudeType) .subagentReferences(refs) .build(); |
A2A协议子智能体
A2A（Agent‑to‑Agent）协议的实现位于独立模块 spring‑ai‑agent‑utils‑a2a，完整文档参考该模块README。
A2A组件
| 类名 | 功能说明 |
|---|---|
A2ASubagentDefinition |
封装A2A的AgentCard元数据，kind类型为"A2A" |
A2ASubagentResolver |
从/.well‑known/agent‑card.json拉取智能体卡片 |
A2ASubagentExecutor |
使用JSON‑RPC传输发送消息，从返回工件中提取文本结果 |
注册示例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
import org.springaicommunity.agent.common.task.subagent.SubagentReference; import org.springaicommunity.agent.common.task.subagent.SubagentType; import org.springaicommunity.agent.subagent.a2a.A2ASubagentDefinition; import org.springaicommunity.agent.subagent.a2a.A2ASubagentExecutor; import org.springaicommunity.agent.subagent.a2a.A2ASubagentResolver; TaskTool.builder() // 注册本地Claude子智能体 .subagentTypes(ClaudeSubagentType.builder() .chatClientBuilder("default", chatClientBuilder) .build()) // 添加远程A2A子智能体引用 .subagentReferences(new SubagentReference("http://localhost:10001/myagent", A2ASubagentDefinition.KIND)) // 注册A2A解析器+执行器 .subagentTypes(new SubagentType(new A2ASubagentResolver(), new A2ASubagentExecutor())) .build(); |
实现自定义协议
新增一套协议，需要实现3个接口，组装成SubagentType完成注册。
1. 实现 SubagentDefinition
封装协议专属元数据
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
public class MySubagentDefinition implements SubagentDefinition { public static final String KIND = "MY_PROTOCOL"; private final SubagentReference reference; private final MyAgentMetadata metadata; @Override public String getName() { return metadata.name(); } @Override public String getDescription() { return metadata.description(); } @Override public String getKind() { return KIND; } @Override public SubagentReference getReference() { return reference; } // 协议专属获取方法 public MyAgentMetadata getMetadata() { return metadata; } } |
2. 实现 SubagentResolver
按照协议规则发现智能体资源
|
1 2 3 4 5 6 7 8 9 10 11 |
public class MySubagentResolver implements SubagentResolver { @Override public boolean canResolve(SubagentReference ref) { return ref.kind().equals(MySubagentDefinition.KIND); } @Override public SubagentDefinition resolve(SubagentReference ref) { MyAgentMetadata metadata = fetchMetadata(ref.uri()); return new MySubagentDefinition(ref, metadata); } } |
3. 实现 SubagentExecutor
通过协议传输完成任务调用
|
1 2 3 4 5 6 7 8 9 |
public class MySubagentExecutor implements SubagentExecutor { @Override public String getKind() { return MySubagentDefinition.KIND; } @Override public String execute(TaskCall taskCall, SubagentDefinition subagent) { MySubagentDefinition myAgent = (MySubagentDefinition) subagent; return myClient.send(myAgent.getMetadata(), taskCall.prompt()); } } |
4. 在TaskTool注册
|
1 2 3 4 |
TaskTool.builder() .subagentReferences(new SubagentReference("my://agent‑1", MySubagentDefinition.KIND)) .subagentTypes(new SubagentType(new MySubagentResolver(), new MySubagentExecutor())) .build(); |
其他协议实现思路
这套抽象可以适配各类智能体通信模式。
MCP（模型上下文协议）
|
1 2 3 4 5 6 7 8 9 10 |
public class MCPSubagentDefinition implements SubagentDefinition { public static final String KIND = "MCP"; // 封装MCP服务端能力信息 } public class MCPSubagentResolver implements SubagentResolver { // 从mcp.json配置加载，或者通过stdio/SSE发现服务 } public class MCPSubagentExecutor implements SubagentExecutor { // 通过MCP工具调用执行任务 } |
自定义HTTP API
|
1 2 3 4 5 6 7 8 9 10 11 |
public class HttpSubagentDefinition implements SubagentDefinition { public static final String KIND = "HTTP"; private final String endpoint; private final Map<String, String> headers; } public class HttpSubagentResolver implements SubagentResolver { // 从OpenAPI规范或者配置文件加载 } public class HttpSubagentExecutor implements SubagentExecutor { // 通过REST接口发起调用 } |
gRPC智能体
|
1 2 3 4 |
public class GrpcSubagentDefinition implements SubagentDefinition { public static final String KIND = "GRPC"; private final ManagedChannel channel; } |
完整注册执行流程
完整执行流程如下图：
模块包结构
参考模块包结构如下：
|
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 |
spring‑ai‑agent‑utils‑common/ org.springaicommunity.agent.common.task.subagent ├── SubagentDefinition.java # 核心接口：子智能体定义 ├── SubagentReference.java # 轻量子智能体引用记录 ├── SubagentResolver.java # 子智能体解析器接口 ├── SubagentExecutor.java # 子智能体执行器接口 ├── SubagentType.java # 解析器与执行器绑定组合 └── TaskCall.java # 任务调用入参记录 spring‑ai‑agent‑utils/ org.springaicommunity.agent.tools.task ├── TaskTool.java # 主工具类，Builder构造器 ├── TaskOutputTool.java # 获取后台子任务结果工具 └── subagent/claude/ # Claude内置实现 ├── ClaudeSubagentDefinition.java ├── ClaudeSubagentResolver.java ├── ClaudeSubagentExecutor.java ├── ClaudeSubagentReferences.java └── ClaudeSubagentType.java # 便捷构建器 spring‑ai‑agent‑utils‑a2a/ org.springaicommunity.agent.subagent.a2a ├── A2ASubagentDefinition.java ├── A2ASubagentResolver.java └── A2ASubagentExecutor.java |
相关文档
- TaskTools — TaskTool完整文档与使用指南
- spring‑ai‑agent‑utils‑common — SPI模块，全部核心抽象
- spring‑ai‑agent‑utils‑a2a — A2A协议实现
- SkillsTool — 子智能体可复用知识模块
- 示例：subagent‑demo — 本地Claude子智能体演示工程
- 示例：subagent‑a2a‑demo — A2A远程智能体集成演示
- 原文：Subagent Framework – Protocol-Agnostic Agent Orchestration