Managed Agents 允许一个 Agent 以协调者（coordinator）身份管理和委派任务给其他 Agent，实现多 Agent 协作。协调者 Agent 可以创建子 Agent 线程、发送消息、等待结果，从而将复杂任务分解为多个独立的子任务并行或串行执行。
核心概念
Managed Agents 建立在 Session Thread 模型之上。一个 Session 内可以同时存在多个 Thread，每个 Thread 绑定一个独立的 Agent 快照，拥有独立的对话历史和执行上下文。
| 概念 | 说明 |
|---|
| Coordinator | 协调者线程，每个 Session 有且仅有一个。使用 Session 创建时指定的 Agent，负责编排和分派任务 |
| Child thread | 子线程，由 coordinator 通过工具调用创建。绑定 multiagent.agents 花名册中的某个 Agent，独立执行任务并通过 send_to_parent 回报结果 |
| Session Thread | 线程实体，ID 前缀为 sthr_。包含 role（coordinator 或 child）、独立的 Agent 快照和状态 |
| Mailbox | 线程间消息队列，CAS 内部管理。消息入队后由调度器按目标线程状态自动分发 |
配置 Managed Agent
要启用 managed agents 能力，需要在 Agent 配置中设置 multiagent 字段：
curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"name": "task-coordinator",
"model": "ultimate",
"system": "你是一个任务协调者，负责将任务分配给合适的子 Agent。",
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write"]
}
],
"multiagent": {
"type": "coordinator",
"agents": [
{"type": "agent", "id": "agent_019f000000000000000000000000001a", "name": "Research Agent"},
{"type": "agent", "id": "agent_019f000000000000000000000000002b"},
{"type": "self"}
]
}
}'
multiagent 字段说明
| 字段 | 类型 | 必选 | 说明 |
|---|
type | string | 是 | 必须为 "coordinator" |
agents | array | 是 | 可委派的 Agent 花名册，1-20 个唯一条目 |
agents 数组元素支持三种格式：
| 格式 | 示例 | 说明 |
|---|
对象 type: "agent" | {"type": "agent", "id": "agent_xxx", "version": 2, "name": "Reviewer"} | 引用其他 Agent。id 必填，version 和 name 可选 |
对象 type: "self" | {"type": "self"} | 引用 coordinator 自身作为子 Agent |
| 字符串简写 | "agent_xxx" | 等价于 {"type": "agent", "id": "agent_xxx"} |
配置 multiagent 时，tools 中必须包含 agent_toolset_20260401 类型的工具配置项。系统会在运行时自动注入 create_agent、send_to_agent、list_agents、Agent 四个控制工具。
Coordinator 控制工具
当 Session 的 Agent 配置了 multiagent 且当前线程角色为 coordinator 时，以下工具被自动注入：
create_agent
创建一个新的子 Agent 线程并发送初始任务。调用后立即返回线程 ID，不等待子 Agent 完成。
| 参数 | 类型 | 必选 | 说明 |
|---|
agent_id | string | 是 | 花名册中的 Agent ID 或 "self"。取值范围由 multiagent.agents 决定 |
agent_name | string | 否 | 为子线程指定的显示名称 |
task | string | 是 | 发送给子 Agent 的初始任务描述 |
"Created agent thread: sthr_019f..."
Agent
委派一个聚焦任务给子 Agent 并同步等待其返回结果。这是一个阻塞式工具——coordinator 的 turn 会暂停直到子 Agent 完成（调用 send_to_parent）或被中断。
| 参数 | 类型 | 必选 | 说明 |
|---|
agent_id | string | 是 | 花名册中的 Agent ID 或 "self" |
prompt | string | 是 | 委派给子 Agent 的任务提示 |
send_to_agent
向已存在的子线程发送后续消息。
| 参数 | 类型 | 必选 | 说明 |
|---|
thread_id | string | 是 | 目标子线程 ID（sthr_ 前缀） |
message | string | 是 | 发送的消息内容 |
"Message queued for agent thread: sthr_019f..."
list_agents
列出当前 Session 中所有子线程的状态、待处理消息数以及可用的 Agent 花名册。无需参数。
Child 控制工具
当线程角色为 child 时，系统自动注入一个工具：
send_to_parent
向 coordinator 发送结果、状态更新或提问。调用后子线程会变为 idle 状态。
| 参数 | 类型 | 必选 | 说明 |
|---|
message | string | 是 | 发送给 coordinator 的消息 |
Session Thread 生命周期
创建 Session
客户端创建 Session 并引用配置了 multiagent 的 Agent。
启动 Turn
客户端发送 user.message 事件，CAS 自动创建 coordinator 线程（role: coordinator）。
Coordinator 委派任务
模型调用 create_agent 或 Agent 工具，CAS 创建 child 线程，将任务消息入队到 mailbox。
Child 执行
CAS 调度器将 mailbox 消息分发给 child 线程，CAW 加载 child 的 Agent 快照独立执行。
Child 回报结果
Child 调用 send_to_parent，消息通过 mailbox 发回 coordinator。Child 线程变为 idle。
Coordinator 继续
Coordinator 收到 child 的回报，综合结果继续处理或发起新的委派。
Session 空闲
当所有运行中的线程都已停止，Session 整体回到 idle 状态。
线程事件
在 managed agents 场景下，事件流中会出现以下新事件类型：
| 事件类型 | 说明 |
|---|
session.thread_created | 创建了新的子线程 |
session.thread_status_running | 线程开始执行 |
session.thread_status_idle | 线程执行完成或暂停 |
session.thread_status_terminated | 线程被归档/终止 |
agent.thread_message_sent | 线程间发送消息（coordinator → child 或后续消息） |
agent.thread_message_received | 线程间接收消息（child → coordinator） |
session_thread_id 字段标识所属线程。可以通过 列出线程事件 和 线程事件流 接口按线程维度筛选事件。
| 项目 | 限制 |
|---|
| 每个 Agent 最多配置的子 Agent 数量 | 20 个唯一条目 |
| 每个 Session 最多并发线程数 | 25 个（含 coordinator） |
| Session 空闲条件 | 所有线程必须停止运行 |
下一步
配置 multiagent
在创建 Agent 时设置 multiagent 字段。
Agent 数据结构
multiagent 与 agent entry 字段参考。
列出 Session Threads
查看 Session 中的所有线程。
Session Thread 对象
Session Thread 对象字段与生命周期。
