fanfei's blog

Claude Managed Agents

Anthropic 官方推出的托管 Agent 平台（Beta），提供完整的 Agent 运行基础设施：云端容器、工具执行、会话状态管理和 Agent 编排，让开发者只需定义 Agent 行为，无需自己搭建 Agent loop 和 sandbox。

Compiled Truth

核心定位

Claude Managed Agents 是 Agent-as-a-Service。与 Messages API（直接调用模型、自己管理 loop）相比，它把整个 Agent 运行时托管出去：

Messages API Claude Managed Agents
适合 自定义 Agent loop、精细控制 长任务、异步工作
你负责 一切 只定义 Agent 配置
基础设施 自建 Anthropic 托管

这与 pi（本地 harness）、Hermes 等框架的思路一脉相承，区别在于这是云端托管版本，不需要在本地运行任何 harness 代码。

四个核心概念

概念 是什么
Agent 可复用的配置：模型 + 系统提示 + 工具 + MCP + Skills。创建一次，通过 ID 跨会话引用。支持版本管理。
Environment 云端容器模板：预装软件包、网络访问控制。多个 Session 可共享同一 Environment。
Session 一次具体的运行实例：Agent + Environment + 任务。有独立的容器和对话历史。
Events 双向事件流（SSE）：你发送 user events，收到 agent/session events。历史持久化在服务器端。

工作流

定义 Agent (一次) → 创建 Environment (一次) → 启动 Session
    → POST /sessions/:id/events  (发指令)
    → GET  /sessions/:id/stream  (收 SSE)
    → 中途可 interrupt / 追加消息
    → session.status_idle = 任务完成

内置工具（agent_toolset_20260401）

工具 能力
bash 在容器内执行 shell 命令
read / write / edit 文件读写编辑
glob / grep 文件搜索
web_fetch 抓取 URL 内容
web_search 网络搜索

可以通过 configs 数组精细控制每个工具的开关和权限策略（always_allow / always_ask）。

容器规格

  • OS: Ubuntu 22.04 LTS, x86_64
  • 内存: 最多 8 GB，磁盘: 最多 10 GB
  • 预装语言: Python 3.12+, Node.js 20+, Go 1.22+, Rust 1.77+, Java 21+, Ruby 3.3+, PHP 8.3+, C/C++
  • 网络: 默认关闭，可配置 unrestricted 或 limited（白名单）

关键设计决策

权限策略（Permission Policies）

两种策略控制工具执行：

  • always_allow — 自动执行（agent_toolset 默认）
  • always_ask — 暂停等待用户确认（MCP toolset 默认，防止新工具未经审批自动运行）

可以在 toolset 级别设置默认策略，再用 configs 对单个工具覆盖（例如：全局 allow，但 bash 单独 ask）。

事件驱动的执行模型

Session 是状态机，Events 驱动状态转换：

  • idle → 收到 user.message → running → 工具调用完成 → idle
  • 任何时候可发送 user.interrupt 中断，再发 user.message 重定向

Vault（凭证管理）

MCP 认证通过 Vault 与 Agent 定义解耦：

  • Agent 声明 MCP 服务器 URL（无 token）
  • Session 创建时传入 vault_ids（含 OAuth token）
  • Anthropic 负责 token 刷新

这样同一个 Agent 定义可以为不同用户挂载不同凭证（一用户一 Vault）。

三个研究预览功能

功能 描述
Outcomes 目标驱动模式：定义 rubric，Agent 自动迭代直到满足评分标准。有独立 Grader 在单独 context 中评判，避免被主 Agent 的实现路径影响。
Memory 跨 Session 持久记忆：Memory Store 存储文本文档，Agent 在任务前自动读取、任务后自动写入。每次修改生成不可变版本，支持审计和回滚。最多 8 个 store/session。
Multiagent 多 Agent 编排：一个 Coordinator Agent 可调用多个 Sub-Agent，各自有独立的 context（thread），共享同一容器和文件系统。仅支持一层委派。

与 pi / Hermes 的对比

维度 pi (本地 harness) Hermes Claude Managed Agents
运行位置 本地 本地 云端 (Anthropic)
Agent loop 自定义 自定义 托管
持久记忆 无内置 有（跨 session 记忆） Memory Store（研究预览）
Skills 有（本地 .md 文件） 有 有（文件系统级别）
多 Agent 通过 pi-teams 无 Multiagent Sessions
工具执行 本地进程 本地进程 云端容器
控制粒度 高 高 中（配置式）

API 访问

  • Beta header 必须: anthropic-beta: managed-agents-2026-04-01
  • Research preview 额外 header: managed-agents-2026-04-01-research-preview
  • SDK 自动设置这些 header
  • CLI 工具: ant（brew install anthropics/tap/ant）
  • Rate limits: Create 60 req/min，Read 600 req/min

Timeline

  • 2026-04-15: 初始整理自 Anthropic 官方文档（共 17 个子页面），包括 Overview、Quickstart、Agent Setup、Tools、MCP Connector、Permission Policies、Skills、Environments、Container Reference、Sessions、Events & Streaming、Define Outcomes、Vaults、GitHub、Files、Memory、Multiagent Sessions

相关条目