如何使用 Claude Sonnet 5 构建 Claude 托管代理（Managed Agents）

您是否曾想过在 Python 脚本中运行类似 Claude Code 的工作流，让模型在受管环境中访问工具、文件、技能和指令？

Claude 托管代理正是为此类工作流而设计，帮助您在可控环境中构建能够执行多步任务的代理。

在本教程中，我将向您展示如何使用Claude Sonnet 5，这是 Anthropic 近期发布、面向高级推理、编码与数据分析任务的模型。它为代理提供检查数据、使用工具、编写并执行代码、生成结构化输出的能力。

您将创建一个托管代理，配置其环境，上传一个 CSV 文件，并赋予代理对工具和 XLSX 技能的访问权限。

代理会分析数据，生成 Python、JSON 和 Excel 文件，验证结果，并提供已完成的输出以供下载。

如果您完全不熟悉 Claude，建议先查看 Claude Code 101 课程。

什么是 Claude 托管代理？

Claude 托管代理是 Anthropic 用于以自主代理方式运行 Claude 的托管框架。

与其自己编写循环来发送提示、执行工具调用、保存结果并管理运行时，不如定义代理并让 Anthropic 负责相关基础设施。

它适用于更长的、多步骤任务，模型可能需要在完成工作前使用多个工具。

托管代理由四个主要部分构成：

• Agent（代理）：可复用的配置，包含模型、系统提示、工具、MCP 服务器和技能。
• Environment（环境）：代理运行所在的位置，可选择 Anthropic 的云沙箱或您自建的沙箱。
• Session（会话）：执行特定任务的代理运行实例。
• Events（事件）：会话运行期间交换的消息、工具调用、结果与状态更新。

1. 准备 Claude 代理工作区

要跟随本教程，请在您的电脑上安装Python 3.12 或更高版本和Jupyter Notebook。我们将使用 Jupyter Notebook 逐步创建、运行并检查托管代理。

您还需要一个 Anthropic Console 账户。

请在 Console 中创建新的 API 密钥，至少充值$5 的 API 额度，并妥善保存密钥。

托管代理在单次会话中可能会进行多次模型与工具调用，因此成本可能高于一次标准的 API 请求。

将该密钥存为 ANTHROPIC_API_KEY 环境变量，而不是直接添加到 notebook 或提交到 GitHub。

对于 macOS、Linux 或 WSL，请在终端中运行：

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

对于 Windows PowerShell，请使用：

$env:ANTHROPIC_API_KEY="your-api-key-here"

2. 设置 Anthropic Python SDK

在创建托管代理之前，安装官方的 Anthropic Python SDK，并导入本 notebook 所需的模块。

该 SDK 提供 Anthropic 客户端，您将用它来创建代理、环境、文件与会话。

%pip install -q --upgrade anthropic

接下来，从环境变量加载您的 Anthropic API 密钥。

将密钥保存在 notebook 外部比直接放在代码中更安全，尤其是当您计划共享项目或推送到 GitHub 时。

import os
from anthropic import Anthropic

api_key = os.environ.get("ANTHROPIC_API_KEY")
assert api_key, "Set ANTHROPIC_API_KEY in your environment or in a local .env file."

托管代理目前通过 Anthropic 的 beta API 访问。managed-agents-2026-04-01 beta 标志启用此功能，不过官方 SDK 会在托管代理请求中自动发送所需的 beta 头。

我们在 notebook 中保留该标志，因为稍后在列出与下载会话文件时需要用到。

BETA_FLAG = "managed-agents-2026-04-01"

client = Anthropic(api_key=api_key)

最后，创建一个字典来存储本教程期间创建的各个资源的 ID。

其中包括代理、环境、已上传文件与会话。保存这些 ID 便于最后进行清理，即使后续步骤失败也不受影响。

created = {"agent": None, "environment": None, "file": None, "session": None}
print("✓ Anthropic client initialized.")

客户端已就绪。

3. 创建托管代理

托管代理是您工作流的可复用配置。

在创建时，您需要选择 Claude 模型、编写用于定义其角色与指令的系统提示，并附加可用的工具与技能。

随后，您可以在多个会话中复用同一个代理，而无需每次都重新创建配置。

我们将代理命名为Sonnet 5 数据分析师，并使用 claude-sonnet-5。

系统提示要求其扮演一位严谨的数据分析师：检查挂载在 /workspace 的文件，使用代码执行进行分析，保持结果简明，并将最终文件保存到 /mnt/session/outputs。

agent = client.beta.agents.create(
    name="Sonnet 5 Data Analyst",
    model="claude-sonnet-5",
    system=(
        "You are a meticulous data analyst. When asked about data, always read the "
        "file mounted at /workspace, analyse it with the code execution tool, and "
        "report concise, numeric results. Use the XLSX skill for spreadsheet work. "
        "Save final artifacts to /mnt/session/outputs."
    ),
    tools=[
        {"type": "agent_toolset_20260401"},
    ],
    skills=[{"type": "anthropic", "skill_id": "xlsx"}],
)

agent_toolset_20260401 让代理在会话中访问 Anthropic 的内置工具，而 xlsx 技能为创建与分析 Excel 工作簿提供任务级指引。

Anthropic 还提供针对 PowerPoint、Word 与 PDF 工作流的预构建技能。

最后，保存代理 ID。

您稍后在创建会话时会用到它，同时清理环节也会用到它来归档代理。

created["agent"] = agent.id
print(f"✓ Created agent: {agent.id}")

您应会看到类似如下的输出：

✓ Created agent: agent_01EVcgvQsAkLxNnJFp6aynwm

4. 配置 Anthropic 云沙箱

接下来，我们将创建托管代理在会话期间运行的环境。

环境充当安全沙箱，为代理提供独立工作区以读取挂载文件、编写代码并运行命令。

我们将使用 Anthropic 的云环境并启用受限网络。稍后代理会在此沙箱中使用 Python 分析已上传的 CSV 文件。

environment = client.beta.environments.create(
    name="code-exec-sandbox",
    config={"type": "cloud", "networking": {"type": "limited"}},
)

created["environment"] = environment.id
print(f"✓ Created environment: {environment.id}")

运行该单元后，您应会看到类似如下的环境 ID：

✓ Created environment: env_01FzWACEf9UJDL65ovBPA1zf

5. 使用 Anthropic Files API 上传数据

接下来，我们将上传代理要分析的数据集。

托管代理使用 Anthropic 的 Files API 上传本地文件，随后可在会话环境中进行挂载。

在本指南中，我们使用名为 sales_data.csv 的示例 12 行数据集。

上传前，我们先检查文件是否存在，并确认其包含预期的数据行数。

from pathlib import Path

csv_path = Path("sales_data.csv")
assert csv_path.exists(), f"Missing input file: {csv_path.resolve()}"

row_count = sum(1 for _ in csv_path.open(encoding="utf-8")) - 1
assert row_count == 12, f"Expected 12 data rows, found {row_count}"

然后我们上传该文件，并保存其 ID 以便后续清理。

uploaded = client.beta.files.upload(file=csv_path)

created["file"] = uploaded.id
print(f"✓ Uploaded {csv_path}: {uploaded.id} ({row_count} rows)")

运行该单元后，您应会看到类似如下的输出：

✓ Uploaded sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12 rows)

6. 初始化代理执行会话

现在，我们将创建一个会话。

会话将代理、环境与其执行特定任务所需的资源连接起来。此处我们将已上传的 CSV 文件挂载到 /workspace/sales_data.csv，以便代理能在沙箱内访问它。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": uploaded.id,
            "mount_path": "/workspace/sales_data.csv",
        },
    ],
)

created["session"] = session.id
print(f"✓ Created session: {session.id}")

您应会看到类似如下的会话 ID：

✓ Created session: sesn_015mNhrKhqqfe7u8VP6GuFdr

7. 流式查看代理的响应

现在，我们将把任务发送给会话，并在代理工作时流式查看其活动。

创建会话只是为代理与沙箱做准备；代理在收到 user.message 事件后才开始工作。

事件流让我们能实时看到代理的消息、工具调用及最终会话状态。

该提示要求代理分析挂载的 CSV 文件，编写并运行 Python 脚本，创建 JSON 摘要，并构建 Excel 报告。

我们还创建了三个变量来收集代理文本、记录其使用的工具，并确认会话是否成功结束。

agent_text_parts = []
tools_used = []
final_status = None

with client.beta.sessions.events.stream(session.id) as stream:
    # Send the user message once the stream is open.
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": (
                            "Use the XLSX skill and analyze /workspace/sales_data.csv. "
                            "Write /mnt/session/outputs/analyze_sales.py, run that Python "
                            "script, and have it create /mnt/session/outputs/summary.json. "
                            "Also create /mnt/session/outputs/sales_report.xlsx with the "
                            "source data, monthly profit, and a summary sheet."
                        ),
                    }
                ],
            }
        ],
    )

    for event in stream:
        etype = getattr(event, "type", None)

        if etype == "agent.message":
            for block in event.content:
                txt = getattr(block, "text", None)
                if txt:
                    print(txt, end="")
                    agent_text_parts.append(txt)

        elif etype == "agent.tool_use":
            name = getattr(event, "name", "<tool>")
            print(f"\n[tool_use] {name}")
            tools_used.append(name)

        elif etype == "session.status_idle":
            final_status = "idle"
            print("\n\n✓ Agent finished; session is idle.")
            break

        elif etype == "session.status_error":
            final_status = "error"
            print("\n✗ Session reported an error.")
            break

print("Tools used:", tools_used)

在运行过程中，您应会看到如 read、bash、write 和 edit 等工具事件。

这些事件表明代理正在检查可用的指令与文件、编写分析脚本、在沙箱中运行脚本，并修复其发现的问题。

当代理没有进一步工作要做时，会话会变为空闲状态。在此示例中，session.status_idle 表示任务已完成，因此我们停止监听流。

Anthropic 会在沙箱内管理其内置工具的执行；仅在使用自定义工具时，您才需要自行处理工具结果。

8. 获取生成的文件与事件历史

会话完成后，我们可以检查其保存的事件历史，并下载由代理创建的文件。

事件历史提供了会话的完整记录，包括模型请求、工具调用、工具结果和状态变化。

history = client.beta.sessions.events.list(session.id, order="asc")

print("--- Session event history ---")
for event in history.data:
    print(event.type)

print(f"({len(history.data)} events total)")

接着，我们列出附加到会话的文件，并下载所有标记为可下载的文件。文件将本地保存到 outputs 文件夹中。

import os

os.makedirs("outputs", exist_ok=True)

files = client.beta.files.list(scope_id=session.id, betas=[BETA_FLAG])
downloadable = [f for f in files.data if f.downloadable]

print(f"Found {len(downloadable)} downloadable file(s) for this session.")

downloaded_paths = []

for f in downloadable:
    try:
        content = client.beta.files.download(f.id, betas=[BETA_FLAG])
        local_path = os.path.join("outputs", f.filename)

        content.write_to_file(local_path)
        downloaded_paths.append(local_path)

        print(f"  downloaded {f.id} -> {local_path}")
    except Exception as exc:
        print(f"  skip {f.id}: {exc}")

最后，我们检查所有预期输出是否已成功下载：

expected_outputs = {"analyze_sales.py", "summary.json", "sales_report.xlsx"}
downloaded_names = {os.path.basename(path) for path in downloaded_paths}

assert expected_outputs <= downloaded_names, (
    f"Missing expected outputs: {sorted(expected_outputs - downloaded_names)}"
)

生成的 Python 脚本、JSON 摘要与 Excel 报告现已可在本地 outputs 文件夹中获取。

9. 分析 Python、JSON 与 Excel 输出

代理完成任务后，生成的文件会下载到本地 outputs/ 目录。

这些文件表明代理不仅返回了文本响应：它编写并执行了代码，创建了结构化数据，并生成了可独立审阅的电子表格报告。

下方截图展示了这三个生成产物。

该文件包含代理编写并执行的分析代码，使工作流可复现且便于检查。

该文件以结构化格式存储结果，可供仪表板、API 或其他程序使用。

该 Excel 文件以可视化形式展示月度计算，包括收入、成本、利润、利润率、合计与图表。

对于 sales_data.csv 中的 12 行数据，核验结果为：

• 总收入：$32,900
• 总成本：$14,750
• 总利润：$18,150
• 平均月利润：$1,512.50
• 最佳月份：12 月（利润 $2,550）
• 最差月份：1 月（利润 $400）

该工作簿以公式驱动，而非仅依赖硬编码数值。

在运行过程中，代理阅读了附带的 XLSX 技能说明，创建工作簿，使用 LibreOffice 重新计算并检查了公式，并在完成任务前修复了循环引用问题。

10. 清理托管代理 API 资源

托管代理资源会一直保留，直到您手动移除，因此在任务完成后及时清理非常重要。

活动资源——尤其是正在运行的会话与环境——若保持运行，可能会持续产生成本。

会话必须处于空闲状态才能删除。

在最后一步，我们删除会话、已上传文件与环境，然后归档代理。

每个清理操作都封装在一个辅助函数中，以防某一步删除失败而影响其余资源的移除。

def safe(label, fn):
    try:
        fn()
        print(f"✓ deleted {label}")
    except Exception as exc:
        print(f"· could not delete {label}: {exc}")

if created["session"]:
    safe("session", lambda: client.beta.sessions.delete(created["session"]))

if created["file"]:
    safe("file", lambda: client.beta.files.delete(created["file"]))

if created["environment"]:
    safe("environment", lambda: client.beta.environments.delete(created["environment"]))

if created["agent"]:
    safe("agent (archived)", lambda: client.beta.agents.archive(created["agent"]))

print("\n🎉 Cleanup complete. The agent is archived; other resources were deleted.")

您应会看到类似如下的输出：

✓ deleted session
✓ deleted file
✓ deleted environment
✓ deleted agent (archived)

🎉 Cleanup complete. The agent is archived; other resources were deleted.

完整项目（含 notebook、示例 CSV 文件与设置说明）已在 GitHub 提供。

您可以克隆该仓库并重新运行 notebook，以复现实用指南中的结果。

结语

我发现 Claude 托管代理的搭建与使用相对简单。

您创建一个代理，赋予其所需的工具、技能与沙箱，然后通过会话运行它。

此后，它可以处理完整的工作流，例如编写代码、创建文件、自检输出并返回最终结果。

我最初尝试使用Modal 沙箱，因为我想要更灵活的外部环境。

然而该设置对于本指南而言过于复杂，因此我决定将本项目聚焦于 Anthropic 的托管云沙箱。

对我而言，主要的不足是成本。我使用仅 12 行的小型 CSV 文件运行了两次本示例，花费约$0.25。

仪表板显示费用计入对应模型下，但我没能找到详细分解。对于简单的计算与电子表格任务，相比更低成本的开源方案，这显得有些昂贵。

总体而言，该项目展示了完整的托管代理工作流：创建代理、上传 CSV 文件、在受管沙箱中运行 Python、生成 JSON 与 Excel 报告、核验输出、下载文件，并在事后清理资源。