加载中

构建您的第一个托管代理

第 12 课8 分钟
加载中

构建您的第一个托管代理

如果您曾经手动构建过代理循环,您一定熟悉这套流程:while 循环、stop reason(停止原因)判断分支、工具执行。这种方式是可行的,而且对许多功能来说,这其实是正确的形态。但有时这个循环需要运行很长时间 —— 几分钟,甚至几个小时 —— 跨越许多工具,要保持状态、写入文件,并在网络故障后恢复工作。在这种情况下,您不会希望在自己的服务器上运行这个循环,而是希望把它委托出去。这就是托管代理(managed agents)的作用。

什么是托管代理?

托管代理是一个运行在 Anthropic 基础设施上(而非您自己的基础设施上)的代理循环。您描述一次代理,为其提供一个工作环境,然后启动一个会话。Anthropic 运行该循环,您只需在其工作时将事件流式传回即可。

每个 API 账户默认都启用了托管代理 —— 无需特殊权限。

四个基本要素

共有四个基本要素,它们按顺序出现:

  1. Agent(代理) —— 角色本身:模型、系统提示和工具集。这可以在多次运行中复用。
  2. Environment(环境) —— 代理运行的位置:云端或自托管、网络配置等。
  3. Session(会话) —— 代理在特定环境中的一次运行。会话是工作的单位。
  4. Events(事件) —— 流入和流出的消息:代理的动作、工具调用、结果、回复。

下面是这些部分是如何配合运作的:您的应用与会话通信,会话驱动环境内的工作,发生的一切都会通过事件流流回:

显示代理连接到会话、会话驱动环境、结果通过事件流流回应用的架构图

请注意这里的转变:您不是在运行一个 while 循环,而是在发送事件和读取事件。

最小化的托管代理

让我们构建一个能做些有用事情的最小托管代理:在临时驱动器中创建一个文件,统计其行数,并报告结果。

对于工具,我们将使用agent toolset(代理工具集)—— Anthropic 捆绑的文件、bash 和网络工具。它们足以完成此任务,因此我们无需自行定义任何工具。

第 1 步:创建代理

首先,我们创建代理。请注意,代理工具集就直接定义在 tools 数组中 —— 这就是那个捆绑工具集:

python
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。每个会话都有自己的沙箱,文件就写入其中:

python
environment = client.beta.environments.create(
    name="line-counter-env",
    config={
        "type": "cloud",
        "networking": {"type": "limited"},
    },
)

第 3 步:创建会话

然后,我们使用代理和环境创建一个会话,外加一个可选的标题。会话是工作的单位:

python
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Count lines demo",
)

第 4 步:打开事件流,然后发送启动消息

现在我们打开事件流 —— 请注意,我们首先执行此操作。事件流只会传递在其打开之后发生的事件,因此务必在发送启动消息之前先打开它。然后,我们将用户消息发送到这个实时流中:

python
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 表示某个工具调用需要您给出答复。

python
    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 的容器中,而不是您自己的容器中:

托管代理运行的终端输出:创建了代理、环境和会话 ID,然后事件流显示代理写入文件、运行其工具,并报告该文件包含 3 行内容

这其中的取舍

通常情况下,使用代理时,我们有自己的循环,必须控制一切。而使用托管代理,您将该循环、沙箱和可恢复性都委托出去 —— 只需在事件流到来时进行消费即可。会话的事件历史记录存储在服务器上。因此,如果您的连接中断,请打开一个新的流,列出过去的事件以查看您错过了什么,并跳过列表中已经返回过的任何实时事件。相关代码请参阅不错过事件地重新连接。

在生产应用中,这就是用于长时间运行、涉及文件操作、"帮我整理一下这个"类任务的形态。想象一下文件共享清理:一个托管代理读取目标目录结构规范,遍历杂乱的待处理文件夹,将文件移动到正确的项目文件夹中,归档重复文件和零字节的垃圾文件,并标记出它无法自信地归类的内容 —— 这一切都在一个可以针对数千个文件运行数分钟的会话中完成。下面是它在真实应用中的样子 —— 一个文件共享清理仪表盘,实时流式显示代理在整理、归档和标记文件时的活动:

由托管代理驱动的文件共享清理 Web 应用,显示正在整理的文件夹树,以及代理在移动和归档文件时产生的事件实时活动提要

小结

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