把 Claude Managed Agents 讲明白

Claude Managed Agents：理解 Agent、Environment 和 Session 的工作原理

Claude Managed Agents 是 Anthropic 推出的一项托管服务，旨在简化开发人员创建和部署智能代理（Agent）的过程。本文将详细解析 Managed Agents 的核心概念及其应用场景。

一、Managed Agents 简介

Claude Managed Agents 是一个 Beta 版本的服务，它提供了一种全新的方式来管理和运行 Agent，而不是依赖于传统的 Messages API 或 Claude Agent SDK。具体而言：

• Messages API：直接与模型进行通信的基础层。
• Claude Agent SDK：开源的 harness，允许在本地机器或服务器上执行 Agent 循环。
• Claude Managed Agents：托管环境和沙箱容器，提供完整的运行时支持。

Managed Agents 适合那些希望将 Agent 集成到产品中的开发团队，并且不想自己搭建复杂的基础设施。对于只编写插件、CLI 工具或一次性脚本的人来说，使用 Agent SDK 就足够了。

二、它在解决什么问题

构建一个功能完备的智能代理涉及多个组件和技术挑战。Managed Agents 消除了这些复杂性：

1. Agent 循环：解析并执行模型生成的动作，并将结果反馈给模型。
2. 沙箱环境：确保模型的行为被限制在一个安全且隔离的环境中，防止潜在的安全风险。
3. 工具集：提供一系列预定义的工具供 Agent 使用，如 bash、文件操作和网络请求等。
4. 会话状态管理：持久化存储用户的对话历史和其他关键数据点。
5. 事件流处理：实时显示 Agent 的当前状态及进展，并支持用户与 Agent 之间的交互。
6. 优化策略：如缓存提示、压缩上下文和选择工具等，以提高性能和资源利用率。

这些组件需要大量的开发工作。而使用 Managed Agents，则可以将这些繁琐的工作交给 Anthropic 处理，从而使开发者能够更快地专注于实现业务逻辑。

三、技术架构详解

Managed Agents 的核心组成部分包括 Agent、Environment、Session 和事件流（Events）：

• Agent：一个可复用的模型实例，包含系统提示（system prompt）、可用工具集合和 MCP 服务器等。
• Environment：定义容器模板及其网络策略与预装包。
• Session：一次具体的任务执行实例，在特定 Agent 和 Environment 中运行。
• Events：用户与 Session 之间交换的消息流。

这四个概念之间的关系可以通过以下流程图来理解：

启动一个 Session

启动一个新的 Session 涉及到发送请求和订阅事件流两个步骤。具体过程如下：

1. 发送创建 Session 请求 (POST /v1/sessions)
2. 订阅 SSE 事件流 (GET /sessions/{id}/stream)
3. 发送用户消息 (POST /sessions/{id}/events)

每个步骤的具体内容和流程可以进一步细分为：

• 定义 Agent：通过 API 创建一个具有特定配置的 Agent 实例。
• 定义 Environment：创建一个新的容器模板，指定其网络策略和其他配置项。
• 启动 Session：将上述两个组件组合在一起以运行一次具体的任务。

关键特性

1. 双通道通信模式：用户消息通过 HTTP 请求发送；实时状态更新则通过 Server-Sent Events（SSE）订阅。
2. 持久化机制：Session 的状态和服务端的事件流被持久化存储，即使断开连接也不会丢失数据。
3. 中间干预能力：允许在 Agent 执行过程中插入新的用户指令以调整其行为路径。

这些特性极大地提高了开发效率，并减少了许多常见的技术障碍和复杂性问题。

四、具体应用示例

在官方文档中提供了一个简短的 Python 示例，展示了如何使用 Managed Agents 来创建一个简单的编码助手。以下是该示例的核心代码：

from anthropic import Anthropic

# 初始化客户端
client = Anthropic()

# 创建 Agent 和 Environment
agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-4-7",
    system="You are a helpful coding assistant.",
    tools=[{"type": "agent_toolset_20260401"}],
)
environment = client.beta.environments.create(
    name="quickstart-env",
    config={
        "type": "cloud",
        "networking": {"type": "unrestricted"},
    },
)

# 启动 Session
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Quickstart session",
)

# 发送用户消息并开启事件流订阅
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": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt.",
            }],
        }],
    )

    for event in stream:
        match event.type:
            case "agent.message":
                print(event.content.text)
            case "agent.tool_use":
                print(f"Using tool: {event.name}")
            case "session.status_idle":
                print("Agent finished.")

通过这段代码，我们创建了一个名为“Coding Assistant”的 Agent，并定义了它所使用的工具集。接着，启动一个 Session 并发送用户指令：“生成前20个斐波那契数并保存到文件”。在运行过程中，系统会打印出相应的输出信息。

这个例子展示了 Managed Agents 如何简化开发过程和提高功能实现的灵活性与效率。

通过以上内容，我们对 Claude Managed Agents 的工作原理和技术细节有了全面的理解。无论是从技术架构层面还是实践应用角度来看，Managed Agents 都为开发者提供了一个强大的工具来快速构建智能代理系统。

五、它和相似方案有什么区别

容易混淆的三个概念：消息API（Messages API）、代理SDK（Agent SDK）以及托管代理（Managed Agents）。

几条经验法则：

• 如果你在开发一个命令行工具（如代码助手或CLI任务管理器），使用代理SDK较为合适。这种情况下，程序需要直接访问用户的文件系统和资源。
• 若你正在构建一个SaaS产品，并希望内置“让AI帮助用户执行事务性操作”的功能，则应考虑采用托管代理服务。该模式下，无需为每个用户单独维护容器环境，降低了运维复杂度与成本。
• 当任务仅涉及文本生成或简单的信息处理时，选择消息API更为经济高效，避免过度配置资源。

另一个常见的混淆点是模型上下文协议（Model Context Protocol, MCP）。MCP旨在提供一套标准框架用于定义和调用各种工具。然而它本身并不负责代理的运行环境搭建问题；相比之下，托管代理服务则涵盖了从容器管理到事件处理的一整套解决方案。

六、局限与注意事项

尽管托管代理提供了许多便利功能，但其目前仍存在一些实际限制：

1. 不稳定性和API变更风险

当前版本为测试版（如managed-agents-2026-04-01），意味着相关协议和接口可能频繁变动。开发者需时刻关注最新文档更新以适应变化。

2. 供应商锁定问题加剧

与仅依赖消息API的方案相比，托管代理服务更加绑定于特定提供商（Anthropic）。这意味着迁移成本较高，灵活性不如自建解决方案。

3. 额外计费条款

除基础模型调用费用外，还会根据会话时长收取额外费用（如每小时0.08美元）以覆盖服务器资源使用。对于持续运行的长期任务尤其需要注意这一项开支。

4. 容器环境限制

用户无法直接访问或修改托管环境中容器内的配置细节（例如通过SSH登录）。需遵循Anthropic提供的预定义语言和库支持范围；超出部分可通过扩展接口实现，但灵活性受限。

5. 请求频率限制

不同类型请求存在固定速率上限，如创建会话等操作每分钟只能进行60次。批量处理场景下尤其需要注意避免触发限流机制导致服务中断。

6. 有限的持久化能力

虽然托管代理支持一定程度的状态存储与恢复功能，但具体保留时间、回收规则及文件系统保存策略需查阅官方文档明确了解，并不能无限期保持数据状态。

7. 预研特性尚未开放

诸如自我评估反馈循环（outcomes）、多Agent协调通信框架以及长期记忆机制等高级功能目前仍处于研究阶段，实际应用前建议谨慎评估其可用性与成熟度。

七、总结

总体而言，托管代理服务代表了Anthropic在构建更加健壮的AI代理生态系统方面迈出的重要一步。该方案特别适合那些需要长时间运行且具备复杂工具调用能力的应用场景。对于希望快速上线并专注于核心业务逻辑开发而非底层架构维护的团队来说尤为有利。

然而，鉴于其Beta状态及潜在的技术限制因素，建议在项目初期先进行充分评估与验证工作，以确保技术选型符合实际需求，并为未来可能出现的变化做好准备。