Managed Agents - Endpoint Reference / Managed Agents - 端点参考

All endpoints require x-api-key and anthropic-version: 2023-06-01 headers. Managed Agents endpoints additionally require the anthropic-beta header.

所有端点都需要 x-api-key 和 anthropic-version: 2023-06-01 请求头。Managed Agents 端点还额外要求 anthropic-beta 请求头。

Most users should define agents and environments as version-controlled files synced with ant apply - see shared/anthropic-cli.md. The endpoints below are the underlying API that the CLI and SDKs drive.
大多数用户应当把代理和环境定义为受版本控制的文件，用 ant apply 同步——见 shared/anthropic-cli.md。下面的端点是 CLI 与 SDK 所驱动的底层 API。

Beta Headers / Beta 请求头

anthropic-beta: managed-agents-2026-04-01

The SDK adds this header automatically for all client.beta.{agents,environments,sessions,vaults,deployments,deployment_runs}.* calls. Memory store endpoints (client.beta.memory_stores.*) use agent-memory-2026-07-22 instead, which the SDK also sets; sending both headers on a memory store request returns a 400. The Files and Skills APIs are out of beta and need no beta header.

对于所有 client.beta.{agents,environments,sessions,vaults,deployments,deployment_runs}.* 调用，SDK 会自动添加这个请求头。记忆存储端点（client.beta.memory_stores.*）改用 agent-memory-2026-07-22，SDK 也会自动设置；对记忆存储请求同时发送两个请求头会返回 400。Files 与 Skills API 已结束测试期，不需要 beta 请求头。

SDK Method Reference / SDK 方法参考

All resources are under the beta namespace. Python and TypeScript share identical method names.

所有资源都在 beta 命名空间下。Python 与 TypeScript 的方法名完全一致。

Naming quirks to watch for:

需要注意的命名怪癖：

• Agents and Session Threads have no delete - only archive. Archive is permanent: the agent becomes read-only, new sessions cannot reference it, and there is no unarchive. Confirm with the user before archiving a production agent. Environments, Sessions, Vaults, Credentials, and Memory Stores have both delete and archive; Session Resources, Files, Skills, and Memories are delete-only; Memory Versions have neither - only redact.
  代理与会话线程没有 delete——只有 archive。归档是永久的：代理变为只读，新会话不能引用它，也没有取消归档。归档生产环境的代理前请先与用户确认。环境、会话、保管库、凭证和记忆存储同时有 delete 和 archive；会话资源、文件、技能和记忆只有 delete；记忆版本两者皆无——只有 redact。
• Session resources use add (not create).
  会话资源用 add（不是 create）。
• Go's event stream is StreamEvents (not Stream).
  Go 的事件流是 StreamEvents（不是 Stream）。
• The self-hosted worker class is EnvironmentWorker from anthropic.lib.environments / @anthropic-ai/sdk/helpers/beta/environments / anthropic-sdk-go/lib/environments; client.beta.environments.work.worker(...) is a factory that returns the same class, alongside the environments.work.poller/stats/stop client methods.
  自托管的 worker 类是来自 anthropic.lib.environments / @anthropic-ai/sdk/helpers/beta/environments / anthropic-sdk-go/lib/environments 的 EnvironmentWorker；client.beta.environments.work.worker(...) 是一个返回同一类的工厂，与 environments.work.poller/stats/stop 客户端方法并列。

【评论】"归档即终态、不可取消归档"是不可逆操作设计；文档据此要求在归档生产代理前先征得用户确认，属于对破坏性 API 的防护性约定。

Agent shorthand: agent on session create accepts three forms - a bare string (agent="agent_abc123", latest version), a pinned reference {type: "agent", id, version}, or {type: "agent_with_overrides", id, version?, model?, system?, tools?, mcp_servers?, skills?} to override those fields for this session only (see shared/managed-agents-core.md -> Override agent configuration for a session).

代理简写： 会话创建时的 agent 接受三种形式——裸字符串（agent="agent_abc123"，最新版本）、钉住版本的引用 {type: "agent", id, version}，或 {type: "agent_with_overrides", id, version?, model?, system?, tools?, mcp_servers?, skills?}，仅为该会话覆盖那些字段（见 shared/managed-agents-core.md -> Override agent configuration for a session）。

Model shorthand: model on agent create accepts either a bare string (model="claude-opus-5-5" - uses standard speed) or the full config object, which takes speed, effort, and inference_geo alongside id: {id: "claude-opus-5-5", speed: "fast"}, {id: "claude-opus-5-5", effort: "high"}, {id: "claude-opus-5-5", inference_geo: "us"}. effort accepts a level string (low/medium/high/xhigh/max) or {type: "<level>"}, and in a per-session model override it sets the session's effort level (the agent's own effort isn't carried over, and a model override without effort runs at that model's default effort level). inference_geo ("us" | "global") pins the geography serving the agent's model requests, and is also applied in a per-session model override. See shared/managed-agents-core.md -> Effort on the agent model / Pinning inference geography. Note: speed: "fast" is supported on Claude Opus 5.5, Claude Opus 5, and Opus 4.8 - on the Claude API only, which includes Managed Agents but not Amazon Bedrock, Google Cloud, or Microsoft Foundry. Opus 4.7 fast mode has been removed; speed: "fast" on Opus 4.7 returns an error.

模型简写： 代理创建时的 model 接受裸字符串（model="claude-opus-5-5"——使用 standard 速度）或完整配置对象，后者在 id 之外还接受 speed、effort 和 inference_geo：{id: "claude-opus-5-5", speed: "fast"}、{id: "claude-opus-5-5", effort: "high"}、{id: "claude-opus-5-5", inference_geo: "us"}。effort 接受级别字符串（low/medium/high/xhigh/max）或 {type: "<level>"}；在按会话的 model 覆盖中，它会设置该会话的 effort 级别（代理自身的 effort 不会被带过来，不带 effort 的 model 覆盖按该模型的默认 effort 级别运行）。inference_geo（"us" | "global"）钉住服务该代理模型请求的地理区域，在按会话的 model 覆盖中同样生效。见 shared/managed-agents-core.md -> Effort on the agent model / Pinning inference geography。注意：speed: "fast" 在 Claude Opus 5.5、Claude Opus 5 和 Opus 4.8 上受支持——仅在 Claude API 上，包括 Managed Agents，但不包括 Amazon Bedrock、Google Cloud 或 Microsoft Foundry。Opus 4.7 的 fast 模式已被移除；在 Opus 4.7 上使用 speed: "fast" 会返回错误。

Agents / 代理

Step one of every flow. Sessions require a pre-created agent - there is no inline agent config under managed-agents-2026-04-01.

每个流程的第一步。 会话需要预先创建好的代理——在 managed-agents-2026-04-01 下没有内联的代理配置。

Sessions / 会话

Events / 事件

Session Threads / 会话线程

Per-subagent event streams in multiagent sessions. See shared/managed-agents-multiagent.md.

多代理会话中每个子代理的事件流。见 shared/managed-agents-multiagent.md。

Session Resources / 会话资源

Environments / 环境

For type: "self_hosted", config is the bare {"type": "self_hosted"} - networking and packages do not apply. (networking never governs web_search / web_fetch in either type - those are restricted per-tool with allowed_domains / blocked_domains in the agent toolset; see shared/managed-agents-tools.md.)

对于 type: "self_hosted"，config 就是裸的 {"type": "self_hosted"}——networking 和 packages 不适用。（两种类型中 networking 都不管辖 web_search / web_fetch——那些是在代理工具集中按工具用 allowed_domains / blocked_domains 限制的；见 shared/managed-agents-tools.md。）

Deployments / 部署

Scheduled deployments (depl_ IDs) run an agent on a recurring cron schedule - each firing creates a session. See shared/managed-agents-scheduled-deployments.md for the conceptual guide (cron/DST semantics, failure behavior, lifecycle).

定时部署（depl_ ID）按周期性的 cron 计划运行一个代理——每次触发都会创建一个会话。概念指南（cron/夏令时语义、失败行为、生命周期）见 shared/managed-agents-scheduled-deployments.md。

Deployment Runs / 部署运行

Each trigger attempt (scheduled or manual) writes a deployment_run record (drun_ IDs) carrying either the created session_id or an error.type (environment_archived, agent_archived, vault_not_found, session_rate_limited, service_unavailable).

每次触发尝试（定时或手动）都会写入一条 deployment_run 记录（drun_ ID），携带已创建的 session_id 或一个 error.type（environment_archived、agent_archived、vault_not_found、session_rate_limited、service_unavailable）。

Vaults / 保管库

Vaults store credentials that Anthropic manages on your behalf - MCP credentials (OAuth with auto-refresh, or static bearer tokens) and environment_variable credentials substituted into outbound requests at egress. Attach to sessions via vault_ids. See managed-agents-tools.md §Vaults for the conceptual guide and credential shapes.

保管库存储由 Anthropic 代你管理的凭证——MCP 凭证（自动刷新的 OAuth，或静态 bearer token）和在出口处替换进外发请求的 environment_variable 凭证。通过 vault_ids 附加到会话。概念指南与凭证形状见 managed-agents-tools.md §Vaults。

Credentials / 凭证

Credentials are individual secrets stored inside a vault.

凭证是存储在保管库内的单个机密。

Memory Stores / 记忆存储

Workspace-scoped persistent memory that survives across sessions. Attach to a session via a {"type": "memory_store", "memory_store_id": ...} entry in resources[] (session-create time only). See shared/managed-agents-memory.md for the conceptual guide, the FUSE-mount agent interface, preconditions, and versioning.

工作区范围的持久记忆，跨会话存活。通过 resources[] 中的 {"type": "memory_store", "memory_store_id": ...} 条目附加到会话（仅会话创建时）。概念指南、FUSE 挂载的代理接口、前置条件与版本化见 shared/managed-agents-memory.md。

Memories / 记忆

Individual text documents inside a store (<= 100KB each). create creates at a path and returns 409 (memory_path_conflict_error, with conflicting_memory_id) if the path is occupied; update mutates by mem_... ID (rename and/or content). Only update accepts a precondition ({"type": "content_sha256", "content_sha256": ...}) - on mismatch returns 409 (memory_precondition_failed_error). List endpoints accept view: "basic"|"full" (controls whether content is populated; retrieve defaults to full).

存储内的单个文本文档（每个 <= 100KB）。create 在一个 path 处创建，若路径已被占用则返回 409（memory_path_conflict_error，附 conflicting_memory_id）；update 按 mem_... ID 变更（重命名和/或内容）。只有 update 接受 precondition（{"type": "content_sha256", "content_sha256": ...}）——不匹配时返回 409（memory_precondition_failed_error）。列表端点接受 view: "basic"|"full"（控制是否填充 content；retrieve 默认为 full）。

Memory Versions / 记忆版本

Immutable per-mutation snapshots (memver_...) - the audit and rollback surface. operation in created / modified / deleted.

每次变更一份的不可变快照（memver_...）——审计与回滚的界面。operation 取值为 created / modified / deleted。

Files / 文件

Skills / 技能

Request/Response Schema Quick Reference / 请求/响应模式速查

CreateAgent Request Body / CreateAgent 请求体

Always start here. model, system, tools, mcp_servers, skills are top-level fields on this object - they do NOT go on the session.

永远从这里开始。 model、system、tools、mcp_servers、skills 是这个对象的顶层字段——它们不放在会话上。

{
  "name": "string (required, 1-256 chars)",
  "model": "claude-opus-5-5 (required - bare string, or {id, speed?, effort?, inference_geo?} object)",
  "description": "string (optional, up to 2048 chars)",
  "system": "string (optional, up to 100,000 chars)",
  "tools": [
    { "type": "agent_toolset_20260401" }
  ],
  "skills": [
    { "type": "anthropic", "skill_id": "xlsx" },
    { "type": "custom", "skill_id": "skill_abc123", "version": "1" }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "name": "github",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  ],
  "multiagent": {
    "type": "coordinator",
    "agents": [
      "agent_abc123",
      { "type": "agent", "id": "agent_def456", "version": 4 },
      { "type": "self" }
    ]
  },
  "metadata": {
    "key": "value (max 16 pairs, keys <=64 chars, values <=512 chars)"
  }
}

Limits: tools max 128, skills max 20, mcp_servers max 20 (unique names). multiagent.agents 1-20 entries (string ID | {type:"agent",id,version?} | {type:"self"} | {type:"advisor",model}, at most one advisor) - see shared/managed-agents-multiagent.md.
限制：tools 最多 128，skills 最多 20，mcp_servers 最多 20（名字唯一）。multiagent.agents 为 1-20 个条目（字符串 ID | {type:"agent",id,version?} | {type:"self"} | {type:"advisor",model}，advisor 至多一个）——见 shared/managed-agents-multiagent.md。

CreateSession Request Body / CreateSession 请求体

{
  "agent": "agent_abc123 (required - string shorthand for latest version, or {type: \"agent\", id, version} object)",
  "environment_id": "env_abc123 (required)",
  "title": "string (optional)",
  "resources": [
    {
      "type": "github_repository",
      "url": "https://github.com/owner/repo (required)",
      "authorization_token": "ghp_... (required)",
      "mount_path": "/workspace/repo (optional - defaults to /workspace/<repo-name>)",
      "checkout": { "type": "branch", "name": "main" }
    }
  ],
  "initial_events": [
    { "type": "user.message", "content": [{ "type": "text", "text": "Review the auth module." }] }
  ],
  "vault_ids": ["vlt_abc123 (optional - vault credentials: MCP auth + environment variables)"],
  "budget": {
    "type": "limit",
    "max_list_cost": { "amount": "2500", "currency": "USD" }
  },
  "metadata": {
    "key": "value"
  }
}

The agent field accepts a string ID, {type: "agent", id, version}, or {type: "agent_with_overrides", id, version?, ...} for session-local overrides of model/system/tools/mcp_servers/skills. Outside the overrides form, those fields live on the agent, not here. An effort inside a model override is applied (the agent's own effort isn't carried over, and a model override without effort runs at that model's default effort level). An inference_geo inside a model override is applied (omitting it clears the agent's pin for this session).

budget (optional, create-only) is a hard dollar cap on the session's list-priced spend; amount is an integer string in minor units (cents - "2500" = $25.00), USD only. It can be changed or removed later via session update, never added. See shared/managed-agents-core.md -> Session budgets.

initial_events (optional, max 50) sends events at creation and starts the agent loop in the same call. Only user.message and user.define_outcome are accepted - no system.message, and none of the tool-result kinds. Validation is all-or-nothing. See shared/managed-agents-core.md -> Seeding a session with initial_events.

checkout accepts {type: "branch", name: "..."} or {type: "commit", sha: "..."}. Omit for the repo's default branch.
agent 字段接受字符串 ID、{type: "agent", id, version}，或用于对 model/system/tools/mcp_servers/skills 做会话本地覆盖的 {type: "agent_with_overrides", id, version?, ...}。在覆盖形式之外，那些字段放在代理上，不放在这里。model 覆盖内的 effort 会被应用（代理自身的 effort 不会被带过来，不带 effort 的 model 覆盖按该模型的默认 effort 级别运行）。model 覆盖内的 inference_geo 会被应用（省略它会清掉代理在本会话的区域钉住）。

budget（可选，仅创建时）是对会话按清单价支出的硬性美元上限；amount 是以最小单位（美分——"2500" = $25.00）计的整数字符串，仅支持 USD。之后可通过会话更新更改或移除，绝不能再添加。见 shared/managed-agents-core.md -> Session budgets。

initial_events（可选，最多 50）在创建时发送事件并在同一次调用中启动代理循环。只接受 user.message 和 user.define_outcome——不接受 system.message，也不接受任何工具结果类型。校验是全有或全无。见 shared/managed-agents-core.md -> Seeding a session with initial_events。

checkout 接受 {type: "branch", name: "..."} 或 {type: "commit", sha: "..."}。省略则用仓库的默认分支。

CreateEnvironment Request Body / CreateEnvironment 请求体

{
  "name": "string (required)",
  "description": "string (optional)",
  "config": {
    "type": "cloud | self_hosted",
    "networking": {
      "type": "unrestricted | limited (union - see SDK types)"
    },
    "packages": { }
  },
  "metadata": { "key": "value" }
}

CreateDeployment Request Body / CreateDeployment 请求体

{
  "name": "Weekly compliance scan",
  "agent": "agent_abc123 (required - same shapes as CreateSession)",
  "environment_id": "env_abc123 (required)",
  "initial_events": [
    { "type": "user.message", "content": [{ "type": "text", "text": "Run the weekly compliance scan." }] }
  ],
  "schedule": {
    "type": "cron",
    "expression": "0 20 * * 5",
    "timezone": "America/New_York"
  }
}

Optional session config (resources, vault_ids, etc.) is supported the same way as on CreateSession, including budget - copied onto each fired session; unlike a session's, it can be added where none exists and re-added after clearing (see shared/managed-agents-scheduled-deployments.md § Deployment budgets). Response includes status, paused_reason, and schedule.upcoming_runs_at (next fire times). See shared/managed-agents-scheduled-deployments.md.
可选的会话配置（resources、vault_ids 等）以与 CreateSession 相同的方式支持，包括 budget——复制到每个被触发的会话上；与会话上的不同，它可以在原本没有时添加，也可在清除后重新添加（见 shared/managed-agents-scheduled-deployments.md § Deployment budgets）。响应包含 status、paused_reason 和 schedule.upcoming_runs_at（下次触发时间）。见 shared/managed-agents-scheduled-deployments.md。

SendEvents Request Body / SendEvents 请求体

{
  "events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Hello"
        }
      ]
    }
  ]
}

system.message events (append system-level context for this turn and later ones) use the same envelope with type: "system.message" - supported on Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, and Claude Sonnet 5.5 (not Claude Sonnet 5), checked against the agent's primary model only; see shared/managed-agents-events.md § Adding system context mid-session.
system.message 事件（为本回合及之后的回合追加系统级上下文）使用同样的信封、type: "system.message"——在 Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、Claude Opus 5.5、Claude Opus 5、Claude Opus 4.8 和 Claude Sonnet 5.5 上受支持（Claude Sonnet 5 不支持），且只按代理的主模型检查；见 shared/managed-agents-events.md § Adding system context mid-session。

Define Outcome Event / Define Outcome 事件

{
  "type": "user.define_outcome",
  "description": "Build a DCF model for Costco in .xlsx",
  "rubric": { "type": "file", "file_id": "file_01..." },
  "max_iterations": 5
}

rubric is required: {type: "text", content} or {type: "file", file_id}. max_iterations default 3, max 20. Echoed back with outcome_id + processed_at. See shared/managed-agents-outcomes.md.
rubric 是必需的：{type: "text", content} 或 {type: "file", file_id}。max_iterations 默认 3，最大 20。会随 outcome_id + processed_at 回显。见 shared/managed-agents-outcomes.md。

Tool Result Event / 工具结果事件

{
  "type": "user.custom_tool_result",
  "custom_tool_use_id": "sevt_abc123",
  "content": [{ "type": "text", "text": "Result data" }],
  "is_error": false
}

Error Handling / 错误处理

Managed Agents endpoints use the standard Anthropic API error format. Errors are returned with an HTTP status code and a JSON body containing type, error, and request_id:

Managed Agents 端点使用标准的 Anthropic API 错误格式。错误以一个 HTTP 状态码和一个包含 type、error、request_id 的 JSON 体返回：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Description of what went wrong"
  },
  "request_id": "req_011CRv1W3XQ8XpFikNYG7RnE"
}

Include the request_id when reporting issues to Anthropic - it lets us trace the request end-to-end. The inner error.type is one of the following:

向 Anthropic 报告问题时请附上 request_id——它让我们能端到端追踪请求。内层 error.type 是以下之一：

Note that 409 Conflict carries error.type: "invalid_request_error" (there is no separate conflict_error type); inspect both the HTTP status and the message to distinguish conflicts from other invalid requests.

注意 409 Conflict 携带的是 error.type: "invalid_request_error"（没有单独的 conflict_error 类型）；要区分冲突与其他无效请求，需同时查看 HTTP 状态码和 message。

Pagination / 分页

Most Managed Agents list endpoints use the page / next_page cursor scheme:

大多数 Managed Agents 列表端点使用 page / next_page 游标方案：

Every SDK exposes an auto-paginating iterator that follows next_page. In Python and TypeScript, iterate the list result directly; the other SDKs expose the iterator via a separate method (iterating the plain list result returns one page). SDK auto-pagination is forward-only - to go back a page, read prev_page from the response and pass it back as the page parameter yourself.

每个 SDK 都暴露遵循 next_page 的自动分页迭代器。在 Python 和 TypeScript 中直接迭代列表结果即可；其他 SDK 通过单独的方法暴露迭代器（迭代普通列表结果只返回一页）。SDK 自动分页是仅向前的——要回退一页，需自己从响应读取 prev_page 并作为 page 参数传回。

Warning: Some endpoints use a different cursor scheme: Message Batches, Files, Models, and several Admin API endpoints take after_id/before_id and return has_more/first_id/last_id instead of page/next_page. Some page-scheme endpoints (e.g. GET /v1/skills) also return a has_more boolean alongside next_page. Check the endpoint's reference page for its exact pagination fields.
警告：一些端点使用不同的游标方案：Message Batches、Files、Models 以及若干 Admin API 端点接受 after_id/before_id，返回 has_more/first_id/last_id 而不是 page/next_page。一些 page 方案的端点（例如 GET /v1/skills）还会在 next_page 旁边返回 has_more 布尔值。请查阅端点的参考页确认其确切的分页字段。

Rate Limits / 速率限制

Managed Agents endpoints have per-organization request-per-minute (RPM) limits, separate from your Messages API token limits. Model inference inside a session still draws from your organization's standard ITPM/OTPM limits.

Managed Agents 端点有按组织计的每分钟请求数（RPM）限制，与你 的Messages API token 限制相互独立。会话内的模型推理仍消耗你组织的标准 ITPM/OTPM 限制。

Files and Skills endpoints use the standard tier-based rate limits.

Files 与 Skills 端点使用标准的按层级速率限制。

When a limit is exceeded the API returns 429 with a rate_limit_error (see Error Handling for the response envelope) and a retry-after header indicating how many seconds to wait before retrying. The Anthropic SDK reads this header and retries automatically.

超限时 API 返回 429 和 rate_limit_error（响应信封见错误处理），并附带一个 retry-after 响应头，指明重试前要等待的秒数。Anthropic SDK 会读取该响应头并自动重试。