返回专栏
Agent SDK/03 · Claude/3.4

Claude Managed Agents

Managed Agents 是一个预置、可配置、运行在托管基础设施上的 agent harness。

预计阅读
14分钟
全文字数
2,280字
资料截至
2026-10-09
Agent SDK · Claude3.4
版本与时效声明
  • 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 使用。
本文要点
  1. Managed Agents 是一个预置、可配置、运行在托管基础设施上的 agent harness。Anthropic 负责运行循环、托管沙箱、保存会话,你通过 REST 接口和 SSE 与它交互1。
  2. 四个核心概念:Agent(模型、system、tools、MCP、skills)、Environment(云端沙箱或自托管沙箱)、Session(一个运行中的 agent 实例)、Events(双向的消息)1。
  3. 计费由两部分组成:token 费用,加上 $0.08/会话小时 的运行时费用。只计算处于 running 状态的时间,空闲等待不计费3。
  4. 和 2.4 OpenAI Agents API 是同一类产品,也就是分层模型里的 L5。

1. 定位:与 Messages API、Agent SDK 有什么不同#

Messages APIClaude Managed Agents
是什么直接调用模型预置、可配置的 agent harness,运行在托管基础设施上
适合自定义 agent 循环,需要精细控制长时间运行的任务、异步工作

以上取自官方文档1。

Agent SDKManaged Agents
循环在哪运行你的进程,内部再启动一个 CLI 子进程Anthropic 的编排层
工具在哪执行你的机器或容器每个会话独占的云端容器,也可以是自托管沙箱
部署运维你自己负责Anthropic 负责
状态本地 JSONL;跨主机需要自己配置 SessionStore服务端持久化:对话、沙箱状态、产物

官方列出的适用场景1:

  • 长时间执行,任务持续数分钟到数小时;
  • 需要安全的云端沙箱;
  • 需要自托管执行,以满足合规或数据驻留要求;
  • 不想自己搭基础设施;
  • 需要有状态的会话;
  • 需要按 cron 定时运行,即 scheduled deployments。
数据合规

Managed Agents 的设计是有状态的:对话历史、沙箱状态和产物都保存在服务端。因此它目前不符合零数据保留(ZDR)的要求,也不在 HIPAA BAA 的覆盖范围内。你可以自行删除会话和文件1。


2. 四个核心概念与生命周期#

Events(SSE)

user.* ⇄ agent.* / session.*

Agent(创建一次,多次复用)

model / system / tools / MCP / skills

有版本号

Session(每次运行创建一个)

引用 agent 与 environment

Environment

cloud:Anthropic 托管容器

self_hosted:你自己的沙箱

你的应用

Events(SSE)

user.* ⇄ agent.* / session.*

Agent(创建一次,多次复用)

model / system / tools / MCP / skills

有版本号

Session(每次运行创建一个)

引用 agent 与 environment

Environment

cloud:Anthropic 托管容器

self_hosted:你自己的沙箱

你的应用

官方给出的流程是五步1:

  1. 创建 Agent,定义模型、系统提示词、工具、MCP 和 skills;只创建一次,之后通过 ID 引用。
  2. 创建 Environment,选择云端沙箱或自托管沙箱。
  3. 启动 Session,引用 agent 和 environment。
  4. 发送事件、接收流式结果:用户消息以事件的形式发送,Claude 自主调用工具,结果通过 SSE 推送回来。事件历史保存在服务端,可以完整拉取。
  5. 引导或中断:在 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 和 environment
session = 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。

stream-first 原则

事件流只会推送它打开之后产生的事件,所以要先打开流,再发送事件,否则可能出现竞态,漏掉早期的事件5。


4. 内置工具与权限策略#

工具名称说明
Bashbash在 shell 会话中执行命令
Readread读取沙箱中的文件
Writewrite写文件
Editedit对文件做字符串替换
Globglob按 glob 模式匹配文件
Grepgrep用正则搜索文本
Web fetchweb_fetch抓取 URL 的内容
Web searchweb_search搜索网页
  • 在 agent 配置里加入 agent_toolset_20260401,上面这些工具默认全部启用。可以用 configs 禁用某个工具,或者覆盖它的设置6。
  • 单次工具输出超过 10 万字符(约 2.5 万 token)时,会被自动写入沙箱里的文件,模型只收到截断的预览和文件路径6。

权限策略只管服务端执行的工具,包括内置工具集和 MCP 工具集7:

策略行为
always_allow自动执行,不需要确认。这是内置工具集的默认值
always_ask会话暂停,等你批准后再执行。这是 MCP 工具集的默认值
auto由服务端逐个评估每次调用:直接执行、拒绝,或者暂停等待审批

自定义工具由你的应用执行,执行与否完全由你控制,所以不受权限策略管辖7。


5. 自定义工具:在你这边执行#

整体流程5:

  1. 会话发出一个 agent.custom_tool_use 事件,里面包含工具名和输入;
  2. 你在自己的系统里执行这个工具;
  3. 发送 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 中8Multiagent orchestration
Vaults凭据保存在 vault 里,在出站请求时才替换成真实值,沙箱里看不到真实的密钥Vaults
MCP connector在 agent 上声明 MCP server,凭据通过 vault 注入MCP connector
Skills打包好的技能,可以从 GitHub 仓库的 .claude/skills 目录加载2Skills
Memory stores跨会话的记忆存储Memory
Scheduled deployments按 cron 定时自动启动会话Overview
Session budgets给单个会话设置花费上限;达到上限后以 budget_reached 暂停2Budgets
Self-hosted sandboxes工具在你的基础设施上执行,循环仍由 Anthropic 运行Self-hosted sandboxes
Webhooks会话、环境、memory store 的生命周期事件推送Webhooks
ant CLIant beta:sessions connect 可以把终端挂到一个会话上,实时查看并审批工具调用2CLI

会话停下时,stop_reason.type 会说明原因5:

stop_reason.type含义你要做什么
end_turnagent 完成了这一轮,或者被你中断发送新的 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 AgentsOpenAI Agents API
Agent 配置client.beta.agents.create,有版本号client.beta.agents.create,也可以在创建会话时内联配置
环境cloud / self_hostednone / openai_hosted / self_hosted
会话client.beta.sessionsclient.beta.agents.sessions
事件命名user.message、agent.message、session.status_idle 等agent.session.input.message、agent.session.turn.completed 等
多 Agent协调者加 roster,各自有独立的 threadmulti_agent.enabled,加上托管的 subagent
凭据VaultsVaults
运行时计费$0.08 / 会话小时沙箱按容器价格计费
底层 harnessAnthropic 的托管 harnessOpenAI 的 Codex harness

这张表是笔者根据两家文档整理的。两者在 2026 年先后推出,概念上几乎一一对应。可以看出,“托管 harness 加沙箱加持久会话”已经成为两家共同的产品形态。


小结#

  • Managed Agents 适合长时间运行、需要沙箱、不想自己运维的 agent 任务。agent 只创建一次,每次运行开一个新会话。
  • 写客户端代码时要记住三点:先开流再发送、按 stop_reason 区分完成、待处理动作、预算耗尽、自定义工具的结果用 custom_tool_use_id 回传。
  • 如果需要完全掌控运行环境,或者有 ZDR 要求,改用 3.3 Claude Agent SDK 或 Messages API。

相关笔记#

参考资料#

注释与出处#

  1. Anthropic,Claude Managed Agents overview,https://platform.claude.com/docs/en/managed-agents/overview ↩ ↩2 ↩3 ↩4 ↩5 ↩6 ↩7 ↩8

  2. 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

  3. Anthropic,Pricing(Claude Managed Agents pricing 一节),https://platform.claude.com/docs/en/about-claude/pricing ↩ ↩2 ↩3

  4. Anthropic,Get started with Claude Managed Agents,https://platform.claude.com/docs/en/managed-agents/quickstart ↩

  5. Anthropic,Session event stream(Event types、stream-first、自定义工具结果、stop_reason),https://platform.claude.com/docs/en/managed-agents/events-and-streaming ↩ ↩2 ↩3 ↩4

  6. Anthropic,Tools(Managed Agents),https://platform.claude.com/docs/en/managed-agents/tools ↩ ↩2

  7. Anthropic,Permission policies,https://platform.claude.com/docs/en/managed-agents/permission-policies ↩ ↩2

  8. Anthropic,Multiagent orchestration,https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration ↩

输入关键词开始搜索。多个关键词用空格分隔。