构建您的第一个托管代理

什么是托管代理？

托管代理是一种运行在 Anthropic 基础设施上（而不是您自己的基础设施上）的代理循环。您只需描述一次代理，为它提供一个运行环境，然后启动一个会话。Anthropic 负责运行这个循环，而您只需在它工作时将事件流式传输出来。

托管代理在每个 API 账户中默认启用——无需任何特殊权限。

四个基本元素

共有四个基本元素，它们按以下顺序出现：

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

以下是这些部分如何组合在一起的：您的应用与一个会话通信，该会话驱动环境内的工作，而发生的一切都会通过事件流回传出来：



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

最小化的托管代理

让我们构建一个能完成有用工作的最小托管代理：在临时驱动器中创建一个文件，统计其行数，并报告结果。

对于工具，我们将使用代理工具集（agent toolset）——Anthropic 捆绑的文件、bash 和网络工具。它们完全能胜任这个任务，所以我们不需要自己定义任何工具。

第一步：创建代理

首先，我们创建代理。请注意代理工具集就直接定义在 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}}
    ],
)

请记住：代理是可复用的。创建一次，就可以在多个会话中运行它。

第二步：创建环境

接下来是环境。它定义了您的代理运行所在的沙箱：云端，网络设置为 limited。在 limited 模式下，沙箱和网络工具只能访问您在 allowed_hosts 中列出的主机。这个任务不需要网络，所以我们不列出任何主机。只有当代理必须访问您无法提前列出的站点时，才使用 unrestricted。每个会话都有自己独立的沙箱，文件就是写入到那里的：

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

第三步：创建会话

然后，我们用代理和环境创建一个会话，再加上一个可选的标题。会话是工作的基本单位：

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

第四步：打开事件流，然后发送启动消息

现在我们打开事件流——请注意我们是先这样做的。事件流只会传递在它打开之后发生的事件，所以务必在发送启动消息之前先打开它。然后我们将用户消息发送到这个实时流中：

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 中一切流动的方式。

第五步：消费事件流

最后，我们消费这个事件流。对于这个演示来说，有三种重要的事件类型：

• agent.message——Claude 的文本
• agent.tool_use——Claude 选择了哪个工具
• session.status_idle——代理已停止并正在等待输入

这个演示在第一个 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 会说明原因）。
• 当循环会运行过长时间、做太多事情，或需要在中断后存活下来时，选择托管代理。当您想要完全掌控时，选择手动循环。