Anthropic Claude Managed Agents 公测上线：5 分钟跑通全托管 AI 代理

2026 年 4 月 8 日，Anthropic 在 Claude Platform 正式开放了 Claude Managed Agents 的 Public Beta。这套全新的全托管代理框架（Managed Agent Harness）把"Agent 循环 + 工具执行 + 沙箱容器 + 状态持久化"打包成一组 REST API，开发者不再需要自己搭建 agent loop、工具调用层或运行时，只要调用 /v1/agents、/v1/environments、/v1/sessions 三个端点，就能让 Claude 以自主代理的方式在安全沙箱中完成长耗时任务。

本次公测同时发布了 managed-agents-2026-04-01 Beta 请求头、新的 agent_toolset_20260401 工具集，以及基于 Server-Sent Events 的事件流协议。本文结合官方文档与最新 Release Notes，系统梳理 Claude Managed Agents 的核心概念、API 接入方式、事件模型与计费规则，并给出一份可直接复用的 Python / curl 快速上手代码，帮助你在 5 分钟内跑通一次真实的 Managed Agent 会话。

Claude Managed Agents 是什么：托管代理的核心定位

在理解 Managed Agents 之前，需要先厘清它与传统 Messages API 的关系。Anthropic 现在提供两条构建路径：Messages API 负责直接调用模型，适合需要完全控制 agent loop 的场景；Managed Agents 则提供预构建、可配置的代理运行环境，适合长耗时、异步化、需要沙箱隔离的工作负载。

与 Messages API 的定位差异

🎯 选型建议：如果你正在构建一个需要"AI 自主写代码、跑脚本、浏览网页再汇总结果"的后台任务，Managed Agents 会比手工串联 Messages API + 自建沙箱更省事。建议在 API易 apiyi.com 平台上做一次两者的对比测试，快速判断自己的业务更适合哪种形态。

四大核心概念

Claude Managed Agents 围绕四个基础概念构建：

• Agent（代理）：模型、系统提示词、工具、MCP Servers 与 Skills 的静态定义，创建一次后可被多个会话复用，支持版本化。
• Environment（环境）：云端容器模板，描述预装软件包、网络访问策略以及挂载文件。
• Session（会话）：指定 Agent + Environment 的具体运行实例，负责执行一次性或长耗时任务。
• Events（事件）：Session 与客户端之间交换的消息，包括用户消息、工具调用、工具结果、状态变更等。

Managed Agents 核心能力盘点：沙箱、工具集与 SSE 流

理解四大概念之后，我们来逐个看它们在 Beta 版本中提供了哪些实际能力。

安全沙箱与容器配置

每个 Session 运行在一个隔离的云端容器中，具备以下特性：

• 预装运行时：Python、Node.js、Go 等主流语言环境开箱即用。
• 网络策略：支持 unrestricted（无限制）和更严格的受限网络模式，避免沙箱成为数据外传通道。
• 文件系统：容器内的文件在会话生命周期中持久化，Agent 可以跨轮次读写。
• 可挂载资源：可在 Environment 中预先挂载数据文件或脚本。

内置工具集 agent_toolset_20260401

公测版本提供了一个统一的工具集标识 agent_toolset_20260401，一次性启用所有预构建工具：

🎯 开发者提示：agent_toolset_20260401 是一个"组合开关"，方便快速原型验证。生产环境建议根据最小权限原则按需启用子集。如果想在 API易 apiyi.com 对比不同工具子集的 token 成本，可直接切换 base_url 后复用同一段代码。

Server-Sent Events 流式事件模型

与传统 Messages API 的"一次请求 → 一次响应"不同，Managed Agents 采用事件驱动 + SSE 推送模型。关键事件类型如下：

快速上手 Claude Managed Agents：API 接入完整流程

下面用最短的代码演示一次完整的 Managed Agent 会话。核心步骤包括：创建 Agent → 创建 Environment → 创建 Session → 发送消息并订阅 SSE 流。

前置条件

1. 一个 Claude API Key（或 API易 apiyi.com 的兼容 Key）。
2. 每次请求携带 anthropic-beta: managed-agents-2026-04-01 头；官方 SDK 会自动附加，手工 curl 需显式声明。
3. Python SDK 升级到最新版本：pip install -U anthropic。

极简 Python 示例

from anthropic import Anthropic

client = Anthropic(
    # 使用 API易中转可复用现有代码，无需改动 SDK 用法
    base_url="https://api.apiyi.com",
    api_key="YOUR_API_KEY",
)

# 1. 创建 Agent
agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-sonnet-4-6",
    system="You are a helpful coding assistant.",
    tools=[{"type": "agent_toolset_20260401"}],
)

# 2. 创建 Environment（无限制网络）
env = client.beta.environments.create(
    name="quickstart-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

# 3. 创建 Session
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=env.id,
    title="Quickstart session",
)

# 4. 打开 SSE 流并发送用户消息
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": "Generate the first 20 Fibonacci numbers to fibonacci.txt",
            }],
        }],
    )
    for event in stream:
        if event.type == "agent.message":
            for block in event.content:
                print(block.text, end="")
        elif event.type == "agent.tool_use":
            print(f"\n[Using tool: {event.name}]")
        elif event.type == "session.status_idle":
            print("\n\nAgent finished.")
            break

# 携带 Beta 头创建 Agent
curl -sS https://api.apiyi.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.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }'

# 创建 Environment、Session 的请求结构类似，见官方 quickstart 文档
# 订阅 SSE 流时使用：
# curl -N -H "Accept: text/event-stream" \
#   https://api.apiyi.com/v1/sessions/$SESSION_ID/stream

🎯 代码复用建议：上面的 base_url 指向 API易 apiyi.com，即可在中国大陆以低延迟访问 Managed Agents 公测接口。官方 SDK 的所有参数、Beta 头、事件类型完全兼容，无需二次封装。

五步流程图解

[Client] ──1. create agent──────────▶ [API]
[Client] ──2. create environment────▶ [API]
[Client] ──3. create session────────▶ [API]
[Client] ──4. open SSE stream───────▶ [API]
[Client] ──5. send user.message─────▶ [API]
         ◀─ agent.message / tool_use / tool_result / status_idle ──

整个过程的核心是：事件先行，流式接收。官方建议先打开 SSE 流再发送 user 事件，这样不会错过任何中间状态。

Claude Managed Agents 关键规则：限流、计费与品牌合规

公测版本已经给出了明确的生产参数。以下是开发者最关心的三项规则。

限流规则

限流以**组织（Organization）**为单位统计，与账号下的 Tier 相互独立：

除此之外，组织级的消费额度和 Tier 速率上限依然生效。高并发的批量代理任务需要提前做限流规划，或者通过 API易 apiyi.com 分摊到多账号资源池。

计费模型

Managed Agents 的计费由两部分组成：

1. Session 运行时费用：$0.08 / 会话小时。
2. 模型 Token 费用：按所选 Claude 模型（如 Sonnet 4.6 / Opus 4.6）的标准单价计费。

没有额外订阅、没有固定基础设施成本。这意味着空闲但未关闭的 Session 仍会按小时计费，务必在任务结束后调用结束接口。

品牌合规要点

Anthropic 对合作伙伴使用 Claude 品牌提出了明确约束：

• ✅ 允许：Claude Agent、Claude（菜单语境内）、{YourAgentName} Powered by Claude。
• ❌ 禁止：Claude Code、Claude Code Agent、Claude Cowork 等名称；禁止模仿 Claude Code 的 ASCII art 或视觉元素。

🎯 合规建议：面向企业交付的托管代理产品，建议保持自身品牌主体地位，仅在技术说明中以"Powered by Claude"的方式致谢。若需要正式的品牌授权或模板化 UI，可通过 API易 apiyi.com 获取合作渠道的对接指引。

Claude Managed Agents 典型应用场景：哪些业务最值得迁移

公测版本虽然仍有部分功能（outcomes、multiagent、memory）处于 Research Preview，但对于以下四类场景已经可以立即落地。

适合立即迁移的四类工作负载

暂不建议使用的场景

• 极低延迟的实时对话：Session 启动和 SSE 开销对百毫秒级 UI 不友好。
• 强合规的本地化部署：Managed Agents 是云服务，不支持 on-prem。
• 需要完全自定义 agent loop 的研究型项目：依然建议走 Messages API 自建循环。

🎯 迁移路径建议：把现有"Messages API + 自建工具调度"的代理业务先用 Managed Agents 做一个对照实现，用同一份 Prompt 跑两版，比较 token 成本与完成率。通过 API易 apiyi.com 可以用同一个 Key 同时访问两种接口，避免并行评测时切换密钥。

常见问题 FAQ：Managed Agents 上手避坑

Q1：managed-agents-2026-04-01 是否需要手工附加？

使用官方 SDK（Python / TypeScript / Go / Java / C# / Ruby / PHP）时无需手动附加，SDK 会在 Beta 路径下自动注入。只有在使用原生 curl 或自建 HTTP 客户端时，才需要显式加上 anthropic-beta: managed-agents-2026-04-01。建议通过 API易 apiyi.com 中转时依然按标准路径请求，兼容性最佳。

Q2：SSE 流断开后会话会丢失吗？

不会。Session 的事件历史在服务端持久化，断线后重连 /v1/sessions/{id}/stream 端点即可继续接收后续事件，API 会从断点缓冲区中补推。这一点与 Messages API 的"一次请求一次响应"完全不同。

Q3：如何中断正在运行的 Agent？

Managed Agents 支持 mid-execution steering：向同一个 Session 的 /events 端点再发送一条 user.message，即可打断当前工具调用循环并改变方向。也可以通过专门的中断端点强制终止会话。

Q4：Session 费用会在什么情况下产生？

只要 Session 处于"可运行"状态就会按 $0.08/小时计费，即使 Agent 处于 status_idle。建议任务完成后显式关闭 Session，避免空跑费用。结合 API易 apiyi.com 的账单明细面板可以快速发现异常空闲会话。

Q5：Managed Agents 支持哪些 Claude 模型？

公测当前支持 Claude Sonnet 4.6、Claude Opus 4.6、Claude Haiku 4.5 三款主力模型。长上下文（1M token）在 Opus 4.6 / Sonnet 4.6 上默认可用，不需要额外 Beta 头。

Q6：能否把现有 Agent Skills / MCP Server 搬过来？

可以。Agent 定义中可直接声明 MCP Servers 列表和 Skills 引用，Managed Agents 复用了 2025 年 10 月发布的 Agent Skills Beta 协议，已有的技能包无需改造即可接入。

总结：Managed Agents 带来的开发范式跃迁

Claude Managed Agents 公测上线标志着 Anthropic 正式把"Agent 基础设施"纳入官方产品线。对于开发者来说，这次更新的价值不在于某个单点功能，而在于一次性消除了自建 Agent 系统的五大痛点：循环实现、工具执行、沙箱隔离、状态持久化、事件流协议。只需附加 managed-agents-2026-04-01 Beta 请求头并调用三个端点，就能把 Claude 变成真正的"自主可执行代理"。

结合最新的 Claude Sonnet 4.6 / Opus 4.6 模型、1M token 上下文、Agent Skills 与自动缓存，Managed Agents 让长耗时、异步、多工具的后台代理业务首次具备了企业级可复制的落地路径。下一步，建议先在低风险场景（如自动化报告、代码脚手架）中试点，再逐步迁移关键业务。

🎯 行动建议：准备开始迁移的团队，推荐把 base_url 指向 API易 apiyi.com，既能复用官方 SDK 代码，又能获得稳定的国内访问速率，同时支持 Messages API 与 Managed Agents 双轨并行评测，为选型决策留足数据。

— APIYI Team（API易 apiyi.com 技术团队）