build-managed-agents

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  # 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 即可。

常见陷阱

1. Agent 版本漂移：生产环境要 pin 版本 agent={"type": "agent", "id": "...", "version": N}，否则 update 后静默升级
2. Stream 顺序：先 .stream() 打开通道，再 .send() 发消息，顺序反了会丢事件
3. Custom tool 悬挂：收到 agent.custom_tool_use 必须回 user.custom_tool_result（is_error=True 也行），否则 session 永远 idle
4. Tool confirmation：always_ask 权限下 agent 会停在 session.status_idle 且 stop_reason.type="requires_action"，需要 user.tool_confirmation 放行
5. Rate limits：Create 类 60/min，Read 类 600/min。列表操作尽量用 limit + pagination
6. Archive vs Delete：优先 archive（保留审计），delete 是永久的
7. Running session 不能 delete：先发 user.interrupt 让它 idle

参考文件索引

• reference/create.md — Agent/Environment/Session 完整创建参数
• reference/run.md — 事件收发、流式、多 agent、memory stores、outcomes
• reference/events.md — 所有事件类型 schema（agent.* / user.* / session.* / span.*）
• reference/audit.md — 列表查询、用量统计、成本估算、合规审计
• reference/errors.md — 错误类型、重试策略、状态机
• scripts/quickstart.py — 可运行模板
• scripts/admin.py — CLI 管理工具

官方文档

• https://platform.claude.com/docs/en/managed-agents/overview
• https://platform.claude.com/docs/en/managed-agents/quickstart
• https://platform.claude.com/docs/en/api/agents