SubAgent

SubAgent 是被另一个 Agent 调用的后台 Agent。它不会直接接管聊天，也不会自己提交前台回复；它接收一个明确的子任务，在受限工作区中完成工作，然后把摘要、发现或产物引用返回给父 Agent。

可以把它理解成“临时请一个专门角色帮忙”。父 Agent 仍负责最终判断和聊天提交，SubAgent 只负责局部任务。

适合什么场景

SubAgent 适合拆出边界清楚的小任务：

• 整理一段长聊天中的相关线索。
• 检查草稿是否符合角色、格式或禁忌。
• 为主 Agent 准备摘要、提纲或候选方案。
• 并行处理几个互不依赖的小问题。
• 使用不同模型或不同预设完成专门工作。

不建议为了简单回复使用 SubAgent。委派会增加一次模型运行和时间线复杂度；如果主 Agent 自己能完成，通常直接完成更稳。

它如何工作

一次委派大致是这样：

主 Agent 看到可调用的 SubAgent
  ↓
主 Agent 用 agent.delegate 发起子任务
  ↓
SubAgent 在后台创建自己的 invocation 和任务工作区
  ↓
SubAgent 阅读任务说明、必要摘要和允许访问的文件
  ↓
SubAgent 用 task.return 返回结果
  ↓
主 Agent 用 agent.await 等待或查看结果
  ↓
主 Agent 决定如何使用这些结果，并提交最终聊天内容

时间线会显示委派、等待、子任务开始、返回、失败或取消等事件。子任务的中间过程不会写成普通聊天楼层。

相关工具

SubAgent 相关工具有四个：

工具	谁使用	作用
agent.list	父 Agent	查看当前可调用的 Agent
agent.delegate	父 Agent	向指定 Agent 发起子任务
agent.await	父 Agent	等待子任务完成，或查看当前状态
task.return	SubAgent	返回任务结果并结束子任务

task.return 只在子任务运行时出现。普通主 Agent Profile 不应把它手动加入工具列表。

配置一个可用的 SubAgent

一个可被调用的 SubAgent Profile 通常需要这些设置：

设置	建议
可作为 SubAgent	开启
模型绑定	选择可运行模型，不能停在“需要重新配置”
工具权限	按任务需要开放读取、写入、Skill 或世界书工具
系统提示词	说明它擅长什么、应返回什么、哪些事不要做

如果希望所有主 Agent 都能调用它，允许的调用者可以设为 *。如果它只服务某个主 Agent，则建议只允许那个 Profile 调用。

主 Agent 需要什么

主 Agent 如果要委派任务，需要：

• Profile 中允许生成子 Agent。
• 有足够的最大工具调用数和最大轮数。
• 系统提示词中说明什么时候应委派，什么时候应自己完成。

委派不是越多越好。比较稳妥的写法是告诉主 Agent：只有当任务可以清楚拆分，并且 SubAgent 的结果会帮助最终回复时，才发起委派。

子任务说明应该怎么写

好的子任务说明应包含结果目标，而不是只列步骤。

建议包括：

• 任务目标：需要完成什么。
• 上下文：相关角色、片段、文件路径或限制。
• 期望输出：需要摘要、检查结果、草稿，还是结构化发现。
• 预算意识：如果只需要简单结论，不要要求长篇分析。

不建议让 SubAgent 猜父 Agent 的意图。父 Agent 应把需要的背景写清楚。

工作区和结果

SubAgent 会看到经过限制的任务工作区。常见路径包括：

路径	含义
summaries/parent/	父 Agent 提供给子任务的只读摘要
summaries/agents/	其它子任务返回的摘要
summaries/	当前子任务可写的摘要区域
scratch/	当前子任务的临时草稿

SubAgent 返回结果时，可以附带 artifacts。父 Agent 会看到这些引用，再决定是否读取、采纳或忽略。最终进入聊天的内容仍由父 Agent 提交。

并发和预算

委派受 Profile 限制：

• 最大并发子任务限制同一时间运行几个 SubAgent。
• 每次运行最多子任务限制本轮最多发起多少个子任务。
• 每个子任务还可以被分配更小的最大轮数和工具调用数。
• 子任务结果有预算限制，过长结果不适合直接返回给父 Agent。

如果任务经常超时或没有返回结果，通常应先收窄任务说明，而不是简单提高预算。

当前边界

当前已经支持 return-mode SubAgent，但仍有明确边界：

• 还没有用户可用的 agent.handoff。
• 还没有模型可见的任务取消工具。
• SubAgent 不能直接提交聊天消息。
• 子任务失败不会自动让父 Agent 成功；父 Agent 需要根据返回状态决定下一步。
• 群聊场景下的 Agent 运行仍未作为稳定能力开放。

这些边界是为了让父 Agent 始终保留最终责任。SubAgent 应该帮助主流程，而不是让任务变成不可控的后台展开。

常见问题

为什么我看不到某个 SubAgent？
通常是目标 Profile 没有开启“可作为 SubAgent”，或者它限制了允许调用者。

为什么委派时提示模型需要配置？
导入或分享来的 Profile 不会携带本机模型连接。进入那个 Profile，重新选择可用模型后再运行。

为什么 SubAgent 做完了，聊天里没有直接出现它的回复？
这是正常行为。SubAgent 返回结果给父 Agent，父 Agent 再决定最终聊天内容。

什么时候不该用 SubAgent？
如果任务可以在一次普通 Agent 运行里清楚完成，不必拆分。少一层委派，通常也少一层不确定性。