Managed Agents - Overview / 托管代理 - 概览

Managed Agents provisions a container per session as the agent's workspace. The agent loop runs on Anthropic's orchestration layer; the container is where the agent's tools execute - bash commands, file operations, code. You create a persisted Agent config (model, system prompt, tools, MCP servers, skills), then start Sessions that reference it. The session streams events back to you; you send user messages and tool results in.

Managed Agents 为每个会话预配一个容器作为代理的工作区。代理循环运行在 Anthropic 的编排层上；容器则是代理工具执行的地方——bash 命令、文件操作、代码。你先创建持久化的 Agent 配置（模型、系统提示词、工具、MCP 服务器、技能），然后启动引用它的 Session（会话）。会话把事件流式传回给你；你把用户消息和工具结果发进去。

Warning: THE MANDATORY FLOW: Agent (once) -> Session (every run) / 警告：强制流程：Agent（一次）-> Session（每次运行）

Why agents are separate objects: versioning. An agent is a persisted, versioned config - every update creates a new immutable version, and sessions pin to a version at creation time. This lets you iterate on the agent (tweak the prompt, add a tool) without breaking sessions already running, roll back if a change regresses, and A/B test versions side-by-side. None of that works if you agents.create() fresh on every run.

为什么 Agent 是独立对象：版本化。 Agent 是持久化、带版本的配置——每次更新都会创建一个新的不可变版本，而会话在创建时即固定（pin）到某个版本。这让你可以在不破坏已运行会话的情况下迭代代理（调整提示词、添加工具），在变更造成退化时回滚，并对多个版本做并排 A/B 测试。如果你每次运行都新调用 agents.create()，这些好处统统不复存在。

Every session references a pre-created /v1/agents object. Create the agent once, store the ID, and reuse it across runs.

每个会话都引用一个预先创建的 /v1/agents 对象。代理只创建一次，保存 ID，并在多次运行间复用。

If you're about to write sessions.create() with model, system, or tools on the session body - stop. Those fields live on agents.create(). The session takes a pointer only.

如果你正准备在 sessions.create() 的会话请求体里写 model、system 或 tools——停。这些字段属于 agents.create()。会话只接受指针。

When generating code, separate setup from runtime. agents.create() belongs in a setup script (or a guarded if agent_id is None: block), not at the top of the hot path. If the user's code calls agents.create() on every invocation, they're accumulating orphaned agents and paying the create latency for nothing. The correct shape is: define the agent as a version-controlled file and sync it with ant apply, which records the ID in claude-lock.json (see shared/anthropic-cli.md) - or use a guarded setup script that persists the returned ID (config file, env var, secrets manager) - and have every run load the ID and call sessions.create().

生成代码时，把设置与运行时分开。 agents.create() 应属于安装脚本（或有守卫的 if agent_id is None: 代码块），而不是热路径的开头。如果用户的代码每次调用都执行 agents.create()，他们就会不断累积孤儿代理，并白白支付创建延迟。正确的形态是：把代理定义为一个受版本控制的文件并用 ant apply 同步（ID 记录在 claude-lock.json 中，参见 shared/anthropic-cli.md）——或使用能持久化返回 ID 的带守卫安装脚本（配置文件、环境变量、密钥管理器）——然后让每次运行加载 ID 并调用 sessions.create()。

To change the agent's behavior, use POST /v1/agents/{id} - don't create a new one. (For an agent managed with ant apply, edit its file and re-run instead - an update made outside the files makes the next ant apply refuse to run.) Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via {type: "agent", id, version}). See shared/managed-agents-core.md -> Agents -> Versioning. To change tools/mcp_servers on one running session without touching the agent object, use sessions.update() (vault_ids attaches at session create only) - see shared/managed-agents-core.md -> Updating the agent configuration mid-session.

要改变代理的行为，用 POST /v1/agents/{id}——不要新建。（对用 ant apply 管理的代理，应改为编辑其文件并重新运行——在文件之外做的更新会让下一次 ant apply 拒绝执行。）每次更新都会递增版本；运行中的会话保持其固定的版本，新会话拿到最新版本（或通过 {type: "agent", id, version} 显式固定）。参见 shared/managed-agents-core.md -> Agents -> Versioning。要在不触碰代理对象的前提下更改某个运行中会话的 tools/mcp_servers，使用 sessions.update()（vault_ids 只能在会话创建时附加）——参见 shared/managed-agents-core.md -> Updating the agent configuration mid-session。

Beta Headers / Beta 请求头

Managed Agents is in beta. The SDK sets required beta headers automatically:

Managed Agents 处于 beta 阶段。SDK 会自动设置所需的 beta 请求头：

Which beta header goes where: The SDK sets managed-agents-2026-04-01 automatically on client.beta.{agents,environments,sessions,vaults,deployments,deployment_runs}.* calls and agent-memory-2026-07-22 on client.beta.memory_stores.* calls. Don't add managed-agents-2026-04-01 to a memory store call: sending both headers on a memory store request returns a 400 (attaching a memory store to a session is a session call and still uses managed-agents-2026-04-01). The Files and Skills APIs are out of beta and need no beta header; requests that still send files-api-2025-04-14 or skills-2025-10-02 keep working but get the old beta response shapes. Exception - session-scoped file listing: filtering files.list by scope_id requires managed-agents-2026-04-01, which client.beta.files does not add, so pass betas: ["managed-agents-2026-04-01"] explicitly on client.beta.files.list({scope_id: session.id}) (on raw HTTP, send anthropic-beta: managed-agents-2026-04-01; in the ant CLI, add --beta managed-agents-2026-04-01 to ant beta:files list --scope-id). See shared/managed-agents-environments.md -> Session outputs.

哪个 beta 请求头用在哪里： SDK 在 client.beta.{agents,environments,sessions,vaults,deployments,deployment_runs}.* 调用上自动设置 managed-agents-2026-04-01，在 client.beta.memory_stores.* 调用上自动设置 agent-memory-2026-07-22。不要把 managed-agents-2026-04-01 加到记忆存储调用上：在记忆存储请求上同时发送两个请求头会返回 400（把记忆存储挂到会话上属于会话调用，仍然使用 managed-agents-2026-04-01）。Files 和 Skills API 已结束 beta，不需要 beta 请求头；仍发送 files-api-2025-04-14 或 skills-2025-10-02 的请求继续可用，但会拿到旧的 beta 响应结构。例外——会话级文件列表： 按 scope_id 过滤 files.list 需要 managed-agents-2026-04-01，而 client.beta.files 不会自动添加该请求头，因此需在 client.beta.files.list({scope_id: session.id}) 上显式传入 betas: ["managed-agents-2026-04-01"]（原始 HTTP 时发送 anthropic-beta: managed-agents-2026-04-01；ant CLI 中在 ant beta:files list --scope-id 后加 --beta managed-agents-2026-04-01）。参见 shared/managed-agents-environments.md -> Session outputs。

Reading Guide / 阅读指南

Common Pitfalls / 常见陷阱

• Agent FIRST, then session - NO EXCEPTIONS - the session's agent field accepts only a string ID or {type: "agent", id, version}. model, system, tools, mcp_servers, skills are top-level fields on POST /v1/agents, never on sessions.create(). If the user hasn't created an agent, that is step zero of every example.

  • 先有 Agent，再有会话——无一例外——会话的 agent 字段只接受字符串 ID 或 {type: "agent", id, version}。model、system、tools、mcp_servers、skills 是 POST /v1/agents 的顶层字段，绝不出现在 sessions.create() 上。如果用户还没创建代理，那每个示例的第零步都是创建代理。

• Agent ONCE, not every run - agents.create() is a setup step. Store the returned agent_id and reuse it; don't call agents.create() at the top of your hot path. If the agent's config needs to change, POST /v1/agents/{id} - each update creates a new version, and sessions can pin to a specific version for reproducibility.

  • Agent 只创建一次，而不是每次运行——agents.create() 是设置步骤。保存返回的 agent_id 并复用；不要在热路径开头调用 agents.create()。如果代理配置需要变更，用 POST /v1/agents/{id}——每次更新创建一个新版本，会话可以固定到特定版本以保证可复现性。

• MCP auth goes through vaults - the agent's mcp_servers array declares {type, name, url} only (no auth). Credentials live in vaults (client.beta.vaults.credentials.create) and attach to sessions via vault_ids. Anthropic auto-refreshes OAuth tokens using the stored refresh token. Vaults also hold environment_variable credentials for non-MCP services (CLIs, SDKs, direct API calls) - substituted at egress, never visible in the sandbox.

  • MCP 鉴权经由 vault（保险库）——代理的 mcp_servers 数组只声明 {type, name, url}（不含鉴权）。凭据存放在 vault 中（client.beta.vaults.credentials.create），并通过 vault_ids 附加到会话。Anthropic 使用存储的 refresh token 自动刷新 OAuth token。vault 还保存非 MCP 服务（CLI、SDK、直接 API 调用）使用的 environment_variable 凭据——出站时替换，在沙箱中永不可见。

• Reconcile resources before the first run - a session with a clear ask but a missing tool, credential, data mount, or context will discover the gap mid-run, then flail and give up. Before creating the session, check that every action in the task maps to a configured tool/MCP server, every MCP server has a vault credential, and every referenced file/host is mounted/reachable. When helping a user set one up, run the reconciliation in shared/managed-agents-onboarding.md -> §3 Pre-flight viability check.

  • 首次运行前先核对资源——一个诉求明确但缺少工具、凭据、数据挂载或上下文的会话，会在运行中途才发现缺口，然后挣扎并放弃。创建会话之前，确认任务中的每个动作都映射到已配置的工具/MCP 服务器，每个 MCP 服务器都有 vault 凭据，每个被引用的文件/主机都已挂载/可达。帮助用户搭建时，执行 shared/managed-agents-onboarding.md -> §3 Pre-flight viability check 中的核对。

• Stream to get events - GET /v1/sessions/{id}/events/stream is the primary way to receive agent output in real-time.

  • 用流接收事件——GET /v1/sessions/{id}/events/stream 是实时接收代理输出的主要方式。

• SSE stream has no replay - reconnect with consolidation - if the stream drops while a agent.tool_use, agent.mcp_tool_use, or agent.custom_tool_use is pending resolution (user.tool_confirmation for the first two, user.custom_tool_result for the last one), the session deadlocks (client disconnects -> session idles -> reconnect happens -> no client resolution happens). On every (re)connect: open stream with GET /v1/sessions/{id}/events/stream , fetch GET /v1/sessions/{id}/events, dedupe by event ID, then proceed. See shared/managed-agents-events.md -> Reconnecting after a dropped stream.

  • SSE 流没有重放——重连时需合并去重——如果流在某个 agent.tool_use、agent.mcp_tool_use 或 agent.custom_tool_use 待解决期间断开（前两者需 user.tool_confirmation，最后者需 user.custom_tool_result），会话会死锁（客户端断开 -> 会话空闲 -> 重新连接 -> 始终没有客户端解决结果）。每次（重）连接时：用 GET /v1/sessions/{id}/events/stream 打开流，抓取 GET /v1/sessions/{id}/events，按事件 ID 去重，然后继续。参见 shared/managed-agents-events.md -> Reconnecting after a dropped stream。

  【评论】SSE 无重放意味着断线重连的客户端必须自行从完整事件列表补齐状态，否则待确认的工具调用会永久挂起——这是把容错责任放在客户端一侧的协议设计。

• Don't trust HTTP-library timeouts as wall-clock caps - requests timeout=(c, r) and httpx.Timeout(n) are per-chunk read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track time.monotonic() at the loop level and bail explicitly. Prefer the SDK's sessions.events.stream() / sessions.events.list() over hand-rolled HTTP. See shared/managed-agents-events.md -> Receiving Events.

  • 不要把 HTTP 库超时当作墙钟上限——requests 的 timeout=(c, r) 和 httpx.Timeout(n) 是逐块读取超时；每收到一个字节就重置，因此一个缓慢滴流的连接可以无限期阻塞。要对原始 HTTP 轮询设置硬性截止时间，应在循环层面跟踪 time.monotonic() 并显式退出。优先使用 SDK 的 sessions.events.stream() / sessions.events.list()，而不是手写 HTTP。参见 shared/managed-agents-events.md -> Receiving Events。

• Messages queue - you can send events while the session is running or idle; they're processed in order. No need to wait for a response before sending the next message. Exception: a session paused at its budget (stop_reason: budget_reached) accepts only settle events - change or remove the budget to resume (shared/managed-agents-core.md § Session budgets).

  • 消息排队——会话处于 running 或 idle 时都可以发送事件；它们按顺序处理。无需等到响应再发下一条消息。例外：因预算暂停的会话（stop_reason: budget_reached）只接受结算类事件——变更或移除预算才能恢复（shared/managed-agents-core.md § Session budgets）。

• Environment config.type is "cloud" or "self_hosted" - cloud runs the container on Anthropic's infrastructure; self_hosted moves tool execution to your own (see shared/managed-agents-self-hosted-sandboxes.md).

  • 环境的 config.type 是 "cloud" 或 "self_hosted"——cloud 把容器跑在 Anthropic 的基础设施上；self_hosted 把工具执行移到你自己的设施中（参见 shared/managed-agents-self-hosted-sandboxes.md）。

• Archive is permanent on every resource - archiving an agent, environment, session, vault, credential, or memory store makes it read-only with no unarchive. For agents, environments, and memory stores specifically, archived resources cannot be referenced by new sessions (existing sessions continue). Do not call .archive() on a production agent, environment, or memory store as cleanup - always confirm with the user before archiving.

  • 归档对所有资源都是永久的——归档代理、环境、会话、vault、凭据或记忆存储会使其变为只读，且无法取消归档。具体到代理、环境和记忆存储，已归档的资源无法被新会话引用（已有会话继续运行）。不要把对生产环境的代理、环境或记忆存储调用 .archive() 当作清理手段——归档前务必与用户确认。

  【评论】对编码代理写入"归档前必须与用户确认"，是把不可逆破坏性操作的人工确认权显式保留给用户的一类防护条款。