什么时候使用多智能体编排
当任务可以拆成边界清晰的子任务，或者不同子任务需要不同的智能体配置时，可以使用多智能体编排。 常见场景包括：- 并行处理互不依赖的资料或子任务，最后由协调智能体汇总结果。
- 将代码审查、资料检索等工作交给配置了相应工具或技能的智能体。
- 为同一类任务配置多个智能体副本，分别处理不同输入。
- 需要独立查看或审计不同子任务的执行轨迹。
协调智能体与子线程
创建会话时，平台会创建一个协调线程（coordinator thread）。 它是会话的默认执行入口，使用会话级接口提交的用户输入由它处理。 协调智能体决定委派后，平台会在同一个会话中创建子线程。 子线程执行协调智能体委派的子任务，并将结果返回给协调智能体。
协调线程和子线程属于同一个会话，但每条线程都有自己的状态、历史事件和实时事件流。
共享执行环境不等于共享完整的模型上下文。
协调智能体可以创建子线程，子线程不能继续创建下一级线程。
配置可委派的智能体
在创建或更新协调智能体时，通过multiagent.agents 声明它可以委派的智能体。
type 用来区分来源类型：
type: "agent"：引用另一个已经存在的智能体。id填写该智能体的 ID；version可选，省略时平台会在写入时固定它的最新版本。type: "self"：引用协调智能体自己，让子线程复用协调智能体当前固定的版本和配置，不需要填写id。
agents 至少包含 1 个条目，最多包含 20 个条目。
重复引用同一个智能体、显示名重复、引用已归档的智能体，或引用本身配置了 multiagent 的智能体，都会在写入时报错。
之后更新被引用的智能体，不会改变已经保存的委派配置。
如果要让协调智能体使用被引用智能体的新版本，需要更新协调智能体，生成新的不可变版本。
创建协调智能体
下面演示创建一个协调智能体，并在创建时固定它可以委派的智能体名单。 这个请求不会创建子线程，也不会创建名单中的智能体：agent_researcher 需要替换为当前项目中实际存在的智能体 ID。
智能体名单中的 self 条目允许它再创建一个复用自身当前版本和配置的子线程。
id 是协调智能体的 ID，后续创建会话时需要传入。
响应中的 multiagent.agents 展示平台已经固定的智能体版本；self 条目在写入时解析为协调智能体自身，因此名单中还会包含一条指向协调智能体自身 ID 和版本的记录。
以下响应只展示本页后续需要理解的字段，具体响应字段以正式 API 契约为准：
id，后续创建会话时使用：
创建并运行会话
创建会话
使用上一步创建的协调智能体和一个执行环境创建会话。ENVIRONMENT_ID 应替换为实际执行环境的 ID。
id 是后续发送任务和查询线程时使用的会话 ID：
发送任务
通过会话的事件接口发送user.message。
消息内容使用 content 数组，每个内容块声明自己的 type。
spawn_subagent 时，平台会在同一个会话中创建子线程并启动执行。
同步和异步委派
用户控制委派的方式是配置和指令，而不是填写工具参数。spawn_subagent 是模型在运行时调用的工具，不是客户端直接调用的 REST API。
如果需要客户端精确控制子任务输入和执行顺序，应改为客户端自行编排多个会话调用，而不是使用多智能体委派。
一次委派的工具输入示例如下：
agent_type是必填参数，没有默认值，填写委派列表中智能体的名称（显示名），模型调用时必须显式指定；description是用于标识任务的短标签；prompt是子线程执行任务所需的完整说明；run_in_background: false表示同步委派，也是默认行为；run_in_background: true表示异步委派。
同步委派
同步委派会等待子线程返回报告、进入空闲状态或终止，然后协调智能体继续执行。 当后续步骤必须依赖子线程的结果时，适合使用同步委派。异步委派
异步委派会在子线程创建并开始执行后立即返回。 子线程完成一轮后，会将报告发送回协调智能体，协调智能体可以继续执行其他工作，或等待消息。 异步委派的工具结果是一段文本，包含子线程 ID 和后续处理说明：idle，不会自动删除；协调智能体可以调用 delete_subagent 终止它，终止后线程状态变为 terminated。
如果后续仍需要该子线程处理相关任务，协调智能体可以通过 send_message 复用它继续发送消息；客户端暂不支持直接向子线程发送消息。
智能体之间发送消息
KHA 中的消息都经过协调线程中转。 协调线程可以向指定子线程发送消息，也可以向所有子线程广播；子线程只能把结果或问题发回协调线程。 子线程之间不能直接通信，也不能跨会话发送消息。发送消息：send_message
协调智能体可以向指定子线程发送消息，也可以向所有子线程广播：
agent_id 设置为 all：
等待消息：wait_for_message
协调智能体或支持消息协作的异步子线程可以使用 wait_for_message 等待消息：
agent.thread_message_received 事件的 payload 中读取来源线程（from_session_thread_id）和来源智能体显示名（from_agent_name）。
如果需要查看子线程的完整执行过程，应读取线程历史事件，而不是依赖 wait_for_message 的返回内容。
共享资源与上下文隔离
智能体、会话和线程分别管理不同范围的配置：
子线程使用被选中智能体的固定版本及其配置。
会话绑定的文件、凭据库和记忆库等资源通过会话配置管理，具体绑定方式参阅 启动会话。
会话级智能体配置覆盖
agent_overrides 只影响当前会话，不修改智能体资源或委派列表中的其他智能体。
会话级覆盖配置只作用于协调线程，不会传递给子线程；子线程始终使用委派配置中固定的智能体版本。
观察线程和事件
发送任务后，可以先通过会话级事件流观察协调线程的整体进展。 要查看子线程的详细活动，需要先列出会话中的线程，再使用返回的id 查询对应线程。
列出会话中的线程
id 是后续查询线程的来源。
协调线程没有 parent_thread_id，子线程通过该字段指向父线程。
如果响应包含 next_page_token，继续请求下一页，不要假定当前页面包含所有线程。
查看线程详情
将$THREAD_ID 设置为线程列表中目标线程的 id：
status 可以帮助你判断线程是否仍在运行：
读取线程历史事件
session.thread_created 只写入协调线程的历史，需要通过会话级事件流（协调线程）观察，不会出现在子线程自己的历史事件中。
以上响应只展示与多智能体编排相关的事件字段。
完整事件类型、字段和分页规则见 事件流。
订阅线程实时事件
id: 行是恢复游标（数值），断线后可用它从断点继续订阅，详见事件流。
事件中的 session_thread_id 用于判断事件属于哪条线程。
线程游标只对对应线程的事件流有效，不能用于其他线程或会话。
归档子线程
子线程完成并处于idle 状态后，可以归档它：
204 No Content。
归档不会删除线程的历史事件。
一次委派的事件链
一次异步委派通常可以按以下顺序观察：最佳实践
为子线程设置清晰的任务边界
在prompt 中明确输入、输出、成功条件和需要保留的证据。
例如：
只配置实际需要的智能体
委派列表中只加入协调智能体确实需要委派的智能体。 智能体数量过多会增加模型的选择空间和配置维护成本。约定报告格式
可以要求子线程按固定格式返回：使用线程级事件流审计
不要只查看协调智能体的最终结果。 需要调试或审计时，列出会话中的线程，并独立读取目标子线程的历史事件和实时事件。下一步
智能体
配置智能体、工具和多智能体委派能力。
会话
创建会话并发送任务输入。
事件流
读取历史事件、订阅 SSE 并处理断线续读。
金融投研智能体
查看官方投研多智能体团队的完整设计。