AstrBot/docs/zh/use/subagent.md

Agent Handsoff 与 Subagent

SubAgent 编排是 AstrBot 提供的一种高级 Agent 组织方式。它允许你将复杂的任务分解给多个专门的子 Agent（SubAgent）来完成，从而降低主 Agent 的 Prompt 长度，提高任务执行的成功率。

在 v4.14.0 引入，目前是实验性功能，未稳定。

动机

在传统的架构中，所有的工具（Tools）都直接挂载在主 Agent 上。当工具数量较多时，会带来以下问题：

1. Prompt 爆炸：主 Agent 需要在 System Prompt 中包含所有工具的描述，导致上下文占用过多。
2. 调用失误：面对大量工具，LLM 容易混淆工具用途或产生错误的调用参数。
3. 逻辑复杂：主 Agent 既要负责对话，又要负责组织和调用大量工具，负担过重。

通过 SubAgent 编排，主 Agent 仅负责与用户对话以及任务委派。具体的工具调用由专门的 SubAgent 负责。

工作原理

1. 主 Agent 委派：开启 SubAgent 模式后，主 Agent 只能看到一系列名为 transfer_to_<subagent_name> 的委派工具。
2. 任务移交：当主 Agent 认为需要执行某项任务时，它会调用对应的委派工具，将任务描述传递给 SubAgent。
3. 子 Agent 执行：SubAgent 接收到任务后，使用其挂载的工具进行操作，并将结果整理后回传给主 Agent。
4. 结果反馈：主 Agent 收到 SubAgent 的执行结果，继续与用户对话。

配置方法

在 AstrBot WebUI 中，点击左侧导航栏的 SubAgent 编排。

1. 启用 SubAgent 模式

在页面顶部开启“启用 SubAgent 编排”。

2. 创建 SubAgent

点击“新增 SubAgent”按钮：

• Agent 名称：用于生成委派工具名（如 transfer_to_weather）。建议使用英文小写和下划线。
• 选择 Persona：选择一个预设的 Persona，即人格，作为该子 Agent 的基础性格、行为指导和可以使用的 Tools 集合。你可以在“人格设定”页面创建和管理 Persona。
• 对主 LLM 的描述：这段描述会告诉主 Agent 这个子 Agent 擅长做什么，以便主 Agent 准确委派。
• 分配工具：选择该子 Agent 可以调用的工具。
• Provider 覆盖（可选）：你可以为特定的子 Agent 指定不同的模型提供商。例如，主 Agent 使用 GPT-4o，而负责简单查询的子 Agent 使用 GPT-4o-mini 以节省成本。

最佳实践

• 职责单一：每个 SubAgent 应该只负责一类相关的任务（如：搜索、文件处理、智能家居控制）。
• 清晰的描述：给主 Agent 的描述应当简洁明了，突出该子 Agent 的核心能力。
• 分层管理：对于极其复杂的任务，可以考虑多级委派（如果需要）。

已知问题

SubAgent 系统目前是实验性功能，未稳定。

1. 目前无法隔离人格的 Skills。
2. 子 Agent 的对话历史暂时不会被保存。