什么是托管代理？

如果你曾手动构建过代理循环，一定熟悉这套流程：while循环、停止原因判断、工具执行。这种方式确实有效，并且在许多场景下是最合适的。但有时，这个循环会运行很长时间——几分钟，甚至几小时——涉及多个工具，需要维护状态、写入文件，并在网络波动后恢复工作。这时，你就不希望在自己的服务器上运行这个循环了。你需要委托它。这就是托管代理的用途。

托管代理是什么？

托管代理是在Anthropic基础设施而非你的服务器上运行的代理循环。你只需一次性定义代理，为其提供运行环境并启动会话。Anthropic负责运行循环，而你只需实时接收工作过程中产生的事件流。

所有API账户默认启用托管代理功能——无需特殊权限。

四大基础组件

托管代理包含四个按顺序使用的基础组件：

• 代理(Agent) —— 角色设定：模型、系统提示词和工具集。可跨多次运行重复使用。
• 环境(Environment) —— 代理运行场所：云端或本地环境，网络配置等。
• 会话(Session) —— 特定环境中代理的一次运行实例。会话是工作执行单元。
• 事件(Events) —— 输入输出的消息流：代理动作、工具调用、结果和回复。

组件协作关系如下：你的应用与会话交互，会话在环境中驱动工作，所有发生的事件通过事件流回传：

架构图显示代理连接到会话，会话驱动环境执行，结果通过事件流回传至应用

注意这里的范式转变：你不再运行while循环，而是发送和接收事件。

最小化托管代理示例

让我们构建一个能完成实际任务的最小托管代理：在临时驱动器创建文件，统计行数并返回结果。

工具方面，我们将使用代理工具集——Anthropic内置的文件、bash和网络工具。这些工具足以完成任务，因此我们无需自定义工具。

第一步：创建代理

首先创建代理。注意tools数组中直接定义的代理工具集——这是内置工具包：

记住：代理是可复用的。创建一次即可用于多个会话。

第二步：创建环境

接着创建环境。这会启动容器模板——云端环境，无网络限制。这是实际写入文件的沙箱：

第三步：创建会话

然后创建会话，关联代理和环境，可添加可选标题。会话是工作执行单元：

第四步：开启事件流并发送启动消息

现在开启事件流——注意我们要先开启。事件流只接收开启后发生的事件，因此务必在发送启动消息前开启。然后我们向活动流发送用户消息：

注意是events——复数形式。事件是这个API中所有交互的载体。

第五步：消费事件流

最后我们消费事件流。本演示涉及三种重要事件类型：

• agent. message —— Claude的文本输出
• agent. tool_use —— Claude选择的工具
• session. status_idle —— 代理完成工作

运行时，输出显示代理的思考过程——实际文本、选择的工具及最终答案。所有这些都在Anthropic的容器中运行，而非你的环境：

托管代理运行的终端输出：显示代理ID、环境ID和会话ID创建过程，事件流展示代理写入文件、运行工具并报告文件包含3行

权衡取舍

传统代理通常需要我们自行控制整个循环。而托管代理将循环控制、沙箱环境和可恢复性委托出去，你只需消费传入的事件流。

在生产应用中，这种模式适合长时间运行、涉及文件操作的"请帮我整理这个"类任务。想象一个文件共享清理场景：托管代理读取目标目录结构规范，遍历杂乱的传入文件夹，将文件移至正确的项目文件夹，归档重复文件和零字节垃圾，并标记所有无法确定位置的内容——整个会话可能针对数千个文件运行数分钟。这是实际应用中的场景——一个文件共享清理仪表板实时流式传输代理整理、归档和标记文件的活动：

由托管代理驱动的文件共享清理web应用，显示正在整理的文件夹树结构及代理移动和归档文件时的实时活动事件流

要点回顾

• 托管代理是为你运行的代理循环——运行在Anthropic的基础设施上而非你的服务器。
• 流程是：创建代理→创建环境→创建会话→发送事件→接收事件流。
• 代理(模型、系统提示、工具集)可跨运行复用；会话是单次运行实例；事件是所有交互的载体。
• 发送启动消息前先开启事件流——它只接收开启后的事件。
• 关注三种事件：agent. message(文本)、agent. tool_use(工具选择)和session. status_idle(完成)。
• 当循环运行时间过长、任务过重或需要容错时选择托管代理；需要完全控制时选择手动循环。