build-managed-agents

一个给 coding agent 用的 skill —— 装到 Claude Code / OpenClaw / Cursor 等编程代理上，当用户说"帮我搞一个 managed agent"的时候，这个 skill 会接管，照着 recipe 一步步调 Anthropic 新出的 Claude Managed Agents API，覆盖 create / run / audit 全流程：定义 agent + environment、跑 session、流式处理事件、审计 token 用量和事件链。

把自己搭 agent loop / 工具执行 / 沙箱 / SSE 解析 / 审计日志这堆基础设施全卸掉，直接让 coding agent 去调 Anthropic 托管的那套。

安装

# 全局（推荐，所有项目可用）
git clone https://github.com/YijiaDuan/build-managed-agents \
  ~/.claude/skills/build-managed-agents

# 或只装到当前项目
mkdir -p .claude/skills
git clone https://github.com/YijiaDuan/build-managed-agents \
  .claude/skills/build-managed-agents

运行时依赖：

pip install anthropic          # 或 npm install @anthropic-ai/sdk
export ANTHROPIC_API_KEY="sk-ant-..."

使用

在 Claude Code 对话框里随便说一句：

• "帮我创建一个 managed agent，做 XXX"
• "给这个 session 做个审计，看 token 消耗和事件流"
• "用 client.beta.sessions.events.stream 写一个 XXX"
• "open-source this as a managed agent"

Claude 会自动匹配到这个 skill 并按 reference/ 下的参考文档执行。完整 recipe 在 SKILL.md。

它覆盖什么

 Create ──────► Run ──────► Audit
   │             │           │
   │             │           ├─ 列出所有 session 状态
   │             │           ├─ 拉完整事件流（审计链）
   │             │           ├─ token 用量 + 成本估算
   │             │           └─ 导出 Markdown 报告
   │             │
   │             ├─ 发 user.message
   │             ├─ 流式接收 agent.message / tool_use
   │             ├─ 处理 custom_tool_use 闭环
   │             ├─ tool_confirmation（always_ask）
   │             ├─ interrupt 中断
   │             └─ 多 agent / memory stores（研究预览）
   │
   ├─ 创建 Agent（model + system + tools + MCP + skills）
   ├─ 创建 Environment（云容器 + 预装包 + 网络规则）
   └─ 创建 Session（挂 GitHub repo / 文件 / memory）

项目结构

build-managed-agents/
├── SKILL.md                 # 入口：触发词 + 工作流速查 + 陷阱清单
├── reference/
│   ├── create.md            # Agent/Environment/Session 完整参数
│   ├── run.md               # 事件收发、多 agent、memory stores
│   ├── events.md            # 全部事件类型 schema
│   ├── audit.md             # 列表查询、用量、成本、导出
│   └── errors.md            # 错误类型、重试、状态机
├── scripts/
│   ├── quickstart.py        # 一键跑通 create→run→audit 模板
│   └── admin.py             # CLI: list/show/export/stats/cost/cleanup
├── README.md
├── LICENSE
└── .gitignore

SKILL.md 保持精简（6KB），细节按需加载 reference/ 下的参考文件。scripts/ 是可以直接拿去跑的模板和管理工具，不是装饰。

踩坑预警（从 SKILL.md 精选）

• stream 顺序不能反。先 .stream() 打开通道再 .send() 发消息，反了会丢前几个事件。
• custom tool 必须回结果。收到 agent.custom_tool_use 必须发 user.custom_tool_result（is_error=True 也行），否则 session 永远卡在 idle。
• Agent 版本漂移。生产环境要 pin agent={"type": "agent", "id": "...", "version": N}，否则 update 后新 session 静默升级。
• Running session 不能 delete。先 user.interrupt 让它进 idle。
• Archive 优先于 delete。archive 保留审计链，delete 是永久的。
• Rate limits：创建类 60/min、读取类 600/min，列表类操作用 pagination。
• Beta header：研究预览功能（outcomes / 多 agent / memory stores）需要额外一个 beta header。

不适合用在

• 毫秒级实时交互 —— 用 Messages API 更合适。
• 简单单轮问答 —— 上 managed agents 是杀鸡用牛刀。
• 没有云端工具需求的纯文本生成 —— 直接用模型。

License

MIT © Yijia Duan