Claude Managed Agents 完整部署指南：三步从零到生产级 AI Agent

Claude Managed Agents 是 Anthropic 于 2026 年 4 月 8 日正式发布的托管式 Agent 运行时，通过提供沙箱容器、会话持久化、多 Agent 编排等基础设施，开发者无需自建运行环境即可将 AI Agent 推向生产。区别于普通 Claude API 的单次请求模式，Managed Agents 支持跨轮次持续执行任务，已在 Claude API beta 阶段向所有付费开发者开放。

图1

Claude Managed Agents 是什么：四个核心概念

Claude Managed Agents 的架构围绕四个基础概念构建，理解它们是部署的前提：

概念 含义 类比
Agent 定义 Agent 行为的蓝图，包含模型、系统提示、工具权限 Docker 镜像
Environment Agent 运行的沙箱容器，隔离文件系统与网络 Docker 容器
Session 一次具体的任务执行实例，Agent + Environment 的组合 运行中的进程
Event 用户消息或 Agent 工具调用的最小通信单元 消息队列条目

与普通 Claude API 的核心区别：普通 Messages API 是无状态的单次请求；Managed Agents 是有状态的长期执行，支持数小时连续运行、自动工具调用、多 Agent 并行编排。

Claude Managed Agents vs 主流 Agent 框架对比

在选型前，了解 Managed Agents 与其他方案的边界非常重要：

维度 Claude Managed Agents LangGraph OpenAI Agents SDK 自建框架
基础设施 Anthropic 全托管 自托管 自托管 自托管
模型支持 仅 Claude 系列 多模型 仅 OpenAI 系列 任意模型
沙箱隔离 内置云沙箱 需自行配置 需自行配置 需自行配置
多 Agent 编排 内置（beta 阶段） 成熟 成熟 完全自定义
上手成本 低（3 步部署） 中 中 高
厂商绑定 强（仅 Claude） 弱 强（仅 OpenAI） 无
适用场景 快速生产化、企业内部工具 复杂状态机、多模型 OpenAI 生态 完全定制需求

选型建议：如果你的团队已使用 Claude 且需要快速上线 Agent，Managed Agents 是工程成本最低的路径。根据 Linas Beliūnas 在 2026 年 4 月的分析，传统自建 Agent 运行时通常需要 4–8 名高级工程师耗费 3–6 个月；Managed Agents 将这部分工作封装为 API 调用。

三步完整部署：从零到第一个 Managed Agent

前置准备

# 安装 Anthropic Python SDK（需 0.52.0+）
pip install anthropic

# 配置 API Key
export ANTHROPIC_API_KEY="your-api-key-here"

# 可选：安装 CLI 工具
brew install anthropics/tap/ant

第一步：创建 Agent 定义

Agent 是行为蓝图，定义模型、系统提示和可用工具。agent_toolset_20260401 工具类型开箱包含 Bash 执行、文件操作、网页搜索等完整工具集：

from anthropic import Anthropic

client = Anthropic()

# 创建 Agent 定义
agent = client.beta.agents.create(
    name="coding-assistant",
    model="claude-sonnet-4-6",
    system="你是一名专业的代码审查助手，负责分析代码质量、安全漏洞和性能问题。",
    tools=[{"type": "agent_toolset_20260401"}],
)

print(f"Agent ID: {agent.id}")
# 保存 agent.id，后续 Session 创建需引用

第二步：创建执行环境

Environment 是隔离的沙箱容器，决定 Agent 的网络访问权限和运行环境：

# 创建云沙箱环境（unrestricted = 允许外网访问）
environment = client.beta.environments.create(
    name="prod-env",
    config={
        "type": "cloud",
        "networking": {"type": "unrestricted"}
    },
)

print(f"Environment ID: {environment.id}")

网络类型说明：

  • unrestricted：允许访问所有外部网络（适合需要联网搜索的 Agent）
  • sandboxed：仅限内部通信（适合处理敏感数据的 Agent）

第三步：启动 Session 并流式执行

Session 是一次具体的任务执行实例。通过流式 API 实时获取 Agent 的执行过程：

# 创建 Session
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="代码审查任务 - 2026-05-27",
)

print(f"Session ID: {session.id}")

# 发送任务并流式接收结果
with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{
            "type": "user_message",
            "content": "克隆 https://github.com/example/repo，运行测试套件，报告代码质量问题。"
        }]
    )

    for event in stream:
        if event.type == "text_delta":
            print(event.delta, end="", flush=True)
        elif event.type == "tool_use":
            print(f"\n[工具调用] {event.name}: {event.input}")

使用 curl 直接调用 API

不使用 Python SDK 时，可通过 curl 直接操作，所有请求需携带 beta 头：

# 所有请求必须携带此 beta header
BETA_HEADER="anthropic-beta: managed-agents-2026-04-01"

# 创建 Session
curl -X POST https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "$BETA_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "environment_id": "env_xyz789",
    "title": "My first session"
  }'

# 向 Session 发送消息
SESSION_ID="session_xxx"
curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "$BETA_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{"type": "user_message", "content": "分析这段代码的安全风险"}]
  }'

多 Agent 编排：并行执行任务

Managed Agents 支持多 Agent 并行运行（目前在 research preview 阶段，需申请访问权限）。常见编排模式：

图2

import asyncio

async def run_parallel_agents():
    """并行启动三个专项审查 Agent"""

    tasks = [
        {
            "title": "安全漏洞审查",
            "prompt": "检查认证逻辑、SQL 注入风险、XSS 漏洞"
        },
        {
            "title": "性能瓶颈分析",
            "prompt": "分析数据库查询效率、内存使用、API 响应时间"
        },
        {
            "title": "代码规范检查",
            "prompt": "验证命名规范、注释覆盖率、测试覆盖率"
        }
    ]

    # 并行创建三个 Session
    sessions = await asyncio.gather(*[
        asyncio.to_thread(
            client.beta.sessions.create,
            agent=agent.id,
            environment_id=environment.id,
            title=task["title"]
        )
        for task in tasks
    ])

    return sessions

sessions = asyncio.run(run_parallel_agents())
print(f"已启动 {len(sessions)} 个并行 Agent")

费用结构：两个计费维度

Claude Managed Agents 采用双维度计费，区别于普通 API 的纯 Token 计费：

计费项 单价 说明
Token 消耗 按模型标准费率 与普通 Messages API 相同
Session 运行时 0.08 美元/session-hour 按实际运行时长计费，毫秒精度
网页搜索 10 美元/1000 次 Agent 触发搜索时单独计费

费用估算示例：一个运行 2 小时的代码审查 Agent，使用 Claude Sonnet，消耗约 50 万 Token（输入 40 万 + 输出 10 万）：

  • Token 费用：约 1.5 美元
  • 运行时费用：0.08 × 2 = 0.16 美元
  • 总计约 1.66 美元/次任务

根据 Anthropic 官方文档（2026 年 5 月），Managed Agents 的 Rate Limit 为：创建类端点 300 次/分钟，读取类端点 600 次/分钟。

三大内置工具集

使用 agent_toolset_20260401 时，Agent 自动获得以下工具权限：

内置工具一览：
├── bash          # 在沙箱中执行 Shell 命令
├── file_read     # 读取文件内容
├── file_write    # 写入文件（含代码生成）
├── web_search    # 联网搜索（按次计费）
├── computer      # 截图与 GUI 操作（实验性）
└── code_execute  # 独立代码执行环境

如需细粒度权限控制，可按工具单独声明：

# 仅开放 bash 和文件操作，不开放网页搜索
agent = client.beta.agents.create(
    name="restricted-agent",
    model="claude-sonnet-4-6",
    system="你只能操作本地文件，不能联网。",
    tools=[
        {"type": "bash_20260401"},
        {"type": "file_read_20260401"},
        {"type": "file_write_20260401"},
    ],
)

国内开发者接入方案

由于 Anthropic API 在国内网络环境下访问受限，以下是两种可用方案：

方案一：通过兼容 API 中转

国内部分云服务商提供兼容 Anthropic 标准接口的推理服务，例如七牛云 AI 推理服务支持 Anthropic SDK 格式，开发者可修改 base_url 接入，现有代码无需大改：

from anthropic import Anthropic

# 通过兼容接口接入（替换 base_url）
client = Anthropic(
    api_key="your-qiniu-api-key",
    base_url="https://api.qiniu.com/v1"  # 示例，以实际文档为准
)

方案二：自建代理 + 官方 API

# 通过代理服务器访问 Anthropic API
export ANTHROPIC_BASE_URL="https://your-proxy.example.com"
export ANTHROPIC_API_KEY="sk-ant-..."

python your_agent_script.py

注意：Managed Agents 目前仅通过 Claude API 官方端点提供，部分中转服务尚不支持 Sessions 类端点，使用前需确认服务商是否已支持。

常见问题

Q：Managed Agents 和 Claude Code 的 Subagent 有什么关系？
Claude Code 内置的 Subagent（如 Explore、Plan、Bash 子代理）是基于 Claude Code CLI 本地调度的轻量级协作模式；Managed Agents 是 Anthropic 提供的云端 API 级 Agent 运行时，面向开发者构建生产应用，两者定位不同，不互相替代。

Q：beta header managed-agents-2026-04-01 何时会移除？
Anthropic 官方尚未公布正式 GA 时间表。Python SDK 会自动设置此 header；直接调用 HTTP API 时需手动添加。建议定期关注 platform.claude.com/docs 的更新日志。

Q：Session 最长能运行多久？
目前官方文档未明确限制单个 Session 的最大运行时长，账单按实际 session-hour 计费。实践中，建议将长任务拆分为多个短 Session 以便错误隔离和成本控制。

Q：Managed Agents 支持自托管沙箱吗？
支持。通过 config.type: self_hosted 配置项，可将 Environment 指向团队自有的沙箱基础设施，适合有数据合规要求的企业场景。

Q：如何查看 Agent 的实时执行状态？
使用 claude agents 命令（Claude Code CLI v2.1.139+）或通过 client.beta.sessions.retrieve(session_id) 轮询 Session 状态，字段 status 值为 running、paused（等待用户输入）、completed。

图3

延伸资源

本文内容基于 2026 年 5 月数据，Managed Agents 目前处于 beta 阶段，API 细节可能随版本迭代调整，建议定期查阅官方文档获取最新信息。

把本文的三步部署流程（创建 Agent → 创建 Environment → 启动 Session）加入团队 Runbook，可将新项目接入 Managed Agents 的环境配置时间压缩到 30 分钟以内。

# 人工智能
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

当Agent输出Markdown表格：从渲染崩溃看宿主与模型的权责边界

avatar 龙虾开发者社区
cover

Agent 自动执行 Shell 命令：Docker 沙箱真能防住恶意 rm -rf 吗？

avatar 龙虾开发者社区
cover

Agent 工具调用鉴权失败？MCP 最小权限与重试策略实战解析

avatar 龙虾开发者社区