WaveSpeedAI
← 博客

Claude Managed Agents 快速入门指南 2026

Claude Managed Agents 快速入门指南：beta 请求头设置、首次会话、工具调用和流式事件——附关键代码模式与成本节点说明。

By Dora 2 min read
Claude Managed Agents 快速入门指南 2026

第一次尝试运行 Managed Agents 会话时，我在第一个 curl 请求上就收到了 400 错误。不是在创建 agent 时，不是在环境配置时，而是在流式端点上。我从创建请求中复制粘贴了请求头 anthropic-beta: managed-agents-2026-04-01，但流式 API 直接拒绝了。原来当时文档中引用的是另一个 beta 请求头。就这样白白浪费了四十分钟。

如果你今天想从头到尾跑通第一个 Managed Agents 会话，这就是我实际走过的路。我是 Dora！先说 beta 请求头，因为那是失败最集中的地方。然后依次是 agent、环境、会话、流。最后还有一个费用检查点，因为调试期间会话运行时间一直在计费。

开始之前

你需要一个具备 Managed Agents 访问权限的 Anthropic API 密钥。目前没有候补名单——任何现有密钥在公测阶段均可使用。

beta 请求头是必须的。 每个 Managed Agents 端点都需要 anthropic-beta: managed-agents-2026-04-01。根据 Anthropic 的 Managed Agents 概述，SDK 会自动设置这个头。如果你使用原始 curl，则需要在每个请求中手动添加。这是我在社区反馈中见过的最常见的 400 错误原因。

如果你使用官方 SDK（Python 用 anthropic，TypeScript 用 @anthropic-ai/sdk），请确认你的版本包含 beta agent 支持。旧版本不会有 client.beta.agents 或 client.beta.sessions。

模型选择很重要。 Opus 4.7 在长周期 agent 推理上更智能。Sonnet 4.6 每个 token 更便宜更快。快速入门时，Sonnet 4.6 已经足够。如果你的实际工作负载涉及调试、规划或长工具链，Opus 4.7 物有所值。

第一步 — 定义你的 Agent

在 Managed Agents 中，agent 是一个配置对象，而不是一个进程。你只需定义一次名称、模型、系统提示和工具访问权限，然后就可以在多个会话中复用。

来自官方快速入门的最简可用定义：

python

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-4-7",
    system="You are a helpful coding agent.",
    tools=[{"type": "agent_toolset_20260401"}],
)

agent_toolset_20260401 工具类型解锁了完整的内置工具集——bash、文件读写、网络搜索、网页抓取、代码执行。之后可以缩小范围。第一次运行时保持宽泛，这样你能看到 agent 实际选择使用什么工具。

保存 agent.id。每个会话都需要引用它。

第二步 — 创建环境

环境定义了沙箱容器。大多数首次运行时：

python

env = client.beta.environments.create(
    name="quickstart-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

保存 env.id。如果你的 agent 只操作自己的文件系统，"networking": {"type": "limited"} 更安全，在 SRE 事件响应手册中有详细说明。

第三步 — 启动会话

会话将 agent 与环境绑定在一起。创建会话不会启动工作。 它只是完成资源预置。发送用户事件后，工作才真正开始。

python

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=env.id,
    title="Quickstart session",
)

这种模式——创建，然后通过事件驱动——正是会话参考文档中状态机模型的意义所在。会话是持久的，你可以之后继续发送事件，文件系统在多轮对话之间也会保留。

第四步 — 流式接收事件

打开流，发送用户消息，读取事件直到 session.status_idle：

python

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 first 20 Fibonacci numbers, save to fib.txt"}],
        }],
    )
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[tool: {event.name}]")
            case "session.status_idle":
                break

事件名称遵循 {域}.{动作} 的格式。完整的事件模式在事件与流式文档中有说明。processed_at 字段很重要：如果它是 null，说明事件已入队但尚未执行。我第一次运行时忽略了这一点，以为工具是静默失败的。

费用检查点

Managed Agents 计费包含两部分：标准 token 费率加上每会话小时 $0.08 的活跃运行时费用。根据官方定价页面，运行时按毫秒计费——但仅在状态为 running 时计费。空闲时间和已终止的会话不计费。

实际影响：

  • 调试时忘记关闭的会话：仍在计费（如果它处于运行状态）。
  • 网络搜索：每 1,000 次调用 $10，单独计费。研究型 agent 很快就会触达这个费用。
  • 每天结束工作前，在 Console 追踪中检查活跃会话。请自行确认当前的 UI 路径——Console 的界面布局一直在迭代更新。

常见错误

缺少或错误的 beta 请求头。 400 错误，通常附带关于不支持端点的提示信息。修复方法：确认每个直接 HTTP 调用都带有 managed-agents-2026-04-01。如果使用 SDK 仍然遇到此问题，请升级 SDK。

速率限制。 创建端点上限为每分钟 60 次请求；读取端点为每分钟 600 次。组织级别的限制也适用于此之上。收到 429 时应采用带抖动的退避策略，而不是立即重试。

静默工具循环。 Agent 一直在调用工具但没有产生最终消息。检查会话追踪——通常是某个从未收到响应的 requires_action 未被处理。

常见问题

Q1：如何在 Managed Agents 中启用多 agent 协调？

多 agent（连同记忆和结果功能）目前仍是研究预览特性。你需要通过 Claude Console 单独申请访问权限。协调模式——编排者将任务委派给可调用的 agent——在多 agent 会话文档中有说明，但在你的组织开启预览标志之前无法使用。

Q2：我能查看 agent 在会话中调用了哪些工具吗？

可以。使用 client.beta.sessions.events.list(session.id) 进行程序化访问，或使用 Console 的追踪视图查看带有每个事件 token 数量和时间戳的时间线。

Q3：官方 Managed Agents 手册在哪里？

教程位于 Claude Cookbook 网站——iterate-fix-failing-tests notebook 是最值得首先阅读的。operate-in-production notebook 在你完成 hello-world 阶段后，涵盖了 vaults、MCP 和 webhooks 的使用。

Q4：有没有办法在不产生会话运行时费用的情况下进行测试？

目前没有专用的 Managed Agents 免费套餐。标准 API 免费额度可以覆盖。开发期间请保持会话简短，停止工作时及时关闭会话。空闲会话不计费，但运行中的会话会计费——“运行中”包括静默循环的 agent。

Q5：长时间运行的 Managed Agents 任务最适合用哪个模型？

取决于”长时间运行”的具体含义。对于需要大量工具调用的多小时推理任务，选 Opus 4.7。对于高并发、较简单的循环任务，带有提示缓存的 Sonnet 4.6 可以大幅降低成本。我还在测试 Opus 4.7 在超过 2 小时会话中的表现，那是我数据的边界所在。后续会有更多分享。

仍在验证超过两小时后压缩功能的行为。自己跑一遍——比我告诉你的更有说服力。

往期文章：

分享