托管智能体第一步

Claude 托管智能体入门

创建您的第一个自主智能体。

本指南将引导您完成创建智能体、设置环境、启动会话以及流式传输智能体响应的全过程。

想要交互式演练？ 在最新版本的 Claude Code 中运行 /claude-api managed-agents-onboard，即可获得引导式设置和交互式问答。

核心概念

概念	描述
Agent（代理）	模型、系统提示、工具、MCP 服务器和技能
Environment（环境）	会话运行位置的配置：由 Anthropic 托管的云沙箱，或在您自己的基础设施上自托管的沙箱
Session（会话）	在环境中运行的代理实例，执行特定任务并生成输出
Events（事件）	您的应用程序与代理之间交换的消息（用户轮次、工具结果、状态更新）

前提条件

一个 Anthropic Console 账户
一个 API 密钥

安装 CLI

检查安装是否成功：

ant --version

安装 SDK

将您的 API 密钥设置为环境变量：

export ANTHROPIC_API_KEY="your-api-key-here"

创建您的第一个会话

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 标头。SDK 会自动设置该 beta 标头。

创建智能体
创建一个智能体，定义其模型、系统提示和可用工具。
ant beta:agents create \ --name "Coding Assistant" \ --model '{id: claude-opus-4-8}' \ --system "You are a helpful coding assistant. Write clean, well-documented code." \ --tool '{type: agent_toolset_20260401}'
agent_toolset_20260401 工具类型会启用完整的预构建智能体工具集（bash、文件操作、网络搜索等）。有关完整列表和每个工具的配置选项，请参阅工具。
保存返回的 agent.id。您将在创建的每个会话中引用它。
创建环境
环境定义了智能体运行所在的沙盒。
ant beta:environments create \ --name "quickstart-env" \ --config '{type: cloud, networking: {type: unrestricted}}'
保存返回的 environment.id。您将在创建的每个会话中引用它。
如需在您自己的基础设施上运行沙盒而非使用云沙盒，请参阅自托管沙盒。

启动会话

创建一个引用您的智能体和环境的会话。

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

print(f"Session ID: {session.id}")

发送消息并流式传输响应

打开一个流，发送一个用户事件，然后在事件到达时进行处理：

with client.beta.sessions.events.stream(session.id) as stream:
    # 在流打开后发送用户消息
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt",
                    },
                ],
            },
        ],
    )

    # 处理流式传输事件
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[Using tool: {event.name}]")
            case "session.status_idle":
                print("\n\nAgent finished.")
                break

智能体会编写一个 Python 脚本，在沙盒中执行它，并验证输出文件是否已创建。您的输出类似于以下内容：

I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file.
[Using tool: write]
[Using tool: bash]
The script ran successfully. Let me verify the output file.
[Using tool: bash]
fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).

Agent finished.

工作原理

当您发送用户事件时，Claude 托管智能体会：

配置沙盒： 您的环境配置决定了沙盒的构建方式。
运行智能体循环： Claude 根据您的消息确定要使用哪些工具。
执行工具： 文件写入、bash 命令和其他工具调用都在沙盒内运行。
流式传输事件： 您会在智能体工作时收到实时更新。
进入空闲状态： 当智能体没有更多任务要执行时，会发出 session.status_idle 事件。

后续步骤

创建可复用、带版本控制的智能体配置

自定义网络和沙盒设置

为您的智能体启用特定工具

处理事件并在执行过程中引导智能体

按照定期 cron 计划运行您的智能体

Was this page helpful?

核心概念

概念	描述
Agent（代理）	模型、系统提示、工具、MCP 服务器和技能
Environment（环境）	会话运行位置的配置：由 Anthropic 托管的云沙箱，或在您自己的基础设施上自托管的沙箱
Session（会话）	在环境中运行的代理实例，执行特定任务并生成输出
Events（事件）	您的应用程序与代理之间交换的消息（用户轮次、工具结果、状态更新）

创建您的第一个会话

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 标头。SDK 会自动设置该 beta 标头。

创建智能体
创建一个智能体，定义其模型、系统提示和可用工具。
ant beta:agents create \ --name "Coding Assistant" \ --model '{id: claude-opus-4-8}' \ --system "You are a helpful coding assistant. Write clean, well-documented code." \ --tool '{type: agent_toolset_20260401}'
agent_toolset_20260401 工具类型会启用完整的预构建智能体工具集（bash、文件操作、网络搜索等）。有关完整列表和每个工具的配置选项，请参阅工具。
保存返回的 agent.id。您将在创建的每个会话中引用它。
创建环境
环境定义了智能体运行所在的沙盒。
ant beta:environments create \ --name "quickstart-env" \ --config '{type: cloud, networking: {type: unrestricted}}'
保存返回的 environment.id。您将在创建的每个会话中引用它。
如需在您自己的基础设施上运行沙盒而非使用云沙盒，请参阅自托管沙盒。

启动会话

创建一个引用您的智能体和环境的会话。

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

print(f"Session ID: {session.id}")

发送消息并流式传输响应

打开一个流，发送一个用户事件，然后在事件到达时进行处理：

with client.beta.sessions.events.stream(session.id) as stream:
    # 在流打开后发送用户消息
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt",
                    },
                ],
            },
        ],
    )

    # 处理流式传输事件
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[Using tool: {event.name}]")
            case "session.status_idle":
                print("\n\nAgent finished.")
                break

智能体会编写一个 Python 脚本，在沙盒中执行它，并验证输出文件是否已创建。您的输出类似于以下内容：

I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file.
[Using tool: write]
[Using tool: bash]
The script ran successfully. Let me verify the output file.
[Using tool: bash]
fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).

Agent finished.

工作原理

当您发送用户事件时，Claude 托管智能体会：

配置沙盒： 您的环境配置决定了沙盒的构建方式。

运行智能体循环： Claude 根据您的消息确定要使用哪些工具。

执行工具： 文件写入、bash 命令和其他工具调用都在沙盒内运行。

流式传输事件： 您会在智能体工作时收到实时更新。

进入空闲状态： 当智能体没有更多任务要执行时，会发出 session.status_idle 事件。

核心概念

前提条件

安装 CLI

安装 SDK

创建您的第一个会话

工作原理

后续步骤

核心概念

前提条件

安装 CLI

安装 SDK

创建您的第一个会话

工作原理

后续步骤

核心概念

前提条件

安装 CLI

安装 SDK

创建您的第一个会话

工作原理

后续步骤

核心概念

前提条件

安装 CLI

安装 SDK

创建您的第一个会话

工作原理

后续步骤