Skip to main content

前言​

随着Claude模型能力的持续提升，越来越多的开发团队希望借助AI完成更复杂、耗时更长的自动化任务——例如在真实代码库中进行多文件重构、自主执行端到端的数据分析流水线、或者在云端持续运行的研究助手。然而，构建一个生产级的智能体系统并不简单：开发者需要设计agent loop、管理沙箱安全隔离、处理工具调用错误、维护会话状态，以及解决长时任务中上下文窗口被耗尽等难题。

Managed Agents是Anthropic在Claude Platform上推出的解决方案——一个面向长时自主任务的托管智能体服务。它将智能体运行所需的基础设施（沙箱容器、工具执行层、会话持久化）统一托管，让开发者聚焦于定义智能体的行为和目标，而不是搭建和维护底层基础设施。

什么是Managed Agents​

Claude Managed Agents是Anthropic提供的预构建、可配置的智能体运行框架，运行在托管的云基础设施之上。与直接调用Messages API相比，它提供了完整的智能体运行时，包括：

  • 自动化的agent loop：无需自行编写驱动Claude循环调用工具直到任务完成的代码
  • 安全隔离的执行容器：每个Session拥有独立的云容器，Claude可以在其中执行Bash命令、读写文件、访问网络
  • 持久化的会话状态：会话事件日志保存在服务端，支持中断恢复和异步消费
  • 内置性能优化：自动的Prompt Caching、上下文压缩（Compaction）等机制，确保长时任务的高效运行
维度Messages APIClaude Managed Agents
定位直接模型调用，细粒度控制预构建智能体框架，长时自主任务
需自建完整的agent loop、沙箱、工具执行几乎不需要
适用场景自定义控制流、短对话长时任务、异步工作流
会话持久否（调用方管理状态）是（服务端持久化）
执行环境无托管云容器

设计思想：解耦Brain、Hands与Session​

Managed Agents的架构核心是将智能体系统分成三个独立、可替换的层次：

+---------+       execute(name, input)       +-----------+
|  Brain  | ───────────────────────────────> |   Hands   |
| (Claude |                                  | (Sandbox  |
| +harness)|  <── string result ──────────── |   Tools)  |
+---------+                                  +-----------+
     |
     | emitEvent / getEvents
     v
+---------+
| Session |  (append-only durable event log)
+---------+
  • Brain（大脑）：Claude模型及其harness（驱动模型循环调用工具的控制逻辑），完全无状态，可以独立扩展
  • Hands（手）：沙箱容器和工具——任何工具调用都抽象为execute(name, input) → string接口，容器宕机只是工具调用返回错误，可以重启新容器继续
  • Session（会话）：所有事件的持久化追加日志，保存在Brain和Hands之外，任何一方崩溃都不丢失进度

这种三层解耦带来了显著的工程优势：

  • 容错性：容器故障不导致会话丢失，harness崩溃后通过wake(sessionId)恢复，从上次事件继续
  • 安全性：凭据不存放在沙箱容器内，Claude生成的代码无法直接访问API Key
  • 性能：p50 TTFT（首Token延迟）降低约60%，p95降低超过90%
  • 灵活性：同一个Brain可以连接多个Hands，多个Brain可以共享Hands

与SubAgents和AgentTeams的区别​

理解三者的定位差异，有助于在实际场景中选择合适的工具：

特性SubAgentsAgentTeamsManaged Agents
运行环境Claude Code本地Claude Code本地云端托管基础设施
使用方式/agents命令或自动委托实验性功能，多实例协作REST API / SDK
典型场景主对话的子任务委托多维度并行任务协作长时自动化、异步后台任务
会话持久否（随主对话生命周期）否是（服务端持久化）
执行沙箱本地工作目录本地工作目录隔离的云容器
适合开发者使用Claude Code的开发者使用Claude Code的开发者构建AI产品的开发者
上下文隔离是（独立上下文窗口）是（每个实例独立）是（独立容器+独立上下文）
实验阶段GA实验性Beta

简而言之：

  • SubAgents — Claude Code内部的任务委托机制，解决上下文保护和工具权限约束问题
  • AgentTeams — Claude Code的多实例并行协作，解决同时探索多条路径的问题
  • Managed Agents — 面向开发者的平台级托管服务，解决在生产环境中可靠运行长时自主智能体的问题
NOTE

Managed Agents目前处于Beta阶段，所有请求需携带managed-agents-2026-04-01的Beta请求头。SDK会自动添加该头部。

核心概念​

Managed Agents围绕四个核心概念构建：

概念含义
Agent模型、系统提示、工具集、MCP服务器和Skills的组合配置
Environment云容器模板（预安装包、网络访问规则等）
Session在指定Environment中运行的智能体实例，执行具体任务并产生输出
Events应用程序与智能体之间交换的消息（用户消息、工具结果、状态更新等）

Agent​

Agent是一个可复用、带版本管理的配置对象，定义了Claude在会话中的行为方式。创建一次Agent，通过ID在所有Session中复用。

Agent的配置字段：

字段必填说明
name是智能体的可读名称
model是驱动智能体的Claude模型（支持Claude Sonnet 4.6及更新版本）
system否系统提示，定义智能体的行为和角色
tools否可用工具列表（内置工具集、MCP工具、自定义工具）
mcp_servers否提供标准化第三方能力的MCP服务器
skills否为特定领域提供专属上下文的Skills
callable_agents否可调用的其他智能体（多智能体编排，研究预览功能）
description否智能体功能的描述说明
metadata否任意键值对，用于自行追踪

每次更新Agent都会生成新版本，版本号从1开始递增。Agent可以被归档（Archive），归档后变为只读，已运行的Session继续正常工作，但无法再创建新Session引用该Agent。

Environment​

Environment定义了Session运行时的容器配置。多个Session可以共享同一个Environment，但每个Session拥有独立的容器实例，文件系统互不干扰。

Environment的主要配置项：

配置项说明
name唯一名称（组织内唯一）
config.type容器类型，目前为cloud
config.packages预安装包（pip、npm、apt等，会被缓存）
config.networking网络访问控制（unrestricted或limited）

Session​

Session是智能体执行具体任务的运行实例。每个Session引用一个Agent和一个Environment，拥有独立的容器、独立的上下文窗口和独立的事件日志。

Events​

Events是应用与智能体之间通信的基本单位，通过SSE（Server-Sent Events）实时流式传输。常见的事件类型：

事件类型方向含义
user.message应用→智能体发送用户消息
agent.message智能体→应用智能体的文本回复
agent.tool_use智能体→应用智能体正在调用某工具
agent.tool_result应用→智能体自定义工具的执行结果
session.status_idle智能体→应用智能体完成当前任务，进入空闲
session.status_error智能体→应用会话发生错误

内置工具​

使用agent_toolset_20260401工具类型可以一次性启用完整的内置工具集：

工具名name标识功能
Bashbash在容器内执行Shell命令
Readread读取文件内容
Writewrite写入文件
Editedit对文件执行字符串替换
Globglob快速文件模式匹配
Grepgrep使用正则表达式搜索文本
Web fetchweb_fetch从URL获取网页内容
Web searchweb_search在互联网上搜索信息

所有工具默认启用。可以通过configs数组单独禁用特定工具，或通过设置default_config.enabled: false然后仅显式启用所需工具。

快速上手​

前置条件​

  1. Anthropic Console账号
  2. 有效的API Key
  3. 设置环境变量：export ANTHROPIC_API_KEY="your-api-key-here"

完整流程​

Managed Agents的使用分为四步：创建Agent → 创建Environment → 启动Session → 发送消息并消费事件流。

第一步：创建Agent

agent=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/agents \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "name": "Coding Assistant",
      "model": "claude-sonnet-4-6",
      "system": "You are a helpful coding assistant. Write clean, well-documented code.",
      "tools": [
        {"type": "agent_toolset_20260401"}
      ]
    }'
)

AGENT_ID=$(jq -er '.id' <<< "$agent")
AGENT_VERSION=$(jq -er '.version' <<< "$agent")
echo "Agent ID: $AGENT_ID, version: $AGENT_VERSION"

第二步：创建Environment

environment=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/environments \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "name": "quickstart-env",
      "config": {
        "type": "cloud",
        "networking": {"type": "unrestricted"}
      }
    }'
)

ENVIRONMENT_ID=$(jq -er '.id' <<< "$environment")
echo "Environment ID: $ENVIRONMENT_ID"

第三步：启动Session

session=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d "{
      \"agent\": \"$AGENT_ID\",
      \"environment_id\": \"$ENVIRONMENT_ID\",
      \"title\": \"My first session\"
    }"
)

SESSION_ID=$(jq -er '.id' <<< "$session")
echo "Session ID: $SESSION_ID"

第四步：发送消息并消费事件流

# 发送用户消息（API会缓存事件，直到Stream连接建立后再消费）
curl -sS --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [
          {
            "type": "text",
            "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt"
          }
        ]
      }
    ]
  }' > /dev/null

# 建立SSE连接，实时消费事件流
while IFS= read -r line; do
  [[ $line == data:* ]] || continue
  json=${line#data: }
  case $(jq -r '.type' <<< "$json") in
    agent.message)
      jq -j '.content[] | select(.type == "text") | .text' <<< "$json"
      ;;
    agent.tool_use)
      printf '\n[Using tool: %s]\n' "$(jq -r '.name' <<< "$json")"
      ;;
    session.status_idle)
      printf '\n\nAgent finished.\n'
      break
      ;;
  esac
done < <(
  curl -sS -N --fail-with-body \
    "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "Accept: text/event-stream"
)

典型输出如下：

I'll create a Python script that generates the first 20 Fibonacci numbers.
[Using tool: write]
[Using tool: bash]
The script ran successfully. Let me verify the output file.
[Using tool: bash]
fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).

Agent finished.

执行过程说明​

当用户发送消息后，Managed Agents的内部流程如下：

User Event
    |
    v
[1] Provision Container  <-- based on Environment config
    |
    v
[2] Run Agent Loop       <-- Claude decides which tools to use
    |
    v
[3] Execute Tools        <-- bash, file ops, web search inside container
    |
    v
[4] Stream Events        <-- real-time SSE events to client
    |
    v
[5] session.status_idle  <-- agent has nothing more to do

详细配置示例​

数据分析Agent配置​

以下示例创建一个预装数据分析包的Agent和Environment：

创建数据分析Environment

curl -fsSL https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "data-analysis",
    "config": {
      "type": "cloud",
      "packages": {
        "pip": ["pandas", "numpy", "scikit-learn", "matplotlib"],
        "npm": ["express"]
      },
      "networking": {"type": "unrestricted"}
    }
  }'

创建数据分析Agent

curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Data Analysis Agent",
    "model": "claude-sonnet-4-6",
    "system": "You are an expert data analyst. Load data, perform analysis, generate visualizations, and provide actionable insights. Always save results to files.",
    "tools": [
      {
        "type": "agent_toolset_20260401"
      }
    ]
  }'

禁用特定工具​

若需要一个只能读写文件、不能执行Shell命令的只读分析Agent：

curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Read-Only Analyst",
    "model": "claude-sonnet-4-6",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "configs": [
          {"name": "bash", "enabled": false},
          {"name": "write", "enabled": false},
          {"name": "edit", "enabled": false}
        ]
      }
    ]
  }'

或者使用白名单方式，只启用特定工具：

{
  "type": "agent_toolset_20260401",
  "default_config": {"enabled": false},
  "configs": [
    {"name": "read", "enabled": true},
    {"name": "glob", "enabled": true},
    {"name": "grep", "enabled": true}
  ]
}

生产环境网络限制配置​

生产环境中建议使用limited网络模式，遵循最小权限原则：

curl -fsSL https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "production-env",
    "config": {
      "type": "cloud",
      "packages": {
        "pip": ["requests", "boto3"]
      },
      "networking": {
        "type": "limited",
        "allowed_hosts": ["https://api.example.com", "https://s3.amazonaws.com"],
        "allow_mcp_servers": true,
        "allow_package_managers": false
      }
    }
  }'

网络配置参数说明：

参数说明
type: unrestricted完全放开出站网络（有通用安全黑名单）
type: limited仅允许allowed_hosts中的域名
allowed_hosts允许访问的HTTPS域名列表
allow_mcp_servers是否允许访问配置的MCP Server端点（默认false）
allow_package_managers是否允许访问公共包注册表（默认false）

使用自定义工具​

Managed Agents支持自定义工具，扩展Claude的能力边界。自定义工具由应用侧执行，Claude通过结构化请求调用，结果以agent.tool_result事件返回：

# 创建带自定义工具的Agent
curl -fsSL https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Weather Agent",
    "model": "claude-sonnet-4-6",
    "tools": [
      {
        "type": "agent_toolset_20260401"
      },
      {
        "type": "custom",
        "name": "get_weather",
        "description": "Get current weather for a location. Use this when users ask about weather conditions in any city.",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name, e.g. Beijing, New York"
            }
          },
          "required": ["location"]
        }
      }
    ]
  }'

自定义工具调用时，应用侧需要监听agent.tool_use事件并发送agent.tool_result事件返回结果：

# Python伪代码：处理自定义工具调用
for event in stream_events(session_id):
    if event["type"] == "agent.tool_use" and event["name"] == "get_weather":
        location = event["input"]["location"]
        weather_data = call_weather_api(location)   # 应用侧执行
        
        # 将结果返回给智能体
        send_event(session_id, {
            "events": [{
                "type": "agent.tool_result",
                "tool_use_id": event["id"],
                "content": [{"type": "text", "text": str(weather_data)}]
            }]
        })

版本管理与Agent更新​

Agent支持版本化更新，每次更新自动生成新版本号：

# 更新Agent的系统提示（需传入当前version以防止并发冲突）
curl -fsSL -X PUT "https://api.anthropic.com/v1/agents/$AGENT_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d "{
    \"version\": $AGENT_VERSION,
    \"system\": \"You are a helpful coding assistant. Always write tests for your code.\"
  }"

# 查看版本历史
curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID/versions" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "Version \(.version): \(.updated_at)"'

# 归档Agent（不可再创建新Session引用，但已有Session继续运行）
curl -fsSL -X POST "https://api.anthropic.com/v1/agents/$AGENT_ID/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

支持的包管理器​

创建Environment时可以通过packages字段预安装依赖包，支持以下包管理器：

包管理器生态版本格式示例
apt系统包（apt-get）"ffmpeg"
cargoRust（cargo）"[email protected]"
gemRuby（gem）"rails:7.1.0"
goGo模块"golang.org/x/tools/cmd/goimports@latest"
npmNode.js（npm）"[email protected]"
pipPython（pip）"pandas==2.2.0"

多个包管理器按字母顺序执行（apt → cargo → gem → go → npm → pip），安装结果会被缓存，相同Environment的后续Session无需重复安装。

速率限制​

Managed Agents的API端点按组织维度进行速率限制：

端点类型速率限制
创建类（agents、sessions、environments等）每分钟60次
读取类（检索、列表、流式等）每分钟600次

组织级别的Spend Limit和基于使用层级的速率限制同样适用。

适用场景​

Managed Agents最适合以下类型的工作负载：

  • 长时运行任务：持续数分钟甚至数小时、涉及多次工具调用的复杂任务
  • 云端执行：需要安全隔离容器、预安装依赖包、受控网络访问的场景
  • 零基础设施搭建：不想自行构建agent loop、沙箱、工具执行层的团队
  • 有状态会话：需要持久化文件系统和跨会话对话历史的应用
  • 异步工作流：后台自动化任务，结果通过事件流异步消费

小结​

Claude Managed Agents代表了Anthropic对"平台级AI编排服务"的探索。通过将Brain（Claude+harness）、Hands（沙箱+工具）和Session（事件日志）三层彻底解耦，它解决了单体容器设计在容错性、安全性和可扩展性上的根本缺陷。对于希望快速构建生产级AI自动化系统的开发者而言，Managed Agents提供了一条低摩擦的路径：定义配置，启动会话，专注于业务逻辑——将基础设施交给Anthropic托管。

目前，Managed Agents仍处于Beta阶段，部分高级功能（Outcomes、Multi-agent编排、Memory）处于研究预览阶段，需要单独申请访问权限。随着功能的持续完善，它有望成为构建复杂AI自动化工作流的主流选择之一。