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 # Python
# 或 npm install @anthropic-ai/sdk # TypeScript
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"}], # bash/read/write/edit/glob/grep/web_fetch/web_search
)
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":
# 自定义工具 — 你必须发 user.custom_tool_result 回去
...
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 阶段（任何时候）
# 列出所有 session 状态
for s in client.beta.sessions.list(limit=50):
print(s.id, s.status, s.usage.input_tokens + s.usage.output_tokens)
# 拉某个 session 的完整事件流（审计链）
for evt in client.beta.sessions.events.list(session_id):
print(evt.type, evt.processed_at)
# 看 token 用量 + 时长
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 管理工具