• 人工智能
• AI Agent
• 工具调用
• AI 技能
• 代码智能体
• 后端

spring-ai-agent-utils 是一个面向 Spring AI 的多智能体工具库，把 Claude Code 风格的工具与 Agent 技能带入你的 AI 应用。本文带你上手它最核心的TaskTool：只需一行 Builder 配置，主 Agent 就能把探索代码库、制定实现计划、执行终端命令等复杂任务，自动委派给4 个内置子代理并行完成，同时保持主对话上下文干净。

为什么需要子代理委派？🤔

直接让一个大 Agent 包办所有任务，很快就会遇到两个问题：

• 上下文污染：搜索代码、读文件、跑命令产生的海量中间结果，会把主对话窗口塞满，模型注意力被稀释；
• 工具权限失控：一个"只想查资料"的任务，却握有写文件、删文件的工具。

子代理（Sub-agent）正是解法。在 spring-ai-agent-utils 中，每个子代理都拥有：

这套设计参考了 Claude Code 的子代理机制，完整文档见 TaskTools.md。

认识 4 个内置子代理 🧩

当你注册了 Claude 子代理类型后，TaskTool.Builder.build() 会自动注册 4 个内置子代理，无需任何额外配置：

四个子代理的完整定义都是可读的 Markdown 文件，存放在 agent/ 目录下：

• GENERAL_PURPOSE_SUBAGENT.md —— 擅长跨大代码库搜索配置与代码模式、分析多个文件理解系统架构，要求返回绝对路径和代码片段；
• EXPLORE_SUBAGENT.md —— 严格只读模式，调用时还可以指定探索深度：quick（基础搜索）、medium（多策略探索）、very thorough（全面分析）；
• PLAN_SUBAGENT.md —— 规划专用，输出固定包含"摘要、待修改文件、实现步骤、权衡分析、风险"五个部分，并明确禁止修改任何文件；
• BASH_SUBAGENT.md —— 内置 git 安全规则（不擅自 force push、破坏性命令需确认），文件读写交由父 Agent 处理。

💡 提示：TaskTool 的工具描述里还明确告诉模型什么时候不该用 Task——比如已知具体文件路径就直接用 Read，找某个类定义直接用 Glob，避免无谓的委派开销。

三步配置 TaskTool 子代理委派

第一步：添加依赖

<dependency> <groupId>org.springaicommunity</groupId> <artifactId>spring-ai-agent-utils</artifactId> <version>0.13.0</version> </dependency>

第二步：构建 TaskTool

核心就一句 Builder：注册ClaudeSubagentType后，4 个内置子代理自动就位。

ToolCallback taskTool = TaskTool.builder() .subagentTypes(ClaudeSubagentType.builder() .chatClientBuilder("default", chatClientBuilder) .build()) .build();

ClaudeSubagentType 是便捷构建器，子代理默认自带 Grep、Glob、Shell、文件系统、WebFetch、TodoWrite 等工具，还可按需开启 Brave 网页搜索。

第三步：挂到 ChatClient

ChatClient chatClient = chatClientBuilder .defaultToolCallbacks(taskTool) .build();

配置完成！主 Agent 看到 Task 工具后，会根据各子代理的描述自动决定何时委派。

实战：四种委派方式

1️⃣ 自然语言自动委派

直接提问，主 Agent 识别出这是探索类任务，自动交给Explore：

"认证模块是怎么工作的？"

2️⃣ 显式指定子代理

"用 Bash 子代理跑一下项目的测试，并汇报结果"

3️⃣ 后台运行 + TaskOutput 取结果

设置run_in_background: true后，TaskTool 立即返回task_id，主 Agent 可以一边继续工作一边等子代理。任务完成后通过 TaskOutputTool 用该 id 检索结果。

4️⃣ 并行委派（性能关键）

需要"同时"跑多个任务时，主 Agent 会在一条消息里发出多个 Task 调用。例如让Explore找所有 API 端点、同时让Plan起草重构方案，互不阻塞。

子代理调用的输入结构定义在 TaskCall.java：

多步任务的推进由 TodoWriteTool 配合完成，下面的时序图展示了它在 Spring AI 多智能体中的编排流程：

运行官方 subagent-demo 示例 🚀

项目内置了可运行的多智能体示例，克隆仓库后即可体验：

git clone https://gitcode.com/gh_mirrors/sp/spring-ai-agent-utils cd spring-ai-agent-utils mvn -pl examples/subagent-demo -am spring-boot:run

示例入口 Application.java 演示了完整装配：TaskTool + 技能工具 + TodoWrite 任务编排 + Grep/Glob/Shell/FileSystem 通用工具，最后进入交互式对话循环。启动后直接问"帮我梳理一下这个项目的模块结构"，就能看到主 Agent 委派general-purpose子代理工作的日志（[TASK]前缀标识）。

进阶：自定义子代理与多模型路由 📈

自定义子代理只需写一个带 YAML frontmatter 的 Markdown 文件（如放在.claude/agents/目录），然后通过ClaudeSubagentReferences.fromRootDirectory(...)加载：

--- name: code-reviewer description: 代码审查专家，写完代码后主动使用 tools: Read, Grep, Glob, Bash disallowedTools: Edit, Write model: sonnet --- 你是一名资深代码审查员，关注代码质量与安全……

多模型路由通过 frontmatter 的model字段实现：简单任务配haiku省钱提速，复杂分析配opus；也支持provider:model格式（如openai:gpt-4o、ollama:llama3）把不同子代理路由到不同厂商的模型。远程 A2A（Agent-to-Agent）协议子代理则由独立的 spring-ai-agent-utils-a2a 模块提供，可与本地子代理混用。

最佳实践清单 ✅

1. 单一职责：每个子代理只做一件事，描述里写清"何时使用"；
2. 最小权限：只读场景务必用disallowedTools显式拒绝写操作；
3. 模型分级：快速搜索用便宜模型，深度分析用强模型；
4. 并行优先：无依赖的子任务一次性并行委派；
5. 提示词要具体：子代理看不到用户意图，要明说"只做研究"还是"要写代码"。

延伸阅读

• TaskTools.md —— TaskTool 完整文档：背景任务、自定义 TaskRepository、API 参考
• Subagent.md —— 子代理 SPI 框架：如何接入 A2A、MCP 等自定义协议
• spring-ai-agent-utils-common —— 子代理核心抽象（SubagentDefinition / Resolver / Executor）所在模块

• 人工智能
• AI Agent
• 工具调用
• AI 技能
• 代码智能体
• 后端