| name | build-managed-agents |
| description | 教 Claude Code / OpenClaw 等 coding agent 使用 Anthropic Claude Managed Agents（云端托管代理服务）API —— create/run/audit 全流程。当用户（或上游 coding agent）需要创建托管 agent、跑 session、流式处理事件、审计用量或调用 /v1/agents、/v1/environments、/v1/sessions 等 API 时使用。触发词：managed agents、托管代理、build a managed agent、agent_toolset_20260401、client.beta.agents、client.beta.sessions。 |
build-managed-agents
这是一个给 coding agent（Claude Code / OpenClaw / Cursor agent 等）用的 skill —— 当 coding agent 需要帮用户构建基于 Claude Managed Agents 的应用时，照着本 skill 的 recipe 执行。
Anthropic 托管的 agent 运行时：云容器 + 内置工具 + 事件流。你不用自己搭 agent loop、工具执行、沙箱。
本 skill 覆盖三个阶段：Create（定义 agent/环境/session）→ Run（发消息、流式接收、处理工具确认）→ Audit（查状态、事件流、token 用量、成本）。
何时使用
- 用户要"创建一个 managed agent" / "托管 agent" / "跑一个 session"
- 代码里出现
client.beta.agents、client.beta.environments、client.beta.sessions
- 用户询问
/v1/agents、/v1/environments、/v1/sessions 等端点
- 用户要审计/调试 session（看事件流、token 消耗、错误重试）
前置条件
pip install anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
所有 API 需要 beta header：anthropic-beta: managed-agents-2026-04-01（SDK 自动加）。
Research preview 功能（outcomes / 多 agent / memory stores）需额外：managed-agents-2026-04-01-research-preview。
核心概念速查
| 概念 | 说明 | 生命周期 |
|---|
| Agent | 模型 + system prompt + 工具 + MCP + skills | 复用，有版本号 |
| Environment | 云容器模板（预装包、网络规则） | 复用 |
| Session | 一次运行实例（Agent × Environment） | 一次性，有完整事件流 |
| Event | 会话中每条消息/工具调用/状态变更 | 永久存储，可审计 |
标准工作流
1. Create 阶段（一次性）
from anthropic import Anthropic
client = Anthropic()
agent = client.beta.agents.create(
name="My Agent",
model="claude-sonnet-4-6",
system="你的 system prompt",
tools=[{"type": "agent_toolset_20260401"}],
)
env = client.beta.environments.create(
name="my-env",
config={"type": "cloud", "networking": {"type": "unrestricted"}},
)
详细参数、MCP、skills、自定义工具、权限策略 → 见 reference/create.md
2. Run 阶段（每个任务一次）
session = client.beta.sessions.create(agent=agent.id, environment_id=env.id)
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": "..."}]}],
)
for event in stream:
match event.type:
case "agent.message":
for block in event.content:
print(block.text, end="")
case "agent.tool_use":
pass
case "agent.custom_tool_use":
...
case "session.status_idle":
break
关键细节：
- 必须先开 stream 再 send（不然前几个事件丢失）
- 遇到
always_ask 权限的工具，agent 会停下等 user.tool_confirmation
- 遇到
agent.custom_tool_use，你必须回 user.custom_tool_result，否则 session 卡死
- 要中断 agent 用
user.interrupt
完整事件类型表、图片/文档输入、多 agent、outcomes、memory stores → 见 reference/run.md 和 reference/events.md
3. Audit 阶段（任何时候）
for s in client.beta.sessions.list(limit=50):
print(s.id, s.status, s.usage.input_tokens + s.usage.output_tokens)
for evt in client.beta.sessions.events.list(session_id):
print(evt.type, evt.processed_at)
s = client.beta.sessions.retrieve(session_id)
print(s.usage, s.stats)
成本估算、按时间段过滤、错误分类统计 → 见 reference/audit.md
可用脚本
scripts/quickstart.py — 一键跑通 create→run→audit 的最小模板scripts/admin.py — 管理工具（list-sessions / show / stats / cleanup）
直接 copy 到项目里改 system prompt 即可。
常见陷阱
- Agent 版本漂移：生产环境要 pin 版本
agent={"type": "agent", "id": "...", "version": N}，否则 update 后静默升级
- Stream 顺序：先
.stream() 打开通道，再 .send() 发消息，顺序反了会丢事件
- Custom tool 悬挂：收到
agent.custom_tool_use 必须回 user.custom_tool_result（is_error=True 也行），否则 session 永远 idle
- Tool confirmation：
always_ask 权限下 agent 会停在 session.status_idle 且 stop_reason.type="requires_action"，需要 user.tool_confirmation 放行
- Rate limits：Create 类 60/min，Read 类 600/min。列表操作尽量用 limit + pagination
- Archive vs Delete：优先 archive（保留审计），delete 是永久的
- Running session 不能 delete：先发
user.interrupt 让它 idle
参考文件索引
reference/create.md — Agent/Environment/Session 完整创建参数reference/run.md — 事件收发、流式、多 agent、memory stores、outcomesreference/events.md — 所有事件类型 schema（agent.* / user.* / session.* / span.*）reference/audit.md — 列表查询、用量统计、成本估算、合规审计reference/errors.md — 错误类型、重试策略、状态机scripts/quickstart.py — 可运行模板scripts/admin.py — CLI 管理工具
官方文档
