用 Claude Managed Agents 构建故障调查智能体

我是 Anthropic 应用 AI 团队的 Isabella He。我们与产品、研究团队和客户合作：对内参与 Claude Code 及其智能体框架等工具，对外帮助开发者基于它们构建应用。今天的目标是构建一个故障调查智能体，同时了解 Claude Managed Agents 的底层运行方式。

我们先介绍框架架构，再花大部分时间在仓库中构建站点可靠性工程智能体，最后看看基础功能之外的内容。后续课程会介绍 dreaming 和记忆，它们可以帮助智能体随时间改进。

Claude 的 Messages API 于 2023 年推出，为开发者提供了通过程序访问模型输入和输出的方式。构建者必须自行实现智能体循环、上下文管理和压缩等周边功能。随着模型获得工具使用能力并能执行更长的任务，这些部分也变得更加复杂。

Agent SDK 通过框架提供了 Claude Code 的计算机和文件系统能力，但开发者仍须在容器中托管、扩展并安全运行它。Claude Managed Agents 在框架周围增加了托管基础设施，包括沙箱、可观测性和工具运行时。开发者可以专注于任务配置和领域专用工具。

框架也必须随模型演进。我们发现 Sonnet 4.5 有时会在上下文窗口仍有空间时提前结束，我们称之为上下文焦虑，并为此增加缓解措施。当 Opus 4.5 不再表现出这种行为时，那部分工作便不再需要。Managed Agents 旨在随着模型变化，持续更新上下文处理和缓存等部分。

三个资源构成核心。智能体定义规定角色和能力：模型、系统提示词、工具、MCP 服务器和技能。环境是智能体执行操作的地方，包括容器和网络配置。会话将智能体实例与环境绑定，并提供可以流式输出事件的交互。

智能体循环在服务端运行。如果用户合上电脑或刷新应用，会话仍会保留，不依赖浏览器一直打开。这样，开发者构建的应用就不必自行承担部分托管、扩展和持久化工作。

一个关键设计选择是把智能体循环这个“大脑”与工具执行这个“双手”分开。较早的设计通常把两者放在每个会话的同一个容器中。分离之后，可以对执行和凭据设置更明确的隔离，并在需要时配置工具容器。

这种分离也会影响延迟。循环与执行耦合时，每个会话都必须先启动容器才能继续工作。我们的团队观察到，分离后首 token 时间的第 95 百分位降低了 90% 以上。这种设计还让工具容器发生故障时，循环仍可独立存活。

工作坊中，请克隆提供的仓库并打开 `ship-your-first-managed-agent` 目录。配置 Python 环境、安装依赖、设置 API 密钥并运行 Streamlit 应用。仓库包含说明和完成版参考文件，即使没有在课程期间完成配置，也可以跟着演示操作。

应用模拟了一次故障，这是值班工程师半夜被叫醒时常见的场景。人通常会检查指标、日志和近期部署以了解故障。我们将让智能体访问同类信息，并请它开展调查。

在代码中，我们会把完成版参考代码的部分内容复制到尚未完成的 `agent.py`，以了解各组件如何组合。首先是智能体定义：此示例使用 Claude Opus 4.7、系统提示词和一组工具。创建后会得到一个智能体标识符。

示例提示词很简单：它要求站点可靠性工程智能体调试故障，并提供获取指标、近期部署和代码差异的工具。这些也是开发者调查问题时可能使用的资源。其他应用可以使用更详细或限制更严格的提示词。

接下来配置执行环境。Anthropic 刚刚推出自带容器和计算资源的选项，因此工具既可以在自己的基础设施上执行，也可以在托管基础设施上执行。本次演示使用 Anthropic 云环境和不受限制的网络；也可以通过网络配置，将智能体限制为只访问允许列表中的主机。

私有 MCP 隧道提供了另一种方式：让工具服务器运行在私有环境中，而不是公共网络上。创建环境后，我们分别获得环境和智能体的标识符。接着通过 Files API 上传故障日志，让智能体检查数据并对其运行代码。

提供给智能体的信息会影响它能做什么。开发者仍要选择和管理上下文：上传哪些文件、智能体应如何处理文件，以及还需要什么信息。尽管周边基础设施由平台托管，这些选择仍可以配置。

会话绑定智能体标识符和环境标识符，并挂载上传的日志。它为智能体与用户交互提供场所。随后我们实现流式输出，让界面在会话运行期间显示进度。

托管智能体会话以事件为单位工作，而不只是接收请求再返回最终答案。事件包括用户消息、智能体回复和工具调用。它们可以被记录以供观察，也可以实时输出给用户，让人们看到工作过程，而不必等整个任务完成。

此时智能体可以回复问候，但还无法获取我们需要的指标：本地工具处理函数尚未连接。智能体定义位于服务端，而缺少的执行代码负责告诉应用，在智能体调用工具时应做什么。

加入处理函数后，智能体便可以调用 `get_metrics`、`get_recent_deploys` 和 `get_diff`。我们还增加会话删除功能，让开发者主动管理会话及其保留的数据。现在应用具备了测试运行所需的各个部分。

我启动一个会话，让智能体调试故障。它使用沙箱检查日志，调用近期部署工具并获取指标；界面实时显示这些操作。模拟信号显示，结账流程的 p99 延迟约为基线的十倍。

真正的故障处理智能体需要仔细选择工具和上下文。例如，可以给它一项读取运行手册的技能：这些文档记录团队过去如何诊断故障。过往事后复盘和运行手册为智能体提供人类调查人员也会使用的操作背景。

第一次现场运行需要再试一次，于是我启动新会话。工作坊工具从本地 JSON 文件读取示例数据。采用同样的方法，也可以连接 Datadog 等生产指标系统，并让工具在选定的容器和基础设施中执行。

重试后，智能体给出诊断：订单摘要构建器的一次修改引入了一个查询，似乎导致数据库连接池耗尽。智能体展示使用的指标、排除其他原因并建议应对措施。会话日志和可观测性控制台中都可以查看其工具调用。

本次演示止于提出建议。更完善的故障处理工作流可以把智能体连接到编码工具，让它提出修复并创建拉取请求。这将把工作从初步调查扩展到处理根本原因，同时由人监督相关操作。

我刷新应用后，会话仍然存在，因为其状态保留在服务端。可以发送另一条消息来恢复之前的会话，也可以使用删除功能将会话从列表中移除。工作进行时，界面还会显示会话处于运行还是空闲状态。

回顾构建过程：我们定义了智能体、环境和所需数据；在会话中将它们结合；实时输出回复和工具调用；实现本地处理函数；并增加会话删除功能。随着调查智能体逐步完成，Streamlit 界面让每个部分都变得可见。

在界面之下，事件会追加到会话日志中，而不是仅被视为一次请求和响应。这份记录有助于可观测性和会话恢复。由于工具执行与智能体循环分开，容器发生故障后可以重新启动，而无需重启整个循环。

在本次工作坊中，本地工具读取我们笔记本电脑上的文件，智能体循环则运行在 Anthropic 的托管基础设施中。如果客户自带计算资源或容器，开发者可以选择工具的执行位置。读取本地 JSON 的工具可以替换为生产服务的客户端，同时沿用相同协议。

会话也有不同状态：空闲、运行中、需要重试时的重新调度，以及遇到无法恢复的故障后的终止。可以利用事件围绕这些状态触发操作。例如，Webhook 可以让智能体恢复会话，或响应外部事件开始工作。

基础智能体已经使用托管机制处理压缩、缓存和工具调用等工作。其他功能包括拥有独立上下文窗口的子智能体、记忆、结果评估和技能。负责协调的智能体可以将任务委派给子智能体，并汇总它们的贡献，包括并行执行的工作。

记忆和 dreaming 旨在跨会话保留相关偏好和纠正信息。结果评估功能让开发者定义结果的评估标准，使智能体能够选择工具调用来追求该结果，而不只是执行固定的操作序列。

密钥库通过将加密存储与智能体可以访问的内容分开来管理凭据，并提供按用户和会话控制的权限。其他功能包括 Webhook、权限策略、MCP 服务器控制以及开发者控制台中的智能体构建器。欢迎查看文档和后续课程了解细节。