Claude托管代理快速入门教程

你已经构建了一个AI代理。它在notebook中运行良好。你的演示很顺利。

现在把它交付上线。

这意味着沙盒化执行，这样它就不会破坏你的生产数据库。凭证隔离，这样提示注入就无法窃取你的API密钥。状态管理，这样断开连接就不会丢失一小时的工作成果。错误恢复。追踪。扩展。

至少需要三个月的基础设施工作。而且那是在你的第一个用户看到任何东西之前。

Claude托管代理于2026年4月9日进入公开测试版，消除了整个这一层。你定义代理。Anthropic运行它。本教程带你走完完整流程：构建一个竞品价格监控器，它在网络上研究真实产品，实时流式传输其工作过程，然后使用几乎还没有人谈论的内置评分系统测试其输出。

1、托管代理到底是什么

大多数关于托管代理的报道将其描述为"托管代理"。这准确但浅显。底层背后的架构洞察更有趣。

Anthropic的工程团队将代理分解为三个独立组件：大脑（Claude及其编排工具）、双手（代码运行和文件写入的沙盒化容器）和会话（发生一切的持久、仅追加日志）。每个组件都可以失败、重启或被替换，而不会干扰其他组件。

这是操作系统几十年前使用的相同模式。read()系统调用不在乎它是从1970年代的磁盘组还是现代SSD读取。抽象比硬件更长久。托管代理应用相同的原则：接口保持稳定，而实现（工具、沙盒、模型）在其下发展。

上图（来自Anthropic的工程博客）展示了这三个组件如何虚拟化在稳定接口背后。会话持久存储每个事件。工具运行代理循环并路由工具调用。沙盒在隔离中执行代码。每个都可以独立交换、重启或扩展。

关键的架构决策：大脑以相同方式调用双手，就像调用任何其他工具一样：execute(name, input) → string。如果容器死亡，工具将其捕获为工具调用错误并配置新容器。凭证永远不会到达沙盒。认证令牌存在于安全仓库中，并在代理级别注入，永远不会暴露给代理生成的代码。

对你来说作为开发者，这个架构坍缩为四个API原语：

代理是配置：哪个模型、遵循什么系统提示、哪些工具可用。创建一次，永远通过ID引用。
环境是容器模板：预安装的包、网络访问规则、挂载的文件。同样创建一次并重复使用。
会话是将代理与环境配对的运行实例。这是工作发生的地方。会话在断开连接时保持持久，可以运行数小时。
事件是通信通道。你发送用户消息进去。代理流式传输工具调用、文本和状态更新出来。事件日志是持久的，存在于大脑和双手之外。

2、我们要构建什么

你经营一家在线电子产品商店。你销售10种产品：AirPods、索尼耳机、戴森吸尘器、三星和Pixel手机、MacBook、LG电视、Bose耳机、任天堂Switch和Kindle。你的价格每季度设定一次。问题：你不知道现在是否有竞争力。亚马逊、百思买和沃尔玛每天调整价格。当你手动检查时，数据已经过时了。

我们要构建的代理解决了这个问题。你给它一个CSV格式的产品目录（名称、SKU、你的价格、类别）。它接收该目录，在网络上搜索三个竞争对手的当前价格，将它们与你的价格进行比较，标记每个你比最低竞争对手高出15%以上的产品，并编写一个结构化的markdown报告，包含摘要表格、每个产品的详细分析和定价建议。

以下是这成为托管代理特定测试的原因。它锻炼了完整工具集：网络搜索（3个零售商×10个产品=30次搜索）、文件操作（读取目录、编写报告）和bash（数据处理）。它运行时间足够长以展示会话持久性（6到8分钟的活跃工作）。而且输出结构足够好，可以用标准测试：它是否涵盖了全部10个产品？它是否标记了正确的产品？它是否包含收入影响估计？

输入看起来像这样：

product_name,sku,your_price,category
Apple AirPods Pro 2,APD-001,289.99,Audio
Sony WH-1000XM5,SNY-002,378.00,Audio
Dyson V15 Detect,DYS-003,749.99,Home
Samsung Galaxy S25 Ultra,SAM-004,1349.00,Mobile
...

输出是一个位于/mnt/session/outputs/price_report.md的markdown报告，包含比较表格、标记项目和可操作的建议。然后成果评分器根据你定义的标准对该报告进行评分。

六步到达那里。让我们从架构开始。

在深入研究之前有一个定位说明。Anthropic现在提供三种使用Claude构建的方式。Messages API给你原始模型访问权限，你自己构建代理循环。Agent SDK给你Claude Code作为库，内置工具。托管代理给你完整堆栈：Anthropic运行循环、沙盒、状态和错误恢复。本教程完全专注于托管代理。

让我们开始！

3、先决条件和设置

你需要三样东西：

来自Claude控制台的Anthropic API密钥
Python 3.10+
最新的Anthropic Python SDK

pip install anthropic

设置你的API密钥：

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

每个托管代理请求都需要managed-agents-2026-04-01测试版标头。当你使用测试版命名空间时，Python SDK会自动设置这个，所以你不需要手动管理它。

快速验证你的设置是否有效：

import anthropic

client = anthropic.Anthropic()
# 如果这运行没有错误，你就准备好了
print("SDK version:", anthropic.__version__)

4、创建你的代理

代理是可重用的配置对象。它定义三件事：哪个模型思考、遵循什么指令、哪些工具可以使用。创建代理时不会运行计算。它是一个蓝图。

这是我们的竞品价格监控器的代理：

agent = client.beta.managed_agents.agents.create(
    name="Price Monitor",
    model="claude-sonnet-4-6",
    system="""You are a competitive pricing analyst. Given a product
catalog CSV, research current prices for each product across
Amazon, Best Buy, and Walmart using web search.

For each product:
1. Search for the exact product name + retailer
2. Record the lowest price found at each retailer
3. Compare against the catalog price
4. Flag any product where the catalog price exceeds
the lowest competitor price by more than 15%

Output a markdown report to /mnt/session/outputs/price_report.md
with a summary table and detailed findings per product.""",
    tools=[{"type": "agent_toolset_20260401"}]
)

print(f"Agent ID: {agent.id}")

关于系统提示的两点值得注意。首先，输出路径/mnt/session/outputs/是代理编写稍后可以通过文件API检索的交付成果的地方。其次，指令在方法上非常具体（每个零售商搜索，15%阈值标记）。模糊的提示产生模糊的结果。你的指令越具体，你的代理就越可测试。当我们进入成果部分时这很重要。

保存agent.id。每次启动会话时你都会引用它。

5、配置环境

环境定义代理代码实际运行的容器。它与代理分开，因为同一个大脑可能需要不同的容器来完成不同的任务。一个数据分析代理可能需要一个预装pandas的环境和另一个使用R的环境。

对于我们的价格监控器，设置是最小的：

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

print(f"Environment ID: {environment.id}")

我们将网络设置为unrestricted，因为代理需要执行网络搜索以获取竞品价格。在一个更受限的场景中，你可以将网络访问限制到特定域名：

# 替代方案：限制到特定零售商
"networking": {
    "type": "restricted",
    "allowed_domains": [
        "amazon.com", "bestbuy.com", "walmart.com"
    ]
}

云容器预装了Python、Node.js和Go。如果你需要额外的包，你可以在环境配置中指定它们，或者让代理通过bash在会话期间安装它们。

像代理一样，环境是可重用的。创建一次，跨多个会话通过ID引用。

6、启动会话并发送工作

这是计算开始的地方。会话将你的代理与你的环境配对并开始计时。

首先，创建会话：

session = client.beta.managed_agents.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Price comparison run"
)

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

现在将产品目录作为用户消息发送。这是一个包含10种消费电子产品且"你的商店"价格略高的现实目录：

catalog = """product_name,sku,your_price,category
Apple AirPods Pro 2,APD-001,289.99,Audio
Sony WH-1000XM5,SNY-002,378.00,Audio
Dyson V15 Detect,DYS-003,749.99,Home
Samsung Galaxy S25 Ultra,SAM-004,1349.00,Mobile
Apple MacBook Air M4,APL-005,1249.00,Laptop
LG C4 65-inch OLED TV,LGC-006,1899.00,TV
Bose QuietComfort Ultra,BSE-007,429.99,Audio
Nintendo Switch 2,NIN-008,449.99,Gaming
Kindle Scribe 2,KDL-009,399.99,E-reader
Google Pixel 9 Pro,GPX-010,1099.00,Mobile"""

client.beta.managed_agents.sessions.events.create(
    session_id=session.id,
    events=[{
        "type": "user.message",
        "content": [{
            "type": "text",
            "text": f"""Here is my product catalog:

{catalog}

Research competitor prices for each product across
Amazon, Best Buy, and Walmart. Write the full analysis
report to /mnt/session/outputs/price_report.md"""
        }]
    }]
)

当你发送此事件时，会触发以下序列：

工具从你的环境配置配置容器
Claude读取你的消息并计划其方法
它在沙盒内执行工具（每个产品的网络搜索、用于编写文件的bash）
结果作为服务器发送事件流式传回
完成后，会话状态变为idle

代理自主决定工具序列。你不编排每个步骤。你陈述目标，代理弄清楚如何到达那里。

一个强大的功能：你可以在代理工作时发送额外的user.message事件。这让你在执行过程中进行引导。如果你看到代理在事件流中走上错误的路径，你可以纠正路线而无需重新启动会话。

7、实时流式传输事件

事件流是你观察代理大脑的窗口。每个工具调用、每段文本、每个状态变化都作为服务器发送事件到达。

以下是在Python中使用流的方法：

import json

stream = client.beta.managed_agents.sessions.events.stream(
    session_id=session.id
)

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🔧 [{event.name}]")

    elif event.type == "session.status_idle":
        print("\n\nAgent finished.")
        break

当你运行这个时，你会看到如下输出：

I'll research competitor prices for each product. Let me start
with the audio category.

🔧 [web_search]
🔧 [web_search]

For AirPods Pro 2, I found:
- Amazon: $249.00
- Best Buy: $249.99
- Walmart: $234.00

Your catalog price of $289.99 is 23.9% above the lowest
competitor price. This exceeds the 15% threshold.

🔧 [web_search]
...

🔧 [bash]

Agent finished.

三种事件类型最重要。agent.message携带Claude的文本输出（推理、发现、状态更新）。agent.tool_use在代理调用工具时触发（网络搜索、bash、文件写入）。session.status_idle表示代理已完成所有工作。

完整的事件历史也在服务器端持久化。你可以在事后获取它：

events = client.beta.managed_agents.sessions.events.list(
    session_id=session.id
)

这对调试、审计或重播代理的操作很有用。

8、检索输出

代理将其交付成果写入容器内的/mnt/session/outputs/。你通过文件API检索它们。

files = client.beta.managed_agents.files.list(
    scope_id=session.id
)

for f in files.data:
    print(f"{f.filename} ({f.size_bytes} bytes)")

content = client.beta.managed_agents.files.content(
    file_id=f.id
)

with open(f.filename, "wb") as out:
    out.write(content)

即使你对事件流的连接断开，输出文件也会持久化。这是会话作为持久日志架构的直接好处。当你的笔记本电脑进入睡眠状态时，代理的工作不会丢失。

此时，你有一个工作的竞品价格监控器。五个API调用（创建代理、创建环境、创建会话、发送事件、检索文件）和大约30行Python代码。

但这里有一个将演示与产品区分开的问题：你如何知道输出是好的？

9、测试它（没人谈论的部分）

运行代理一次并手动阅读报告对演示有效。当你每天在500个产品上运行它或为客户端部署它时，这就行不通了。

典型的答案是构建你自己的评估层：解析输出、编写断言、可能使用另一个LLM作为评判者。这是几周的工作。

托管代理有更好的内置功能。它叫做成果，处于研究预览阶段，是整个发布中最少被报道的功能。

9.1 成果如何工作

不是发送user.message，你发送user.define_outcome事件。它有三个部分：

描述：代理应该产生什么
标准：定义"好"是什么样子的markdown文档，逐条标准
最大迭代次数：评分器放弃前代理可以修改多少次

当你定义成果时，工具配置一个单独的评分器。这个评分器在其自己的上下文窗口中运行，完全独立于工作代理。它不会被代理的推理或实现选择影响。在代理完成草稿后，评分器根据标准评估输出并返回四个结果之一：

satisfied：所有标准都满足。会话进入空闲状态。
needs_revision：识别出具体差距。代理获得反馈并重试。
max_iterations_reached：尝试次数用完。
failed：标准根本与任务不匹配。

9.2 编写标准

标准是整个工作流中最重要的工件。它将"这看起来对吗？"转化为结构化的、可重复的质量关卡。

这是我们的价格监控器的标准：

rubric = """
# Competitive Price Report Rubric

## Coverage
- All 10 products from the catalog are included
- At least 2 out of 3 retailers have prices for each product
- Products are grouped by category

## Data Quality
- Each price includes the retailer name and source
- Prices are in USD with two decimal places
- The date of the price check is stated

## Analysis
- A summary table lists all products with your price,
lowest competitor price, and percentage difference
- Products exceeding the 15% threshold are clearly flagged
- At least 3 products should be flagged as overpriced
(given the inflated catalog prices)

## Recommendations
- Each flagged product includes a specific
recommended price adjustment
- The total potential revenue impact is estimated

## Format
- Output is valid markdown
- The summary table is properly formatted
- Report is under 2000 words
"""

每个标准都是评分器可以客观验证的东西。"数据质量"不是"价格准确吗？"（评分器无法检查）。而是"价格格式正确并归因于来源吗？"（评分器可以检查）。围绕可验证的结构和完整性编写标准，而不是评分器无法确认的事实准确性。

9.3 运行成果

# 为基于成果的运行创建新会话
session = client.beta.managed_agents.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Price monitor - graded run"
)

# 定义成果（代理立即开始工作）
client.beta.managed_agents.sessions.events.create(
    session_id=session.id,
    events=[{
        "type": "user.define_outcome",
        "description": f"""Analyze this product catalog and produce
a competitive pricing report:

{catalog}""",
        "rubric": {"type": "text", "content": rubric},
        "max_iterations": 3
    }]
)

现在流式传输事件并观察评估周期：

for event in stream:
    if event.type == "span.outcome_evaluation_start":
        print(f"\n📋 Grader evaluating (iteration {event.iteration})...")

    elif event.type == "span.outcome_evaluation_end":
        print(f"Result: {event.result}")
        print(f"Explanation: {event.explanation}")

        if event.result == "satisfied":
            print("✅ All criteria met.")
            break

典型的运行看起来像这样：

迭代0：代理产生第一稿。评分器发现建议部分缺少收入影响估计。结果：needs_revision。

迭代1：代理阅读评分器的反馈，添加收入影响计算。评分器发现所有标准都满足。结果：satisfied。

评分器的explanation字段给你每个标准的细分。你可以记录它、对其发出警报，或用它随时间改进你的标准。

9.4 以编程方式检查最终状态

对于自动化（CI管道、计划运行、监控），轮询会话：

session_status = client.beta.managed_agents.sessions.retrieve(
    session_id=session.id
)

for eval in session_status.outcome_evaluations:
    print(f"{eval.outcome_id}: {eval.result}")

这是自动化代理测试的基础。编写标准。运行成果。检查result == "satisfied"。这就是你的断言。

10、这花费多少

让我们为我们的价格监控器做数学计算。单次运行10个产品涉及大约：

输入令牌：~50,000（系统提示+目录+网络搜索结果+评分器上下文）
输出令牌：~15,000（代理推理+报告+评分器评估）
活跃运行时：~8分钟（网络搜索需要时间）
网络搜索：~30（3个零售商×10个产品）

使用Claude Sonnet 4.6定价：

通过提示缓存（工具自动应用），输入令牌成本进一步降低。缓存读取比全新输入便宜90%。

作为参考，自己运行这将需要一个容器编排平台、一个网络抓取服务、会话状态存储和监控。即使在AWS上最小设置，在处理单个产品之前，每月固定基础设施成本也要$50-100。

诚实的看法：每次运行$0.69对于你得到的东西来说是便宜的。需要关注的成本驱动因素是网络搜索量。如果你扩展到500个产品，每次仅搜索成本就是$15。

11、回顾和下一步

你构建的：一个竞品价格监控器，接收产品目录，在真实零售商网站上研究价格，并生成结构化的定价分析。五次API调用和约30行Python代码。

关键洞察：成果系统将代理测试从"运行它并阅读输出"转化为结构化的自动化质量关卡。评分器在架构上与工作代理隔离，使用自己的上下文窗口，并提供推动迭代改进的逐条标准反馈。

本周尝试：拿你自己的用例。为它编写标准。运行成果循环。看看评分器是否抓住了你手动会抓住的东西。那就是灵光乍现的时刻。

原文链接：Build, Stream, Test: Your First Claude Managed Agent in 30 Minutes

汇智网翻译整理，转载请标明出处