OpenSkillIndex← back to search
claude-code

build-managed-agents

教 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。

install
source · Clone the upstream repo
git clone https://github.com/YijiaDuan/build-managed-agents
Claude Code · Install into ~/.claude/skills/
git clone --depth=1 https://github.com/YijiaDuan/build-managed-agents ~/.claude/skills/yijiaduan-build-managed-agents-build-managed-agents
manifest: SKILL.md
source content

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 管理工具

官方文档