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

人工智能大模型AI 应用移动开发交互助手【免费下载链接】rikkahubRikkaHub is an Android APP that supports for multiple LLM providers.项目地址https://gitcode.com/gh_mirrors/ri/rikkahub点击查看免费下载本文以 Anthropic Claude Managed Agents 的 Multiagent Sessions 机制为核心系统讲解如何在单个会话Session内由一个协调者CoordinatorAgent 向多个子 AgentSubagent进行委托协作——包括 roster 花名册的声明方式、线程Thread模型与状态语义、会话流上的多智能体事件、跨线程工具确认与自定义工具结果的回传以及最容易踩中的三个陷阱。阅读本文后你将掌握multiagent: {type: coordinator, agents: [...]}的完整配置与编程模式能够为 RikkaHub 这类多 LLM 提供者客户端设计并实现一个协调者 多个专家子代理的协作式 Agent 工作流。文中所有代码示例与概念均可对照本仓库.agents/skills/claude-api/下的官方技能文档与各语言 SDK 绑定验证。多智能体会话的核心模型共享容器、独立线程在 Managed Agents 体系下多智能体协作的最小单位是一个Session。一个协调者coordinatorAgent 可以在同一个 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( nameEngineering Lead, modelclaude-opus-4-8, systemYou 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(agentorchestrator.id, environment_idenv.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操作HTTPSDKclient.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。statusrunning|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 状态聚合线程状态只要有任何线程处于runningsession.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_createdsession_thread_id、agent_name一个新的线程被创建。session.thread_status_runningsession_thread_id、agent_name线程开始活动。session.thread_status_idlesession_thread_id、agent_name、stop_reason线程正在等待输入。检查stop_reason与session.status_idle.stop_reason形状相同。session.thread_status_rescheduledsession_thread_id、agent_name线程在可重试错误后重新调度。session.thread_status_terminatedsession_thread_id、agent_name线程被归档或遇到终端错误。agent.thread_message_sentto_session_thread_id、to_agent_name、content协调者向另一个线程发送了后续消息。agent.thread_message_receivedfrom_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 的顶层字段正确的做法是先更新协调者 Agentagents.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.sendPython 与 TypeScript 的 SDK 方法名完全一致Go 对应client.Beta.Agents/client.Beta.Sessions.Threads.*等命名空间。完整的跨语言方法对照表见 managed-agents-api-reference.mdPython 完整入门流程见 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 会自动附加该头无需手动传递。赞分享人工智能大模型AI 应用移动开发交互助手【免费下载链接】rikkahubRikkaHub is an Android APP that supports for multiple LLM providers.项目地址https://gitcode.com/gh_mirrors/ri/rikkahub点击查看免费下载相关推荐RikkaHub 智能体技能库使用 Python SDK 开发 Claude Managed Agents 完整实战指南RikkaHub 智能体技能库使用 Python SDK 开发 Claude Managed Agents 完整实战指南 本文是 RikkaHub 开源仓库中人工智能大模型AI 应用移动开发交互助手LunaTranslator 的 PS3 游戏文本挂钩支持基于 RPCS3 的视觉小说翻译实战清单与底层原理LunaTranslator 的 PS3 游戏文本挂钩支持基于 RPCS3 的视觉小说翻译实战清单与底层原理 LunaTranslator 作为一款视觉小说翻人工智能大模型AI 应用移动开发交互助手RikkaHub 项目实践Anthropic Managed Agents 客户端模式与事件流驱动会话开发指南RikkaHub 项目实践Anthropic Managed Agents 客户端模式与事件流驱动会话开发指南 本指南以仓库内 managed agents人工智能大模型AI 应用移动开发交互助手上一篇Video2X 免费视频超分辨率与插帧完整指南把老视频拉到 4K 还能更顺滑下一篇Freqtrade 加密交易机器人从克隆到回测的完整教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考