构建您的第一个托管代理
如果您曾经手动构建过代理循环,您一定熟悉这套流程:while 循环、stop reason(停止原因)判断分支、工具执行。这种方式是可行的,而且对许多功能来说,这其实是正确的形态。但有时这个循环需要运行很长时间 —— 几分钟,甚至几个小时 —— 跨越许多工具,要保持状态、写入文件,并在网络故障后恢复工作。在这种情况下,您不会希望在自己的服务器上运行这个循环,而是希望把它委托出去。这就是托管代理(managed agents)的作用。
什么是托管代理?
托管代理是一个运行在 Anthropic 基础设施上(而非您自己的基础设施上)的代理循环。您描述一次代理,为其提供一个工作环境,然后启动一个会话。Anthropic 运行该循环,您只需在其工作时将事件流式传回即可。
每个 API 账户默认都启用了托管代理 —— 无需特殊权限。
四个基本要素
共有四个基本要素,它们按顺序出现:
- Agent(代理) —— 角色本身:模型、系统提示和工具集。这可以在多次运行中复用。
- Environment(环境) —— 代理运行的位置:云端或自托管、网络配置等。
- Session(会话) —— 代理在特定环境中的一次运行。会话是工作的单位。
- Events(事件) —— 流入和流出的消息:代理的动作、工具调用、结果、回复。
下面是这些部分是如何配合运作的:您的应用与会话通信,会话驱动环境内的工作,发生的一切都会通过事件流流回:

请注意这里的转变:您不是在运行一个 while 循环,而是在发送事件和读取事件。
最小化的托管代理
让我们构建一个能做些有用事情的最小托管代理:在临时驱动器中创建一个文件,统计其行数,并报告结果。
对于工具,我们将使用agent toolset(代理工具集)—— Anthropic 捆绑的文件、bash 和网络工具。它们足以完成此任务,因此我们无需自行定义任何工具。
第 1 步:创建代理
首先,我们创建代理。请注意,代理工具集就直接定义在 tools 数组中 —— 这就是那个捆绑工具集:
import anthropic
client = anthropic.Anthropic()
agent = client.beta.agents.create(
name="Line Counter",
model="claude-opus-5",
system="You are a helpful agent that completes small file tasks.",
tools=[
{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}
],
)请记住:代理是可复用的。创建一次,即可在多个会话中运行它。
第 2 步:创建环境
接下来是环境。它定义了代理运行所在的沙箱:云端,网络设置为 limited。使用 limited 时,沙箱和网络工具只能访问您在 allowed_hosts 中列出的主机。这个任务不需要网络,因此我们不列出任何主机。只有当代理必须访问您无法提前列出的站点时,才使用 unrestricted。每个会话都有自己的沙箱,文件就写入其中:
environment = client.beta.environments.create(
name="line-counter-env",
config={
"type": "cloud",
"networking": {"type": "limited"},
},
)第 3 步:创建会话
然后,我们使用代理和环境创建一个会话,外加一个可选的标题。会话是工作的单位:
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
title="Count lines demo",
)第 4 步:打开事件流,然后发送启动消息
现在我们打开事件流 —— 请注意,我们首先执行此操作。事件流只会传递在其打开之后发生的事件,因此务必在发送启动消息之前先打开它。然后,我们将用户消息发送到这个实时流中:
with client.beta.sessions.events.stream(session_id=session.id) as stream:
# 流已打开 —— 现在发送启动消息
client.beta.sessions.events.send(
session_id=session.id,
events=[
{
"type": "user.message",
"content": [
{
"type": "text",
"text": "Create a file in the temp directory, "
"count its lines, and report back.",
}
],
}
],
)请注意这是 events —— 复数形式。在这个 API 中,一切都是通过事件流动的。
第 5 步:消费事件流
最后,我们消费该事件流,仍然在第 4 步的 with 代码块内。对于这个演示来说,有三种重要的事件类型:
agent.message—— Claude 的文本agent.tool_use—— Claude 选择了哪个工具session.status_idle—— 代理已停止并正在等待输入
这个演示在第一个空闲事件处停止。在您自己的应用中,应在将工作视为已完成之前检查 event.stop_reason.type:end_turn 表示代理已结束其回合,或者是您中断了它;而 requires_action 表示某个工具调用需要您给出答复。
for event in stream:
if event.type == "agent.message":
for block in event.content:
if block.type == "text":
print(block.text, end="", flush=True)
elif event.type == "agent.tool_use":
print(f"\n[tool] {event.name}")
elif event.type == "session.status_idle":
print("\n--- Agent done ---")
break运行它,输出的是代理的"出声思考"过程 —— 实际的文本、它所选择的工具,以及最终的答案。这一切都运行在 Anthropic 的容器中,而不是您自己的容器中:

这其中的取舍
通常情况下,使用代理时,我们有自己的循环,必须控制一切。而使用托管代理,您将该循环、沙箱和可恢复性都委托出去 —— 只需在事件流到来时进行消费即可。会话的事件历史记录存储在服务器上。因此,如果您的连接中断,请打开一个新的流,列出过去的事件以查看您错过了什么,并跳过列表中已经返回过的任何实时事件。相关代码请参阅不错过事件地重新连接(在新标签页中打开)。
在生产应用中,这就是用于长时间运行、涉及文件操作、"帮我整理一下这个"类任务的形态。想象一下文件共享清理:一个托管代理读取目标目录结构规范,遍历杂乱的待处理文件夹,将文件移动到正确的项目文件夹中,归档重复文件和零字节的垃圾文件,并标记出它无法自信地归类的内容 —— 这一切都在一个可以针对数千个文件运行数分钟的会话中完成。下面是它在真实应用中的样子 —— 一个文件共享清理仪表盘,实时流式显示代理在整理、归档和标记文件时的活动:

小结
- 托管代理就是为您运行的代理循环 —— 运行在 Anthropic 的基础设施上,而非您自己的服务器上。
- 流程是:创建代理、创建环境、创建会话、发送事件、流式接收事件。
- 代理(模型、系统提示、工具集)可在多次运行中复用;会话是单次运行;事件是一切流动的方式。
- 在发送启动消息之前打开事件流 —— 它只传递在其打开之后发生的事件。
- 请留意三种事件:
agent.message(文本)、agent.tool_use(工具选择)和session.status_idle(已停止并等待输入,stop_reason.type说明原因)。 - 当循环会运行过久、做的事情过多,或需要能够在出现故障时恢复时,请选择托管代理。当您想要完全控制时,请选择手动循环。