RikkaHub 开发实践：Claude Managed Agents 多智能体会话（Multiagent Sessions）完整指南-开发者社区

人工智能
大模型
AI 应用
移动开发
交互助手

【免费下载链接】rikkahub

RikkaHub is an Android APP that supports for multiple LLM providers.

项目地址：https://gitcode.com/gh_mirrors/ri/rikkahub

本文以 Anthropic Claude Managed Agents 的 Multiagent Sessions 机制为核心，系统讲解如何在单个会话（Session）内由一个协调者（Coordinator）Agent 向多个子 Agent（Subagent）进行委托协作——包括 roster 花名册的声明方式、线程（Thread）模型与状态语义、会话流上的多智能体事件、跨线程工具确认与自定义工具结果的回传，以及最容易踩中的三个陷阱。阅读本文后，你将掌握multiagent: {type: "coordinator", agents: [...]}的完整配置与编程模式，能够为 RikkaHub 这类多 LLM 提供者客户端设计并实现"一个协调者 + 多个专家子代理"的协作式 Agent 工作流。文中所有代码示例与概念均可对照本仓库.agents/skills/claude-api/下的官方技能文档与各语言 SDK 绑定验证。

多智能体会话的核心模型：共享容器、独立线程

在 Managed Agents 体系下，多智能体协作的最小单位是一个Session。一个协调者（coordinator）Agent 可以在同一个 Session 内把任务委托给其他 Agent，而无需启动多个独立会话。其底层模型可以用三条规则概括：

共享容器与文件系统：所有参与协作的 Agent 共用同一个 Session 对应的容器（Container）与文件系统。容器是 Agent 工具（bash、文件操作、代码执行）运行的隔离工作区，而 Agent 主循环运行在 Anthropic 的编排层（orchestration layer）上，通过工具调用作用于容器。详细架构可参考 managed-agents-core.md。
独立线程（Thread）：每个 Agent 运行在各自的线程中。线程是一条"上下文隔离"的事件流，拥有自己独立的对话历史、模型、系统提示词、工具、MCP 服务器与技能（Skills），这些均来自该 Agent 自身的配置，而非协调者的配置。
线程持久化：线程是持久存在的。协调者可以给早前调用过的子 Agent 发送后续消息（follow-up），该子 Agent 会保留此前轮次的对话记忆继续工作——这意味着你可以先让子 Agent 完成第一阶段任务，再基于其结果追加第二阶段指令。

关于 beta 头：SDK 会在所有client.beta.{agents,sessions}.*调用上自动附加managed-agents-2026-04-01beta 头，使用多智能体功能无需额外手动添加任何头部。这个头同时启用 Agents、Environments、Sessions、Events、Session Resources、Session Threads、Outcomes、Multiagent、Vaults、Credentials、Memory Stores、Deployments 等整组能力，详见 managed-agents-overview.md。

在协调者上声明 roster 花名册

位置：Agent 顶层字段，不是 tools 条目

multiagent是agents.create()/agents.update()上的一个顶层字段，不是tools[]数组里的一个条目。agents字段用于列出 1–20 个 roster 条目。sessions.create()上不需要做任何改动——roster 在创建会话时从协调者的配置中解析得出。这也是 Managed Agents "Agent 先行"的铁律在协作场景下的延续：先创建 Agent（一次），再让 Session 引用它（每次运行）。关于该生命周期模式的完整论述见 managed-agents-core.md 的 "Agents" 一节。

orchestrator = client.beta.agents.create( name="Engineering Lead", model="claude-opus-4-8", system="You coordinate engineering work. Delegate code review to the reviewer and test writing to the test agent.", tools=[{"type": "agent_toolset_20260401"}], multiagent={ "type": "coordinator", "agents": [ reviewer.id, # bare string — latest version {"type": "agent", "id": test_writer.id, "version": 4}, # pinned version {"type": "self"}, # the coordinator itself ], }, ) session = client.beta.sessions.create(agent=orchestrator.id, environment_id=env.id)

roster 条目的三种形状

Roster 条目	形状	说明
字符串简写	`"agent_abc123"`	引用某个已存储 Agent 的最新版本。
Agent 引用	`{type: "agent", id, version?}`	省略`version`表示在协调者保存时锁定其当时的最新版本。
自身	`{type: "self"}`	协调者可以派生出自己的副本（copies）。

覆盖规则与限制

如果 Session 是通过agent_with_overrides创建的（会话级 Agent 配置覆盖，见 managed-agents-core.md 的 "Override agent configuration for a session" 一节），这些覆盖只作用于协调者及其{type: "self"}副本。
通过 ID 引用的 roster Agent始终使用自己创建时的配置——会话级覆盖不会传播到它们身上。
roster 最多20 个唯一 Agent；协调者可以为每个 Agent派生多个副本（multiple copies）。
仅允许一层委托（One level of delegation only）：子 Agent 若再声明自己的multiagentroster，深度 > 1 的层级会被直接忽略，不会级联。

线程模型：主线程与每线程端点

Session 级的事件流是primary thread（主线程）——它展示协调者的完整轨迹（trace），外加子 Agent 活动的压缩视图（线程状态转换和跨线程消息，不包含子 Agent 的每一次工具调用）。如果你需要深入某个子 Agent 的具体活动，需要使用下面的每线程端点（per-thread endpoints）：

操作	HTTP	SDK（`client.beta.sessions.threads.*`）
列出线程	`GET /v1/sessions/{sid}/threads`	`.list(session_id)`
检索单个线程	`GET /v1/sessions/{sid}/threads/{tid}`	`.retrieve(thread_id, session_id=...)`
归档线程	`POST /v1/sessions/{sid}/threads/{tid}/archive`	`.archive(thread_id, session_id=...)`
列出线程事件	`GET /v1/sessions/{sid}/threads/{tid}/events`	`.events.list(thread_id, session_id=...)`
流式线程事件	`GET /v1/sessions/{sid}/threads/{tid}/stream`	`.events.stream(thread_id, session_id=...)`

SessionThread 对象字段

每个SessionThread携带以下字段：

id：线程 ID。
status：running|idle|rescheduling|terminated。
agent：该线程所运行 Agent 配置的解析快照（resolved snapshot）——包含id、name、model、system、tools、skills、mcp_servers、version。注意这是快照，即使之后 Agent 对象被更新，线程仍保持创建时的配置。
parent_thread_id：父线程 ID；主线程（primary thread）该项为null，主线程也会出现在线程列表中。
archived_at：归档时间戳。
可选的stats/usage字段。

状态聚合语义

Session 状态聚合线程状态：只要有任何线程处于running，session.status就是running。
并发上限：最多25 个并发线程（Max 25 concurrent threads）。
排空每线程流的正确退出条件：在排空（draining）某个每线程事件流时，应在session.thread_status_idle事件处 break，并且像处理 Session 级 idle 一样检查其stop_reason。

关于线程状态与 Session 生命周期状态的对应关系，可对照 managed-agents-events.md 中rescheduling → running ↔ idle → terminated的状态机说明理解。

多智能体事件（会话流上）

协调者主线程的 Session 事件流上会浮现以下多智能体专属事件，用于感知子线程的生命周期与跨线程消息：

事件	载荷要点	含义
`session.thread_created`	`session_thread_id`、`agent_name`	一个新的线程被创建。
`session.thread_status_running`	`session_thread_id`、`agent_name`	线程开始活动。
`session.thread_status_idle`	`session_thread_id`、`agent_name`、`stop_reason`	线程正在等待输入。检查`stop_reason`（与`session.status_idle.stop_reason`形状相同）。
`session.thread_status_rescheduled`	`session_thread_id`、`agent_name`	线程在可重试错误后重新调度。
`session.thread_status_terminated`	`session_thread_id`、`agent_name`	线程被归档或遇到终端错误。
`agent.thread_message_sent`	`to_session_thread_id`、`to_agent_name`、`content`	协调者向另一个线程发送了后续消息。
`agent.thread_message_received`	`from_session_thread_id`、`from_agent_name`、`content`	某个 Agent 将其结果投递给协调者。

这些事件与普通事件一样遵循{domain}.{action}的命名约定，并与session.status_*系列事件并存于同一条流上；完整的事件命名空间对照可参见 managed-agents-events.md 的 "Event Types (Received)" 一节。

子 Agent 线程上的工具权限与自定义工具结果回传

这是多智能体协作中最容易写错的交互点：当一个子 Agent 需要你的客户端介入时（触发了一个always_ask策略的工具确认，或产生了一个自定义工具调用结果），该请求会被跨帖（cross-post）到主线程，并携带session_thread_id标识来源线程——因此你只需要监听 Session 事件流即可，无需订阅每条每线程流。

你需要回发user.tool_confirmation（携带tool_use_id）或user.custom_tool_result（携带custom_tool_use_id），并且回显（echo）来源事件中的session_thread_id。官方文档指出：SDK 的参数类型与 docstring 期望该字段，服务器也会按 tool-use ID 路由，因此回显属于"双保险"（belt-and-suspenders）而非决定性因素——但务必包含它。

for event_id in stop.event_ids: pending = events_by_id[event_id] confirmation = { "type": "user.tool_confirmation", "tool_use_id": event_id, "result": "allow", } if pending.session_thread_id is not None: confirmation["session_thread_id"] = pending.session_thread_id client.beta.sessions.events.send(session.id, events=[confirmation])

同样的模式适用于user.custom_tool_result——为自定义工具回传结果时同样携带session_thread_id。

这里可以对照普通（非多智能体）场景下的工具确认回环来理解差异：在单线程场景中，agent.tool_use事件携带evaluated_permission === 'ask'且 Session 进入 idle 等待决策，客户端用tool_use_id（即事件自身的id，形如sevt_...，不是toolu_...ID）回发user.tool_confirmation；多智能体场景在此基础上额外要求回显session_thread_id以指明确认属于哪个子线程。完整的单线程工具确认 round-trip 模式见 managed-agents-client-patterns.md 的 Pattern 4。

常见陷阱（Pitfalls）

官方文档明确列出了多智能体模式下最容易踩的三个坑，逐条对照自己的实现：

不要把 roster 放在sessions.create()上或tools[]里。multiagent是 Agent 的顶层字段；正确的做法是：先更新协调者 Agent（agents.update()），再启动一个引用该协调者的 Session。这与 Managed Agents 全局性的 "Agent（一次）→ Session（每次运行）" 强制流程一致，见 managed-agents-overview.md。
不要假设共享上下文。线程之间共享文件系统，但不共享对话历史或工具。如果协调者需要某个子 Agent 基于某项信息行动，它必须在委托消息（delegated message）里显式说清楚，或者把信息写入磁盘（写入共享容器文件系统）供子 Agent 读取。这是"共享容器"模型的正确用法——文件系统是跨线程的通信媒介，对话历史不是。
深度 > 1 的委托被忽略。子 Agent 自己声明的multiagentroster（如果有）不会级联生效——只有 Session 的协调者拥有委托权。设计协作拓扑时，请保持"协调者 → 子 Agent"的单层结构。

此外，归档（archive）语义在多智能体场景同样生效：归档线程或归档 Agent 都是不可逆操作，归档后的 Agent 无法被新 Session 引用，详见 managed-agents-api-reference.md 中关于 Archive 的说明。

各语言绑定与端点速查

本文示例以 Python SDK 为主（client.beta.agents.create/client.beta.sessions.create/client.beta.sessions.threads.*/client.beta.sessions.events.send），Python 与 TypeScript 的 SDK 方法名完全一致；Go 对应client.Beta.Agents/client.Beta.Sessions.Threads.*等命名空间。完整的跨语言方法对照表见 managed-agents-api-reference.md，Python 完整入门流程见 Python Managed Agents README。

对于 Python 之外的语言绑定，官方文档建议 WebFetchhttps://platform.claude.com/docs/en/managed-agents/multi-agent.md（对应本仓库的 live-sources.md）获取最新的各语言 SDK 示例，切勿从 cURL 形状或其他语言的 SDK 反推未经验证的 API 签名。多智能体涉及的 Session Threads 端点（GET /v1/sessions/{sid}/threads系列）与 Events 端点（GET /v1/sessions/{sid}/events/events/stream）均为managed-agents-2026-04-01beta 组的一部分，SDK 会自动附加该头，无需手动传递。