Subagents

说明： 原先的 Spring Boot 示例模块 agentscope-examples/multiagent-patterns/ 已在 2.0 包重构中移除。请以本文中的代码片段作为参考实现。其他可运行示例见 agentscope-examples/documentation/。

​

为何使用子智能体？

​

工作方式

1. 编排智能体拥有名为 Task 的工具（以及可选的 TaskOutput，用于后台任务），还可拥有直接工具（如 glob_search、grep_search、web_fetch）处理简单单步工作。
2. 当用户请求复杂或偏某领域时，编排智能体调用 Task 工具，传入：
   • subagent_type：要运行的子智能体（如 codebase-explorer、web-researcher）
   • prompt：发给该子智能体的任务描述
3. 系统按类型查找子智能体，在独立上下文（其系统提示与工具）中执行该 prompt，并将子智能体的回复作为工具结果返回。
4. 编排智能体根据该结果（及可选的其他工具结果）综合出对用户的最终回答。

​

定义子智能体

​

1. Markdown（基于文件）

---
name: codebase-explorer
description: 用于快速探索代码库。用于查找文件、搜索代码、分析结构。工具：glob_search、grep_search。
tools: glob_search, grep_search
---

你是代码库探索专家，负责高效探索和分析代码库。

**能力：**
- 使用 glob 模式查找文件
- 使用正则搜索文件内容
- 分析项目结构与依赖

**指南：**
- 先用 glob_search 了解布局，再用 grep_search 查内容
- 提供简洁、结构化的发现

• name：唯一标识；编排智能体在调用 Task 工具时用此作为 subagent_type。
• description：说明编排智能体（及模型）何时委托给该子智能体；写清楚便于主智能体正确选择。
• tools：该子智能体可用的工具名（逗号分隔）。仅这些工具会被挂载，其它不可用，便于聚焦与安全。

​

2. API（编程式）

ReActAgent dependencyAnalyzerReAct = ReActAgent.builder()
        .name("dependency-analyzer")
        .description("分析项目依赖。用于版本冲突、过时库、安全等问题。")
        .model(model)
        .sysPrompt(DEPENDENCY_ANALYZER_SYSTEM_PROMPT)
        .toolkit(depToolkit)  // 例如仅 glob_search、grep_search
        .memory(new InMemoryMemory())
        .build();

TaskToolsBuilder.builder()
        .model(model)
        .defaultToolsByName(defaultToolsByName)
        .subAgent("dependency-analyzer", dependencyAnalyzerReAct)
        // ... addAgentResource(...) 用于 Markdown 规格
        .build();

​

Task 工具构建器（AgentScope 示例）

1. TaskToolsBuilder.builder()
   • model：从 Markdown 规格构建 ReActAgent 时使用。
   • defaultToolsByName：工具名 → 实例的映射（如 glob_search、grep_search、web_fetch）。Markdown 规格在 tools 字段中按名称引用。
   • taskRepository：用于后台执行；即使只做同步 Task 调用也需配置。
   • subAgent(type, ReActAgent)：注册一个编程式子智能体。
   • addAgentResource(Resource)：从 classpath 或文件资源加载一个 Markdown 规格（如 classpath:agents/codebase-explorer.md）。
2. build()
   将所有 Markdown 规格解析为 ReActAgent（通过 AgentSpecLoader 与工厂），与编程式子智能体合并，返回 TaskToolsResult，包含：
   • taskTool()：注册到编排智能体工具集的 Task 工具。
   • taskOutputTool()：用于查询或获取后台任务结果的 TaskOutput 工具。
3. 编排智能体工具集
   在编排智能体的 Toolkit 上注册 Task 与 TaskOutput，以及编排智能体可直接使用的工具（glob、grep、web_fetch）。编排智能体的系统提示应说明何时委托（何种请求用哪个 subagent_type）、何时使用直接工具。

​

示例：技术尽调助手

• 编排智能体的系统提示说明何时使用各子智能体、何时使用直接工具；拥有 Task、TaskOutput、glob_search、grep_search、web_fetch。
• Markdown 规格位于 src/main/resources/agents/*.md，通过 TaskToolsBuilder.addAgentResource(res) 加载。
• dependency-analyzer 以 ReActAgent 构建，通过 TaskToolsBuilder.subAgent("dependency-analyzer", dependencyAnalyzerReAct) 注册。

@Autowired
OrchestratorService orchestratorService;

String answer = orchestratorService.run(
    "分析该代码库的技术债务并调研 Spring AI 文档");

​

子智能体与其他模式

• Supervisor：监督者模式也是中心智能体将专家当工具调用，但是每个专家一个工具（如 schedule_event、manage_email），角色通常更少、更稳定。子智能体使用单一 Task 工具，通过类型和 prompt 参数选择子智能体，支持大量子智能体（含 Markdown 定义）和可选后台执行。
• Agent as Tool：Agent as Tool 将一个子智能体注册为一个工具、固定名称与签名。子智能体使用分发器（Task 工具）按名称选择子智能体并传入自由格式任务字符串；子智能体常通过 Markdown 批量定义。
• Routing：路由对输入分类并转发给一个或多个专家再综合结果，通常不维护长对话。子智能体编排智能体维护对话，可在一轮或多轮中多次调用 Task（可能不同 subagent_type）。

​

最佳实践

• 写清子智能体描述：编排智能体依赖 description（及自身系统提示）决定调用哪个子智能体。包含触发场景与示例（如“用于查找文件、搜索代码、分析结构”）。
• 限制每子智能体工具：在 Markdown 中只列出该子智能体需要的工具，行为更可预测、误用风险更小。
• 系统提示要聚焦：每个 Markdown 正文即该子智能体的系统提示；明确职责、步骤与输出格式，便于返回有用、一致的结果。
• Markdown 规格纳入版本控制：将 agents/*.md 放入仓库，便于团队在不改代码的情况下增删改子智能体。

​

相关文档

• Supervisor - 一个监督者，每个专家一个工具
• Agent as Tool - 将智能体注册为工具
• Pipeline - 顺序与并行组合