将任务委托给子代理
子代理让一个主智能体把部分工作异步委托给已有的智能体实例。主智能体可以发起委托、查询结果或取消任务，并在取得结果后继续回答用户。
主智能体在需要时才发起子代理任务。子代理返回状态和结果后，主智能体继续组织最终回答。子代理不是持续等待任务的常驻工作进程，也不会接管主智能体与用户之间的对话。
这种方式适合把专业任务交给已经单独验证的智能体实例，也适合并行处理彼此独立的任务。它提供受管理的任务委托，不是用于绘制任意节点、分支和循环的工作流编辑器。
区分子代理、可选的外部编排和工具调用
在扩展一体化智能体运行与协同平台（AgentWorks）智能体或把智能体接入外部系统时，以下三种方式都可能把工作交给另一个执行方，但控制位置、目标对象和下一步由谁决定并不相同。
| 方式 | 控制位置 | 下一步由谁决定 | 适用情况 |
|---|---|---|---|
| 子代理 | AgentWorks 的一次平台运行中 | 主智能体的模型根据提示词、用户输入以及子代理名称和描述决定是否委托 | 动态选择专业智能体，并异步取得结果 |
| 外部编排（可选） | AgentWorks 之外；通常通过 Invoke API 调用智能体实例 | 业务应用或编排系统按照固定状态和规则决定下一步 | 精确控制顺序、分支、并行、重试和终止条件 |
| MCP | AgentWorks 发起调用，外部 MCP Server 执行工具 | 主智能体的模型选择工具，MCP Server 执行具体能力 | 调用工具、API 或数据资源，而不是委托给另一个智能体实例 |
配置 子代理时，只能选择已经存在的 AgentWorks 智能体实例，不能填写外部 Agent Card 或 A2A 服务地址。因此，子代理的 后台任务是 AgentWorks 管理的实例间委托，不是 A2A Task。需要组合独立部署的外部智能体时，请把协调逻辑保留在外部系统中，并通过目标部署提供的 Invoke API 调用 AgentWorks。如果接入方是需要双向长连接的自有消息系统，可以使用 WebSocket。相关接口边界参见选择目标部署提供的集成接口。
理解模型驱动的动态委托
添加子代理关联后，主智能体的模型在每次运行中根据当前输入、系统提示词以及子代理的名称和描述重新判断是否委托。下图展示可能发生的运行行为，不表示 AgentWorks 控制台提供可以编辑的固定工作流。
添加关联不表示每次运行都会调用子代理，也不创建由构建者定义的固定路由、重试次数或终止条件。平台负责后台任务的创建、状态和结果传递；模型决定是否委托以及如何使用返回结果。
判断是否需要子代理
根据任务是否需要独立能力、并行委托或固定流程控制，选择单个智能体、子代理或可选的外部编排。
在一个智能体中完成
同一套指令和上下文能够完成任务时，在一个智能体中使用模型和工具。
使用子代理
以下情况适合使用子代理：
- 某部分任务需要独立的提示词、模型或能力，并且已经有可复用的智能体实例。
- 多个独立任务可以并行执行，再由主智能体汇总。
添加子代理后，通过固定测试验证委托目标和汇总结果。
仅在需要固定流程控制时使用外部编排
需要精确定义节点顺序、条件分支、重试和状态转换时，由 AgentWorks 之外的编排系统控制流程，并通常通过 Invoke API 按需调用智能体实例。参见区分平台单次运行和可选的外部编排。
让主智能体准确选择子代理
主智能体需要从名称、描述和系统提示词中判断每个子代理适合处理什么任务。配置子代理名称、描述和主智能体系统提示词时，请写明职责、输入、预期结果和不适用范围，不要只写“专业助手”或“处理复杂任务”等宽泛描述。
| 配置内容 | 建议写法 | 作用 |
|---|---|---|
| 子代理名称 | 使用可以区分职责的名称，例如“合同条款审查”或“工单分类” | 帮助主智能体快速区分多个子代理 |
| 子代理描述 | 说明处理的任务、所需输入、返回结果和不处理的情况 | 限定委托范围，减少不必要的调用 |
| 主智能体系统提示词 | 说明何时直接回答、何时委托，以及并行委托后如何汇总 | 明确何时委托以及怎样使用返回结果 |
| 结果要求 | 约定风险等级、证据、字段或其他必要输出 | 让主智能体更容易核对和使用子代理结果 |
例如，可以把合同审查子代理描述为：
检查输入的合同条款，列出风险条款、风险等级和判断依据。不回答合同之外的问题，不执行合同修改或审批操作。
配置完成后，需要用固定测试分别覆盖直接回答、单个子代理、多个子代理和异常处理。模型对同类输入的选择可能有所变化，不能只用一次成功调用判断配置已经稳定。
配置子代理
准备并独立验证要委托的智能体实例，再把该实例添加到主智能体模板。
准备子代理实例
- 为专业任务创建一个智能体模板。
- 创建对应的智能体实例。
- 直接测试该实例，确认模型、提示词、凭证和插件都能完成预期任务。
- 使用清晰的实例名称和描述说明它擅长的任务和不应处理的任务。
子代理选择器引用智能体实例，而不是智能体模板。修改子代理来源的智能体模板后，应先更新并重新测试该子代理实例。
通过子代理委托运行时，主智能体不会代替业务系统响应用户工具包产生的工具中断。不要让子代理的关键任务依赖用户工具包；需要在平台内执行工具时，直接为该子代理配置平台工具包、MCP 或沙箱。
将实例添加为子代理
- 创建或编辑主智能体模板。
- 打开 插件配置，单击 添加插件。
- 在 类型 中选择 子代理。
- 在 选择智能体实例 中选择已经验证的实例。
- 按需添加其他子代理。如果正在创建主智能体模板，选择 创建智能体模板；如果正在编辑主智能体模板，选择 保存修改。
- 在主智能体模板详情页打开 插件，确认每个子代理关联的实例名称和 ID。
- 创建或更新主智能体实例。
子代理直接引用已有智能体实例，不使用能力模板和能力实例选择。
运行和管理委托
完成配置后，通过实际渠道任务验证委托，并结合审批和后台任务状态管理或排查运行过程。
通过渠道验证委托
子代理委托使用主智能体所在渠道的运行上下文。先把主智能体实例接入飞书或 QQ；如果渠道账号绑定的是智能体模板，测试用户先发送 /init 获得专属实例。
使用固定输入验证以下委托结果：
- 任务不需要子代理：主智能体直接回答，不创建 后台任务。
- 任务只属于一个子代理：只创建对应实例的后台任务。任务完成后，主智能体使用子代理结果回答。
- 任务可以拆给多个子代理：为预期实例分别创建后台任务。主智能体等待必要结果并完成汇总。
- 子代理请求审批或执行失败：后台任务显示对应状态。主智能体在审批完成或取得终态后继续，不把未完成结果当作成功结果。
每次测试都应核对后台任务中的子代理实例 ID、任务状态和结果，并检查主智能体的最终回答是否实际使用了子代理结果。需要进一步定位模型选择或工具调用时，打开主智能体和子代理实例的 Trace。
处理子代理的确认审批
子代理执行受权限控制的操作时，可能暂停并请求批准。在飞书渠道中，审批卡片会发送到主智能体所在会话；对应后台任务显示为 等待审批。
- 在飞书会话中核对审批卡片中的操作和参数。
- 选择 ✅ 允许、⭐ 加白执行 或 ❌ 拒绝。允许前确认操作符合当前用户权限和业务规则。
- 回到智能体实例的 后台任务，确认任务从 等待审批 恢复运行或结束。
- 等待主智能体取得子代理结果并完成回复，再检查相关 Trace。
这里处理的是子代理发出的确认型审批，不会执行用户工具包中的业务代码。用户工具包产生的工具中断仍需通过 Invoke API 或 WebSocket 接入的业务系统返回 RESPOND 或 ERROR。因此，通过渠道运行的子代理需要平台内执行工具时，应使用平台工具包、MCP 或沙箱。
理解后台任务状态
后台任务状态用于判断委托正在等待、运行、等待审批还是已经结束。
| 状态 | 含义和处理 |
|---|---|
| 等待中 | 委托已创建，等待子代理开始执行；不要立即重复提交同一任务 |
| 运行中 | 子代理正在执行；等待完成后再判断是否需要重试 |
| 等待审批 | 子代理运行需要批准；在飞书会话中核对并处理审批卡片，再继续观察任务 |
| 已完成 | 子代理已返回结果；确认主智能体实际使用了该结果 |
| 失败 | 直接测试子代理实例，并检查其 Trace、凭证和插件 |
| 已取消 | 任务不会继续等待结果；根据业务需要重新发起新任务 |
后台任务记录用于确认委托已经发生；要验证最终结果，还应核对主智能体的回答和相关 Trace。
排查子代理委托
- 没有后台任务：确认主智能体模板保存了 子代理 关联、主智能体实例已更新，并让测试输入明确需要该子代理的专长。
- 提示主智能体实例未初始化：模板绑定渠道用户先发送
/init。 - 长时间处于 等待中 或 运行中：不要连续重复提交；先检查子代理实例是否可直接运行，再查看 Trace 和后台任务状态。
- 处于 等待审批：在主智能体所在飞书会话中查找审批卡片，选择 ✅ 允许、⭐ 加白执行 或 ❌ 拒绝 后，再确认任务是否继续。
- 任务处于 失败：直接调用子代理实例复现问题，检查模型凭证、外部能力和输入是否有效。
- 后台任务持续运行，但子代理通过 API 单独测试正常：检查子代理是否调用了用户工具包；委托任务应改用平台工具包、MCP 或沙箱完成所需操作。
- 委托成功但最终回答未使用结果：在主智能体提示词中说明何时委托、需要等待哪些结果以及如何汇总，并重新执行固定测试。