构建你的第一个 managed agent

如果你已经手动构建了 agent 循环，你就知道是怎么回事：while 循环、停止原因 switch、工具执行。这可以工作，对于许多功能来说它实际上是正确的形式。但有时那个循环会运行很长时间——几分钟，甚至可能几小时——跨多个工具，需要保持状态、写入文件以及在网络中断后恢复工作。在那时，你不想在服务器上运行循环。你想委派它。这就是 managed agents 的用途。

什么是 managed agent？

Managed agent 是在 Anthropic 的基础设施上而不是你的服务器上运行的 agent 循环。你描述一次 agent，给它一个工作环境，然后启动一个会话。Anthropic 运行循环，你只需在其工作时流式传输事件。

Managed agents 对每个 API 账户默认启用——不需要特殊访问权限。

四个原语

有四个原语，它们按顺序出现：

1. Agent — 角色：模型、系统提示和工具集。这在多次运行中可重用。
2. Environment — agent 运行的地方：云端或自托管、网络配置等。
3. Session — agent 在特定环境中的单次运行。会话是工作单元。
4. Events — 流入和流出的消息：agent 的操作、工具调用、结果、回复。

以下是各部分如何配合：你的应用与会话通信，会话驱动环境内的工作，发生的一切通过事件流流回。

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

最小的 managed agent

让我们构建最小的 managed agent，做一些有用的事情：在临时驱动器中创建一个文件，计算其行数并报告回来。

对于工具，我们将使用 agent 工具集 — Anthropic 打包的文件、bash 和网页工具。它们对此任务工作正常，因此我们不必自己定义任何工具。

步骤 1：创建 agent

首先，我们创建 agent。注意 tools 数组中定义的 agent 工具集——这是打包的工具集：

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}}
    ],
)

记住：agent 是可重用的。创建一次并在多个会话中运行它。

步骤 2：创建环境

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

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

步骤 3：创建会话

然后我们使用 agent 和环境创建会话，加上可选的标题。会话是工作单元：

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.",
                    }
                ],
            }
        ],
    )