拆解 Anthropic 的 37 分钟 Agent 教程：从七个函数到一个事故调查助手

从事故问题开始

凌晨收到故障告警，最费时间的往往是把证据拼起来：哪个服务先变慢，刚刚部署了什么，一段看似普通的重构为什么拖垮数据库，日志里的其他错误是否只是干扰。

Anthropic 的《Ship your first Managed Agent》把这段工作做成了一个可以跟着完成的练习。它的价值在于：你能看见一个 Agent 怎样取得信息、执行分析、把过程呈现给人，并在刷新页面后保留工作记录。读完本文，你应当能够解释示例里的每个关键接口，复现它的教学流程，并判断哪些部分还不能直接用于生产。

先核对：这门课究竟教了什么

官方视频由 Claude 频道发布，上传日期为 2026 年 5 月 26 日，完整长度为 37 分 9 秒。讲师 Isabella He 在开场介绍自己来自 Anthropic Applied AI 团队。网上流传的约 37 分钟说法基本准确，但转帖里的“刚发布”和“自动化整个企业”扩大了时间新鲜度与教学范围。

课程做的是一个虚构电商系统的事故调查助手。它读取模拟日志、查询模拟指标和部署记录、检查代码差异，最后提出故障原因与处理建议。25:00 附近，讲师明确把修改代码、提出 PR 等能力放在可以继续扩展的方向；现场演示停在建议阶段。

产品发布也不是视频上传当天：Managed Agents 官方公告标注的是 2026 年 4 月 8 日。今天访问这篇公告，还会看到后来补充的新功能入口，因此不能把当前页面上的所有内容都当作发布当天或课堂上已经实现的能力。

本文逐段核对了视频自动字幕、官方文档和仓库代码，并在本地运行了模拟日志生成器。没有调用付费 Managed Agents API，因而下文会区分源码可以确认的行为、讲师演示的结果和建议补充的工程措施；不把它写成我们完成了云端实测的案例。

为什么这个教程值得学

一个好的入门案例需要有明确问题，也需要能验证答案。这个练习同时具备两点。

第一，数据之间可以互相验证。部署记录给出时间，指标显示影响，diff 解释机制，日志提供运行迹象。单独拿到任何一项，都不足以可靠地认定根因。

第二，界面与 Agent 使用同一套模拟数据。你可以在 Metrics、Logs、Deploys 页面检查它的说法，不必因为它生成了一段流畅的分析就相信它。

第三，课堂把工作拆成可观察的阶段：先让 Agent 获得身份，再配置执行环境，挂载文件，建立会话，接通事件与工具。每一步都能解释“现在多了什么能力”。

第四，完整答案就在仓库中。初学者可以逐步填写，熟悉接口的人可以直接比较空实现与参考实现，精力集中在运行链路上。

但学习成本被压缩，部分原因也在于提示词、工具定义、数据、UI 和历史恢复代码已经准备好了。README 所说的约 38 行，是练习中要补的核心逻辑，不是完整产品的总代码量。源码与练习说明

按时间回看：课程的完整路线

以下时间按 YouTube 完整版本整理，适合作为回看导航。自动字幕可能有术语识别误差，接口名称以代码为准。

理解架构：一次请求背后有四种对象

可以把 Agent 理解为一份可复用的工作配置：模型、系统提示词、工具和技能决定它能做什么。Environment 描述执行环境。Session 把配置、环境和本次输入连接起来，成为具体的一次任务。Events 则记录用户消息、工具请求、工具结果和会话状态。官方概念说明

这里存在两条不同的执行路径。日志上传到云端沙箱，由 Agent 调用内置工具分析；指标、部署与 diff 则由本地 Python 函数读取，再通过事件返回。云端模型没有因此直接取得你电脑的任意执行权限，它只能请求应用已经定义、并愿意处理的工具。

视频用“脑”和“手”解释推理循环与执行环境的分离。工程上的意义是，你可以分别考虑模型调度、容器生命周期、凭据和工具执行，不必把全部工作塞进同一个进程。讲师还介绍了内部延迟改善和开发提速数据；这些是她报告的经验，不构成本教程对你的应用速度或可靠性的保证。

托管的另一项价值是维护 Harness。视频以模型的上下文行为变化为例：某一代模型需要的提前停止缓解措施，在下一代模型上可能已经多余。平台替你承担一部分适配成本，业务团队仍需为自己的输入、工具与验收标准负责。

在这个例子里，关系可以写成：

用户在 Streamlit 中提出事故问题
             ↓ 用户消息事件
Anthropic 托管的 Agent 循环
    ├─ 沙箱内执行命令、筛选 app.log
    └─ 发出自定义工具请求
             ↓ 事件流
本地 Python 分发器 → 查询模拟指标、部署记录、diff
             ↓ 工具结果事件
Agent 继续调查 → 返回分析 → 会话进入空闲

七个函数，分别接通什么

视频描述栏写“六个函数”，当前仓库则明确列出七个，包括删除会话。下面以本次核查的完整参考代码为准，不把两个版本硬说成一致。参考实现

1. setup_agent：定义工作配置，并挂载团队知识

当前实现先上传 incident-triage-runbook Skill，再创建 Agent，指定模型、系统提示词、工具和 Skill 版本。Skill 标题带随机后缀，代码注释解释这是为了避免组织内重名。

这里有两个容易漏掉的区别。视频约 12:44 使用 Opus 4.7，而当前参考文件使用 claude-opus-4-8；当前代码还直接挂载了 runbook，而视频将 runbook 作为值得扩展的上下文能力讨论。复现时要记录仓库版本，不能假设 main 永远与录像一致。

2. setup_environment：配置工具工作的地方

参考实现创建 cloud 环境，并设置 networking.type = unrestricted。这方便课堂演示。连接真实数据时，应重新决定访问范围与工具权限。

视频还提到自带计算资源、自托管执行环境和 MCP tunnels，但本练习没有搭建这些路径。不要把“讲过可选能力”写成“示例已经覆盖部署”。

3. upload_log：让数据成为可检索文件

这个函数将 data/app.log 上传到 Files API。系统提示词要求 Agent 使用 grep 或 Python 分析大文件，不要整份读进上下文。

这是一项非常实用的设计：先按服务、时间和请求 ID 缩小范围，再把有意义的证据交给模型。代价也要看清——文件已经上传，不能因为指标工具在本地运行，就说整个方案的数据都留在本地。

4. start_session：把配置、环境和日志绑定为任务

创建 Session 时传入 Agent ID、Environment ID 和文件资源。代码中的 mount_path 是 app.log，系统提示词使用的完整读取路径是 /mnt/session/uploads/app.log。

路径约定是配置的一部分。上传成功与 Agent 实际能找到文件是两项检查；前者不会自动证明后者。

5. stream_reply：维持消息与工具结果的往返

参考实现先打开事件流，再发送 user.message。循环遇到 agent.custom_tool_use 时，在本地运行工具，然后发送 user.custom_tool_result，其中 custom_tool_use_id 对应原请求事件的 ID。

这个 ID 负责把答案交还给正确的工具请求。仅在本地打印结果没有用；Agent 必须从协议中收到结果才能继续。

此外，stream_reply 自身持续产出事件，正常回合结束时由 provided.py 的 UI 调用方识别 session.status_idle 且 stop_reason.type == end_turn 后退出消费。脱离这个 UI 单独复用函数时，需要自行处理结束条件。

6. handle_tool：让模型请求落到具体业务函数

三个工具分别读取服务指标、最近部署和某个提交的 diff。当前数据来自本地 JSON 与文本文件，没有实际连接 Datadog、PagerDuty 或 GitHub API。

这里可以迁移为真实客户端，但迁移工作包括参数校验、权限、查询范围、超时、限流与错误语义。例如当前 get_metrics 用真假值判断结果，推广到标量指标时要避免把合法的零误判为不存在；get_diff 用提交前七位是否出现在文本中判断匹配，也不适合作为真实仓库的精确查找接口。

7. delete_session：明确资源生命周期

函数调用 Session 删除接口。当前官方概览明确指出，上传的 Files 需要单独删除。按钮从列表移除一个会话，不等于它顺便清除了所有上传文件、Skill、Agent 和 Environment。

同样，参考代码使用 st.cache_resource 减少重复创建，但这是应用进程的缓存。生产应用需要持久保存资源 ID、定义版本更新和清理策略，不能把缓存注释中的“永久复用”理解为重启后还会自动找到同一套资源。

事故是怎样被定位的

样例用虚构的 checkout 服务制造了一次 N+1 查询问题。部署记录把 a3f9c21 的上线时间设在 2026 年 4 月 22 日 14:31:18 UTC。这里的 4 月 22 日是模拟事故日期，与产品发布和视频上传日期无关。

diff显示，原先一次查询多个订单的商品，再在内存中分组；重构后变成在订单循环内逐一查询商品。订单数量上升时，数据库访问次数随之增长。N+1 描述的是这种重复查询模式，具体总次数还取决于 ORM 的求值方式与周边操作。

实际读取样例指标可见，checkout 首个 p99 数据点为 62.448 ms，峰值为 3638.004 ms，错误率峰值为 21.9%。这些是模拟数据，不是 Agent 帮企业实现的性能指标。README 的 65 ms、3600 ms 和 20% 是近似描述。

本地生成器这次输出 69,740 行、14,875,565 字节日志，因此正文用“约 7 万行”最准确。生成器还插入了 auth 服务较早出现、随后自行恢复的错误，让调查不能只凭看到 ERROR 就下结论。生成器

数据也保留了教学简化：指标文件与日志生成器并非同一个真实监控管道。例如连接池指标在 14:37 达到 100%，日志生成器在 14:40 开始加入耗尽后的错误分支。它们支持同一条故障解释，但不适合当作逐秒一致的真实事故记录。

一份合格的调查结果应该把四类证据连起来：

Runbook 如何让调查更有方向

当前仓库的 Skill规定先查部署，再对照指标；找到时间相关的变更后先看 diff，再用日志确认。如果部署不相关，转查连接池和上游依赖。它还列出团队应关注的常见模式，并要求结尾写一句带根因标识的结论。

这类知识的价值是降低无目的搜索：工具决定能取得什么，runbook 帮助决定先查什么、凭什么结束。它适合沉淀团队约定，也应该允许证据不足时走其他分支。

不过，Markdown 中的操作顺序属于模型指引，不能充当授权系统。即使 Skill 写了沟通要求，也不会凭空给 Agent 增加消息工具；真实的回滚或通知权限，必须落实在应用与工具层。

演示中的等待和恢复，同样值得看

22:38 附近，讲师新开会话再次请求调查；约 24:17 得到结果。随后展示历史时，她还提到先前那个会话也返回了。这说明现场过程并非每一步都立即完成，但视频没有提供足够信息认定某次等待的具体原因。

应当学到的是保留 Session ID、查看事件、区分运行状态，而不是遇到等待就不断创建新会话。重复创建可能带来重复工作和费用。

另一个常被误读的点是“关掉电脑还能继续”。平台可以保存并运行服务端会话，但这个示例的自定义工具由本地 Python 处理。如果下一步需要本地工具结果，而处理进程已经停止，端到端流程就缺了执行者。持久会话解决了状态保存问题，工具服务是否在线仍要单独解决。

从事件流到可用界面，还有几处细节

provided.py 用不同状态框显示沙箱工具与本地工具，刷新时通过 sessions.list() 和 events.list() 恢复历史。这让用户可以检查过程，而不只是等待最终文本。

但当前示例只取最近 15 个会话、最多 500 条历史事件，没有实现完整分页；新建 Agent 后也会改变会话列表的筛选对象。页面没有展示旧记录，不足以证明云端记录已经丢失。

流式事件也不自动等于逐 token 文本输出。当前事件文档说明，默认 agent.message 是缓冲后发送的记录；增量文字预览需要选择启用。实际做 UI 时，预览应按事件 ID 归并，并以最终持久消息替换，避免重复展示。示例的逐事件展示能解释过程，不能据此承诺所有文字都会即时逐字出现。

最后几分钟介绍的能力，哪些还没接进去

视频后半段给出了扩展地图，而没有逐一完成实现。下表区分已经接入与仅作介绍的能力。

其中，保存同一个 Session 的历史并不等于跨 Session 学习偏好；写出一段结论也不等于经过 Outcomes 评分。发布时公告中的预览范围还可能与今天不同，实际接入应看当前文档和账号可用能力。

跟着复现：先验证最小闭环

需要 Python 3.10+、可用的 Anthropic API key，以及对应平台访问和计费条件。课程免费公开，运行云端模型会产生费用。下面使用当前官方仓库地址；README 还保留了旧组织地址。

git clone https://github.com/anthropics/cwc-workshops.git
cd cwc-workshops
# 固定本文核查的源码版本，便于对照；不代表最佳生产版本。
git checkout 068b84bb03d2ae87c51edb2837dda25c84c1d686
cd ship-your-first-managed-agent
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cp .env.example .env
# 在本地编辑 .env，填写 ANTHROPIC_API_KEY。
python data/generate_log.py
streamlit run app.py

复现后的验收与排错

Windows 的虚拟环境激活命令随终端不同而变化；PowerShell 可使用 .venv\Scripts\Activate.ps1。运行时保持工作目录位于练习目录，因为代码有相对路径。

首次打开应能查看面板，而 Agent 区域提示尚未实现 setup_agent()。逐一参考 agent_complete.py 填写 agent.py；资源 ID 出现后，点加号创建 Session，再询问 checkout 在 14:32 UTC 左右变慢的原因。

仓库还有 e2e.py，但它直接创建并调用云端资源，会产生费用。它的 PASS 条件主要检查回答是否包含 N+1 与提交号，适合冒烟验证，不能证明完整证据链正确。它也没有在结尾实现全面资源清理；600 秒判断位于收到事件后的循环中，不是可靠的外部硬超时。E2E 源码

README 还明确标注这是不再维护、也不接受贡献的 workshop sample，因此适合作为学习材料，不应当作持续维护的生产模板。依赖使用最低版本约束而非完整锁定，所以固定仓库 SHA 也不等于锁定整个运行环境。出现问题时先保存实际 SDK 版本、Session ID 和事件类型，再对照官方 Quickstart，不要通过盲目换模型或删除状态来掩盖问题。

建议按以下顺序验收：

• 文件生成成功，Agent 配置、环境和 Session 创建成功。
• 日志确实挂载，工具请求能收到对应结果，没有停在等待回调。
• 结论指出 a3f9c21 与 N+1 查询，并给出部署、指标、diff 和日志依据。
• 能解释 auth 早期错误为何不是本次 checkout 故障的充分解释。
• 刷新后仍能找到相同 Session，并可继续追问。
• 测试结束后按资源类别清理，检查用量。

从课堂到生产，优先补这六件事

以下是基于源码的工程建议，超出了视频中的已完成实现。

把工具处理器部署为可靠服务。 为重复事件、断线恢复、执行超时与失败返回制定协议。涉及写操作时，工具请求 ID 还需要与业务侧幂等策略配合。

定义清晰的输入输出。 约束服务名、时间窗口、提交标识与结果大小。查询不到与工具失败必须能区分；证据缺失时允许输出“目前无法判断”。

把诊断与变更分开授权。 第一阶段只读调查；需要回滚、改配置或提 PR 时，再增加相应工具和审核过程。模型在文本里提出建议，不代表已经执行，也不代表变更已经恢复服务。

做多案例评估。 加入无部署故障、多个相邻部署、缺失日志、工具超时和干扰证据，检查误判、漏判、成本与耗时。单一已知答案的模拟事故不足以估计真实可靠性。

管理数据与版本。 固定可复现的 Agent、Skill 和依赖版本，持久保存资源映射，定义数据上传与保留范围。当前示例使用 Skill 的 latest，会给复现带来额外变化。

设置成本与运行边界。 截至本次核查，官方价格包括模型 token 费用，以及活跃 Session 每小时 0.08 美元的运行费。费用不能只按“8 美分一小时”估算；仍应核对所用模型和其他工具收费。官方价格说明

这门课真正留下了什么

它给出了一个清楚、可拆解的工作单元：明确的故障问题，能取得证据的工具，受约束的运行环境，可恢复的过程，以及可以被人检查的结论。

对于正在做 Agent 产品的团队，最值得带走的是这套拆分方式。先让一个边界清楚的任务可靠完成，再决定如何接入更多数据、增加动作权限、引入并行任务。是否选择托管平台，则取决于执行位置、服务可用性、成本与控制需求。

这也是它适合作为入门教程的原因：你不仅能看到 Agent 给出答案，还能沿着源码说明这个答案是怎样产生的，以及下一步应该验证什么。