- Managed Agents 目前处于 beta 阶段。所有端点都需要带上请求头
managed-agents-2026-04-01,用 SDK 时会自动添加1。它于 2026-04-08 开始公测2。本文基于anthropic(Python)1.12.1,入口是client.beta.agents、client.beta.environments、client.beta.sessions等。 - beta 期间行为可能会调整,官方原话是 “Behaviors may be refined between releases”1。文中代码已用 pyright 对照 1.12.1 做过类型检查;没有 API Key,因此没有实际运行。
- 资料截至 2026-10-09,本文不随官方同步更新,请对照 Managed Agents 文档 和 Release notes 使用。
- Managed Agents 是一个预置、可配置、运行在托管基础设施上的 agent harness。Anthropic 负责运行循环、托管沙箱、保存会话,你通过 REST 接口和 SSE 与它交互1。
- 四个核心概念:Agent(模型、system、tools、MCP、skills)、Environment(云端沙箱或自托管沙箱)、Session(一个运行中的 agent 实例)、Events(双向的消息)1。
- 计费由两部分组成:token 费用,加上 $0.08/会话小时 的运行时费用。只计算处于
running状态的时间,空闲等待不计费3。 - 和 2.4 OpenAI Agents API 是同一类产品,也就是分层模型里的 L5。
1. 定位:与 Messages API、Agent SDK 有什么不同#
| Messages API | Claude Managed Agents | |
|---|---|---|
| 是什么 | 直接调用模型 | 预置、可配置的 agent harness,运行在托管基础设施上 |
| 适合 | 自定义 agent 循环,需要精细控制 | 长时间运行的任务、异步工作 |
以上取自官方文档1。
| Agent SDK | Managed Agents | |
|---|---|---|
| 循环在哪运行 | 你的进程,内部再启动一个 CLI 子进程 | Anthropic 的编排层 |
| 工具在哪执行 | 你的机器或容器 | 每个会话独占的云端容器,也可以是自托管沙箱 |
| 部署运维 | 你自己负责 | Anthropic 负责 |
| 状态 | 本地 JSONL;跨主机需要自己配置 SessionStore | 服务端持久化:对话、沙箱状态、产物 |
官方列出的适用场景1:
- 长时间执行,任务持续数分钟到数小时;
- 需要安全的云端沙箱;
- 需要自托管执行,以满足合规或数据驻留要求;
- 不想自己搭基础设施;
- 需要有状态的会话;
- 需要按 cron 定时运行,即 scheduled deployments。
Managed Agents 的设计是有状态的:对话历史、沙箱状态和产物都保存在服务端。因此它目前不符合零数据保留(ZDR)的要求,也不在 HIPAA BAA 的覆盖范围内。你可以自行删除会话和文件1。
2. 四个核心概念与生命周期#
官方给出的流程是五步1:
- 创建 Agent,定义模型、系统提示词、工具、MCP 和 skills;只创建一次,之后通过 ID 引用。
- 创建 Environment,选择云端沙箱或自托管沙箱。
- 启动 Session,引用 agent 和 environment。
- 发送事件、接收流式结果:用户消息以事件的形式发送,Claude 自主调用工具,结果通过 SSE 推送回来。事件历史保存在服务端,可以完整拉取。
- 引导或中断:在 agent 执行过程中,可以发送新的用户事件来调整方向,或者直接中断。
3. 完整示例:从零跑通一个会话#
from anthropic import Anthropic
client = Anthropic()
# 1) Agent:只创建一次,保存 agent.id,之后每次开会话都引用它agent = client.beta.agents.create( name="Coding Assistant", model="claude-opus-5-5", system="你是一个编程助手,写干净、有文档的代码。", tools=[{"type": "agent_toolset_20260401"}], # 内置工具集:bash、read、write、edit、glob、grep、web)
# 2) Environment:云端容器,网络受限,但允许访问包管理器environment = client.beta.environments.create( name="quickstart-env", config={"type": "cloud", "networking": {"type": "limited", "allow_package_managers": True}},)
# 3) Session:引用 agent 和 environmentsession = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, title="Quickstart session")
# 4) 先打开事件流,再发送消息(stream-first,避免漏掉早期事件)with client.beta.sessions.events.stream(session.id) as stream: client.beta.sessions.events.send( session.id, events=[ { "type": "user.message", "content": [{"type": "text", "text": "写一个 Python 脚本,生成前 20 个斐波那契数并保存到 fibonacci.txt"}], } ], ) for event in stream: if event.type == "agent.message": for block in event.content: if block.type == "text": print(block.text, end="") elif event.type == "agent.tool_use": print(f"\n[使用工具:{event.name}]") elif event.type == "session.status_idle": print("\n\nAgent 完成。") break这个例子改编自官方 quickstart4。
事件流只会推送它打开之后产生的事件,所以要先打开流,再发送事件,否则可能出现竞态,漏掉早期的事件5。
4. 内置工具与权限策略#
| 工具 | 名称 | 说明 |
|---|---|---|
| Bash | bash | 在 shell 会话中执行命令 |
| Read | read | 读取沙箱中的文件 |
| Write | write | 写文件 |
| Edit | edit | 对文件做字符串替换 |
| Glob | glob | 按 glob 模式匹配文件 |
| Grep | grep | 用正则搜索文本 |
| Web fetch | web_fetch | 抓取 URL 的内容 |
| Web search | web_search | 搜索网页 |
- 在 agent 配置里加入
agent_toolset_20260401,上面这些工具默认全部启用。可以用configs禁用某个工具,或者覆盖它的设置6。 - 单次工具输出超过 10 万字符(约 2.5 万 token)时,会被自动写入沙箱里的文件,模型只收到截断的预览和文件路径6。
权限策略只管服务端执行的工具,包括内置工具集和 MCP 工具集7:
| 策略 | 行为 |
|---|---|
always_allow | 自动执行,不需要确认。这是内置工具集的默认值 |
always_ask | 会话暂停,等你批准后再执行。这是 MCP 工具集的默认值 |
auto | 由服务端逐个评估每次调用:直接执行、拒绝,或者暂停等待审批 |
自定义工具由你的应用执行,执行与否完全由你控制,所以不受权限策略管辖7。
5. 自定义工具:在你这边执行#
整体流程5:
- 会话发出一个
agent.custom_tool_use事件,里面包含工具名和输入; - 你在自己的系统里执行这个工具;
- 发送
user.custom_tool_result事件,用custom_tool_use_id关联到对应的调用。
from anthropic import Anthropic
client = Anthropic()
agent = client.beta.agents.create( name="Code Reviewer", model="claude-opus-5-5", system="你是资深代码审查者。", tools=[ {"type": "agent_toolset_20260401"}, { "type": "custom", "name": "run_tests", "description": "运行测试套件", "input_schema": { "type": "object", "properties": {"test_path": {"type": "string", "description": "测试文件路径"}}, "required": ["test_path"], }, }, ],)
def run_custom_tool(name: str, tool_input: dict) -> str: return "All 42 tests passed." if name == "run_tests" else f"Unknown tool: {name}"
def run_session(session_id: str) -> None: while True: pending = [] with client.beta.sessions.events.stream(session_id) as stream: for event in stream: if event.type == "agent.message": for block in event.content: if block.type == "text": print(block.text, end="", flush=True) elif event.type == "agent.custom_tool_use": pending.append(event) # 收集需要我们执行的调用 elif event.type == "session.status_idle": break elif event.type == "session.status_terminated": return if not pending: return client.beta.sessions.events.send( session_id, events=[ { "type": "user.custom_tool_result", "custom_tool_use_id": call.id, "content": [{"type": "text", "text": run_custom_tool(call.name, call.input)}], } for call in pending ], )这个例子改编自 Anthropic 官方的 Python 示例写法,事件名以官方 Events and streaming 页面为准5。
6. 进阶能力一览#
| 能力 | 一句话说明 | 文档 |
|---|---|---|
| Outcomes(结果标准) | 用 user.define_outcome 加一份评分标准(rubric)启动会话。harness 对每一轮产出打分,agent 不断修改,直到达标 | Define outcomes |
| Multiagent | 协调者 agent 把任务委派给 roster 中的其他 agent。所有 agent 共享同一个沙箱、文件系统和 vault 凭据,但各自运行在上下文隔离的 session thread 中8 | Multiagent orchestration |
| Vaults | 凭据保存在 vault 里,在出站请求时才替换成真实值,沙箱里看不到真实的密钥 | Vaults |
| MCP connector | 在 agent 上声明 MCP server,凭据通过 vault 注入 | MCP connector |
| Skills | 打包好的技能,可以从 GitHub 仓库的 .claude/skills 目录加载2 | Skills |
| Memory stores | 跨会话的记忆存储 | Memory |
| Scheduled deployments | 按 cron 定时自动启动会话 | Overview |
| Session budgets | 给单个会话设置花费上限;达到上限后以 budget_reached 暂停2 | Budgets |
| Self-hosted sandboxes | 工具在你的基础设施上执行,循环仍由 Anthropic 运行 | Self-hosted sandboxes |
| Webhooks | 会话、环境、memory store 的生命周期事件推送 | Webhooks |
ant CLI | ant beta:sessions connect 可以把终端挂到一个会话上,实时查看并审批工具调用2 | CLI |
会话停下时,stop_reason.type 会说明原因5:
stop_reason.type | 含义 | 你要做什么 |
|---|---|---|
end_turn | agent 完成了这一轮,或者被你中断 | 发送新的 user.message |
requires_action | 有工具调用在等你回应,比如自定义工具或确认请求 | 逐个回应这些阻塞的调用 |
budget_reached | 会话花费达到了预算上限 | 调整或移除预算后会自动恢复 |
7. 计费#
| 维度 | 价格 | 计量方式 |
|---|---|---|
| Token | 按所用模型的标准价格计费,prompt caching 的倍率同样适用 | 与 Messages API 相同 |
| 会话运行时 | $0.08 / 会话小时 | 只计算 running 状态的时长 |
| Web 搜索 | $10 / 千次 | 与 Messages API 相同 |
以上取自官方定价页3。使用 Managed Agents 时,会话运行时费用取代了代码执行工具按容器小时计费的方式,不会重复收取容器费用3。
8. Managed Agents 与 OpenAI Agents API 对照#
| 概念 | Claude Managed Agents | OpenAI Agents API |
|---|---|---|
| Agent 配置 | client.beta.agents.create,有版本号 | client.beta.agents.create,也可以在创建会话时内联配置 |
| 环境 | cloud / self_hosted | none / openai_hosted / self_hosted |
| 会话 | client.beta.sessions | client.beta.agents.sessions |
| 事件命名 | user.message、agent.message、session.status_idle 等 | agent.session.input.message、agent.session.turn.completed 等 |
| 多 Agent | 协调者加 roster,各自有独立的 thread | multi_agent.enabled,加上托管的 subagent |
| 凭据 | Vaults | Vaults |
| 运行时计费 | $0.08 / 会话小时 | 沙箱按容器价格计费 |
| 底层 harness | Anthropic 的托管 harness | OpenAI 的 Codex harness |
这张表是笔者根据两家文档整理的。两者在 2026 年先后推出,概念上几乎一一对应。可以看出,“托管 harness 加沙箱加持久会话”已经成为两家共同的产品形态。
小结#
- Managed Agents 适合长时间运行、需要沙箱、不想自己运维的 agent 任务。agent 只创建一次,每次运行开一个新会话。
- 写客户端代码时要记住三点:先开流再发送、按
stop_reason区分完成、待处理动作、预算耗尽、自定义工具的结果用custom_tool_use_id回传。 - 如果需要完全掌控运行环境,或者有 ZDR 要求,改用 3.3 Claude Agent SDK 或 Messages API。
相关笔记#
参考资料#
注释与出处#
-
Anthropic,Claude Managed Agents overview,https://platform.claude.com/docs/en/managed-agents/overview ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8
-
Anthropic,Release notes(2026-04-08 公测;session budgets、ant CLI 的 sessions connect、从 GitHub 加载 skills 等条目),https://platform.claude.com/docs/en/release-notes/overview ↩ ↩2 ↩3 ↩4
-
Anthropic,Pricing(Claude Managed Agents pricing 一节),https://platform.claude.com/docs/en/about-claude/pricing ↩ ↩2 ↩3
-
Anthropic,Get started with Claude Managed Agents,https://platform.claude.com/docs/en/managed-agents/quickstart ↩
-
Anthropic,Session event stream(Event types、stream-first、自定义工具结果、stop_reason),https://platform.claude.com/docs/en/managed-agents/events-and-streaming ↩ ↩2 ↩3 ↩4
-
Anthropic,Tools(Managed Agents),https://platform.claude.com/docs/en/managed-agents/tools ↩ ↩2
-
Anthropic,Permission policies,https://platform.claude.com/docs/en/managed-agents/permission-policies ↩ ↩2
-
Anthropic,Multiagent orchestration,https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration ↩