Claude Managed Agents 是 Anthropic 的托管代理框架，在撰写本文时处于测试阶段。它在 Anthropic 一侧运行代理循环、沙箱和会话日志，按每会话小时 $0.08 的速率计费（加上令牌费用），空闲时间免费。你发送事件并流式传输结果，而不是自己维护这一层。本文档化演练涵盖了该服务托管的内容、ant apply 基于文件的工作流的行为方式，以及何时 Agent SDK 仍然是更好的选择。
注意：Managed Agents 是本文撰写时的测试版服务。相应对待这里的所有内容。
Claude Managed Agents 为你托管的内容
简版：Anthropic 运行 agent 框架、计算沙箱和会话日志。你通过 HTTP 发送事件并将结果流回。就这样。你不需要管理容器生命周期、工具执行环境或临时失败的重试逻辑。
更具体地说，这是 Anthropic 这边的内容：
- agent 循环。Claude 决定何时调用工具、处理结果并迭代，无需你编写协调代码。
- 内置工具。Bash、文件操作、网页搜索，都可通过
agent_toolset_20260401工具类型访问。你不需要自己连接这些。 - 每会话沙箱。每个会话都有自己的隔离执行环境。没有跨会话泄漏。
- 持久会话日志。如果你的应用程序中断流，会话不会消失。你可以重新连接并追上进度。
- MCP 集成。自定义工具作为 MCP 服务器连接。Claude 触发工具；你的服务通过协议返回结果。无需打包到部署中。
- 提示缓存。在平台级别内置，一旦你的系统提示变长就很重要。
你这边保留的：agent 定义、你的 MCP 服务器实现，以及决定何时启动或停止会话的任何业务逻辑。这比管理完整框架的表面积小得多。
Hatchworks 清楚地说明了基础设施分割：推理可以在配置容器之前开始，即使每个工具调用都跨越服务边界，通常对冷启动 agent 也更快。
何时选择 Managed Agents、Agent SDK 或 Claude Code
我最常看到的混淆是人们将这三个视为可互换的。它们不是。
Claude Code 是一个终端工具。非常适合在本地运行任务的开发者。不是要嵌入产品中的东西。
[Agent SDK](/blog/claude-agent-sdk-guide-2026/) 在你自己的进程中、在你自己的基础设施上运行代理循环。直接文件系统访问、私有网络连接、对执行环境的完全控制。当你需要本地文件写入而不经过服务边界、已经付费的现有基础设施，或模型级别的多提供商灵活性时，选择 SDK（不过目前 SDK 要么就是 Claude）。
托管代理是托管的解决方案。你获得持久会话、沙盒计算和内置可观测性，无需自己构建。成本模型是按会话小时计费，而不仅仅按令牌计费，因此它奖励短而专注的会话，惩罚长时间空闲的会话。
以下是决策表：
| 情况 | 选择此项 |
|---|---|
| 新产品，想要快速发布，没有现有基础设施 | Managed Agents |
| 需要本地文件系统或专网访问 | Agent SDK |
| 你已在运行的现有代理基础设施 | Agent SDK |
| 在迁移到托管前在本地原型设计 | 先用 Agent SDK，再迁移到 Managed Agents |
| 在你自己的机器上的 CI/CD 管道 | Agent SDK |
| 需要持久会话而无需自己构建 | Managed Agents |
值得一提的一点是：正如 hidekazu-konishi.com 上 SDK 指南中所述，一条常见路径是用 SDK 在本地原型设计，一旦你想要不想自己运营的托管沙箱，就迁移到 Managed Agents。
如果你的特定挑战是围绕这个构建完整的代理产品，我们的代理工程工作可能会让你少走一些弯路。
创建一个代理并检查会话
这是一个有文档记录的演练，不是已验证的生产运行。我在描述官方文档中的程序；在你针对自己的密钥运行之前，把这里的任何代码都当作说明性的。
运行代理需要四个步骤。
- 创建代理定义。这是你描述代理能做什么的地方：它可以访问哪些内置工具、它可以调用哪些 MCP 服务器，以及它的系统提示是什么。
- 创建执行环境。平台为你的代理定义配置一个沙盒。
- 启动会话。你发送一个包含用户输入的启动事件。会话 ID 立即返回。
- 流式传输事件。工具调用、中间结果和最终响应都到达流上。你在应用中处理它们。
在七个官方 SDK（Python、TypeScript、Go、Java、C#、Ruby、PHP）中，该流程的形状是一致的，即使语法不同。agent_toolset_20260401 工具类型是在单一声明中解锁完整内置工具集的关键。你不需要单独列举 bash、文件操作和网络搜索。
会话运行后，你可以通过会话日志端点检查它。这是持久性优势的具体体现。断开流，重新连接，日志从你断开的地方重放。对于客户端可能断开连接的长期运行任务，这很重要。
使用 ant apply 和 claude-lock.json 管理资源
ant CLI 是与 SDK 本身分开的工具。通过 Homebrew 安装它。它提供一个基于文件的工作流程，用于在配置文件中声明你的代理资源（代理、环境、MCP 服务器注册），然后将它们应用到平台。
ant apply 文档描述了核心命令：
ant apply
在接触生产之前，运行干运行标志：
ant apply --dry-run
这预览了应用会做什么。官方文档中的重要警告：--dry-run 即使在应用时会被阻止的计划上也可能以 0 退出。不要将干净的 dry-run 作为完整应用成功的保证。先在暂存环境中验证实际应用。
claude-lock.json 文件是记录已部署资源当前状态的锁文件。把它想象成 package-lock.json，它固定资源版本并防止你声明的内容与平台运行的内容之间出现偏差。每次 ant apply 之后，锁文件会更新以反映新状态。提交它。在代码审查中将对其的更改视为有意义的。
一个容易让人困惑的序列化问题：部分应用。如果 ant apply 中途失败，某些资源会处于新状态而某些则不会。锁文件将反映部分更新。在再次运行 ant apply 之前，检查锁文件与实际部署的内容，必要时手动协调，然后重新运行。在未先检查的情况下对破坏的部分状态运行第二次应用，会使资源处于混乱的中间状态。
这与 Terraform 等在 CLI 中有单独计划步骤的工具不同。没有 ant plan。dry-run 是你用于预览的。相应地设计你的 CI。
在 CI 中审查更改并处理部分失败
对于多个开发者针对同一托管代理环境工作的团队，强烈建议从 CI 而不是本地机器应用更改。否则你会遇到锁文件的竞态条件。
这是我建议的工作流：
- PR 打开。CI 运行
ant apply --dry-run并将输出作为 PR 评论发布。 - 审查者检查差异，包括任何锁文件更改。
- 合并到主分支后，CI 针对暂存环境运行
ant apply。 - 仅在暂存应用成功且会话行为正确后才提升到生产环境。
序列化要求是主要的操作约束。你不能针对同一环境并行运行两个 ant apply 调用。如果你的 CI 系统可以快速排队多个合并，在管道级别强制执行锁（大多数 CI 平台都有为此设置的并发组设置）。
对于部分失败处理，检查清单如下：
- 在失败的应用后立即检查锁文件。记下哪些资源已更新，哪些资源未更新。
- 不要盲目重新运行
ant apply。先读错误。 - 如果部分状态可以安全保留以供调查，就保留它。如果资源处于破坏的中间状态，你可能需要在重新应用之前手动回滚。
- 一旦解决，再次运行
ant apply --dry-run后再进行完整应用，以确认计划看起来正确。
因为 --dry-run 可能在被阻止的计划上以 0 退出，即使 dry-run 看起来干净，也不要跳过审查步骤。
测试版限制、成本和部署检查清单
托管代理是一个测试版服务。对于任何生产关键的内容，这一指定很重要。功能可能会改变。定价可能会改变。测试版中的可用性保证与正式版不同。
费用。公布的费率是每会话小时 $0.08，仅在会话运行期间计费（空闲时间不计费），令牌费用按照标准模型费率另行收费。对于短期、任务聚焦的会话，这相对可预测。对于长时间运行且工具使用量大的会话，你需要主动监控会话时长。vibecodingacademy 指南将此置于上下文中：成本竞争力取决于你为构建等效的自管理基础设施而花费的工程时间，这是真实的，而且经常被低估。
测试版中的当前约束：
- 自定义工具通过 MCP 服务器路由，不在进程内函数中。如果你的自定义工具紧密耦合到你的应用程序运行时，你需要先将其提取到 MCP 服务器中。
- 会话可观测性通过会话日志端点进行。没有内置的仪表板等价物，就像你在 SDK 基础上自己构建的那样。
Ant apply部分失败语义需要手动协调。没有自动回滚。- 序列化应用意味着管道吞吐量受到应用持续时间的限制。
部署前检查清单：
- Agent 定义已审查且系统提示已最终确定
- MCP 服务器已注册并独立测试，然后再连接到 agent
claude-lock.json已提交并作为已审查的工件处理Ant apply --dry-run输出在任何生产应用之前由第二个人审查- 会话持续时间监控已就位（注意是否出现异常长的会话）
- 为你的团队记录了部分失败恢复程序
- 在生产提升之前验证了暂存环境
- 在账户级别配置了预算提醒，因为测试版定价可能会变化
关于构建与购买问题的最后一点。Agent SDK 确实给你更多控制权。但控制权意味着所有权。正如 ksred 关于 SDK 所指出的，执行大量工作的 agent 会话可能会快速变得昂贵，失败恢复完全由你在 SDK 中设计。托管 Agent 用一些控制权换取了持久会话和你不需要操作的基础设施。都没有问题。选择取决于你的团队实际上能维护什么。
FAQ
托管 Agent 是否适用于任何 Claude 模型，还是仅限于特定版本？
在撰写本文时，官方文档中未列出托管 Agent 内的具体模型限制。鉴于测试版状态，模型可用性可能会发生变化。在为生产 agent 定义承诺特定模型版本之前，请直接检查概览页面。
我能否在 SDK 中本地运行相同的 agent 定义进行测试，然后再部署到托管 Agent？
不能直接运行。SDK 在你自己的进程中针对你的本地环境运行循环；托管 Agent 在 Anthropic 的沙箱中运行。你可以用 SDK 原型化 agent 行为，但执行环境的差异足够大，你应该在提升到生产之前在暂存环境中测试实际的托管 Agent 部署。
托管 Agent 如何处理需要凭据的 MCP 服务器的身份验证？
官方文档将自定义工具描述为通过 MCP 服务器连接，Claude 触发工具，你的服务返回结果。这些 MCP 服务器的凭据处理是你在服务器级别的责任。根据当前文档，托管 Agent 不会代表你在 MCP 调用中注入凭据。
在托管 Agent 中是否有办法限制每个会话的支出，就像 SDK 的 max_budget_usd 参数一样？
SDK 上 query() 的 max_budget_usd 参数是一个 SDK 级别的控制，不能直接转换为托管 Agent REST API。托管 Agent 内的预算控制在当前测试版中的粒度没有相同的文档记录。账户级别的支出提醒现在是最安全的备选方案。
如果区域或沙箱发生故障，正在运行的会话会发生什么？
持久会话日志是托管 Agent 的核心设计特性，但当前测试版文档中未详细说明会话跨基础设施故障的恢复规范。鉴于测试版的指定，请将耐久性保证视为尽力而为，直到 Anthropic 为该服务发布 SLA。
坦诚的总结：托管 Agent 是一个真正有用的服务，消除了大量基础设施工作。一旦你理解了 dry-run 注意事项和序列化要求，ant apply 工作流就很直接。但它是测试版，部分失败语义需要谨慎，如果你需要本地文件系统访问或已经有你满意的 agent 基础设施，它就不是正确的答案。从决策表开始，根据你的团队实际想要拥有的东西进行选择，并像对待任何其他状态文件一样认真对待锁文件。