构建有效的代理
在过去一年里,我们与数十个跨行业的团队合作构建大语言模型(LLM)代理。最成功的实现方案往往不是使用复杂框架或专门的库,而是基于简单、可组合的模式构建。
在本文中,我们分享从客户合作和自主构建代理中学到的经验,并为开发者提供构建有效代理的实用建议。
什么是代理?
"代理"可以用多种方式定义。一些客户将代理定义为长期独立运行的完全自主系统,使用各种工具完成复杂任务。另一些人则用这个词描述遵循预定义工作流的更规范化实现。在 Anthropic,我们将所有这些变体归类为代理系统,但在工作流和代理之间做出重要的架构区分:
- 工作流是通过预定义代码路径编排 LLM 和工具的系统。
- 代理则是 LLM 动态指导自身流程和工具使用的系统,对如何完成任务保持控制。
下文我们将详细探讨这两种类型的代理系统。在附录 1("实践中的代理")中,我们描述了客户发现这些系统特别有价值的两个领域。
何时使用(何时不使用)代理
在使用 LLM 构建应用时,我们建议寻找尽可能简单的解决方案,仅在必要时增加复杂度。这可能意味着根本不需要构建代理系统。代理系统通常以延迟和成本换取更好的任务性能,你应该考虑这种权衡何时合理。
当确实需要更复杂的方案时,工作流为定义明确的任务提供可预测性和一致性,而代理则是在需要大规模灵活性和模型驱动决策时的更好选择。然而,对于许多应用而言,通过检索和上下文示例优化单次 LLM 调用通常就足够了。
何时以及如何使用框架
许多框架可以简化代理系统的实现,包括:
- Claude Agent SDK;
- AWS 的 Strands Agents SDK;
- Rivet,一个拖放式 GUI LLM 工作流构建器;以及
- Vellum,另一个用于构建和测试复杂工作流的 GUI 工具。
这些框架通过简化调用 LLM、定义和解析工具、链接调用等标准低级任务,使入门变得容易。然而,它们通常会增加额外的抽象层,掩盖底层的提示和响应,使其更难调试。它们还可能在简单设置就足够的情况下,诱使人们增加复杂度。
我们建议开发者先直接使用 LLM API:许多模式只需几行代码就能实现。如果你确实使用框架,请确保理解底层代码。对底层实现的错误假设是客户错误的常见来源。
请参阅我们的实战示例了解一些示例实现。
构建模块、工作流和代理
在本节中,我们将探讨我们在生产中看到的代理系统的常见模式。我们从基础构建模块——增强型 LLM——开始,逐步增加复杂度,从简单的组合工作流到自主代理。
构建模块:增强型 LLM
代理系统的基本构建模块是通过检索、工具和内存等增强功能增强的 LLM。我们当前的模型可以主动使用这些能力——生成自己的搜索查询、选择合适的工具、确定保留哪些信息。
我们建议关注实现的两个关键方面:根据特定用例定制这些能力,并确保它们为 LLM 提供简单、文档完善的接口。虽然实现这些增强功能有多种方式,一种方法是通过我们最近发布的模型上下文协议,它允许开发者通过简单的客户端实现与不断增长的第三方工具生态系统集成。
在本文的其余部分,我们假设每次 LLM 调用都可以访问这些增强功能。
工作流:提示链
提示链将任务分解为一系列步骤,每次 LLM 调用处理前一次的输出。你可以在任何中间步骤添加程序化检查(见下图中的"gate"),以确保流程仍在正轨上。
**何时使用此工作流:**此工作流非常适合可以将任务轻松、清晰地分解为固定子任务的情况。主要目标是通过让每次 LLM 调用成为更简单的任务,以延迟换取更高的准确性。
提示链有用的示例:
- 生成营销文案,然后将其翻译成另一种语言。
- 编写文档大纲,检查大纲是否满足某些标准,然后根据大纲编写文档。
工作流:路由
路由对输入进行分类并将其定向到专门的后续任务。此工作流允许分离关注点并构建更专业的提示。如果没有此工作流,优化一种类型的输入可能会损害其他输入的性能。
**何时使用此工作流:**路由适用于复杂任务,其中有明显的类别需要分别处理,且分类可以准确处理(无论是通过 LLM 还是更传统的分类模型/算法)。
路由有用的示例:
- 将不同类型的客户服务查询(一般问题、退款请求、技术支持)定向到不同的下游流程、提示和工具。
- 将简单/常见问题路由到更小、更经济高效的模型(如 Claude Haiku 4.5),将困难/不寻常的问题路由到更强大的模型(如 Claude Sonnet 4.5),以优化最佳性能。
工作流:并行化
LLM 有时可以同时处理任务并以编程方式聚合其输出。此工作流(并行化)表现为两种关键变体:
- **分区:**将任务分解为并行运行的独立子任务。
- **投票:**多次运行相同任务以获得多样化输出。
**何时使用此工作流:**当分割的子任务可以并行化以提高速度,或需要多个视角或尝试以获得更高置信度的结果时,并行化是有效的。对于有多个考虑因素的复杂任务,当每个考虑因素由单独的 LLM 调用处理时,LLM 通常表现更好,从而可以对每个特定方面进行专注处理。
并行化有用的示例:
分区:
- 实现防护措施,其中一个模型实例处理用户查询,而另一个实例筛选不当内容或请求。这通常比让同一个 LLM 调用同时处理防护措施和核心响应效果更好。
- 自动化评估 LLM 性能,每次 LLM 调用评估模型在给定提示下不同方面的性能。
投票:
- 审查代码漏洞,几个不同的提示审查代码,如果发现问题则标记。
- 评估给定内容是否不当,多个提示评估不同方面或要求不同的投票阈值以平衡误报和漏报。
工作流:编排者-工作者
在编排者-工作者工作流中,中央 LLM 动态分解任务,将其委派给工作者 LLM,并综合它们的结果。
**何时使用此工作流:**此工作流非常适合无法预测所需子任务的复杂任务(例如在编码中,需要更改的文件数量和每个文件中更改的性质可能取决于任务)。虽然它在拓扑结构上与并行化相似,但关键区别在于其灵活性——子任务不是预定义的,而是由编排者根据特定输入确定。
编排者-工作者有用的示例:
- 每次对多个文件进行复杂更改的编码产品。
- 涉及从多个来源收集和分析信息以查找可能相关信息的搜索任务。
工作流:评估器-优化器
在评估器-优化器工作流中,一次 LLM 调用生成响应,而另一次在循环中提供评估和反馈。
**何时使用此工作流:**当我们有明确的评估标准,且迭代优化提供可衡量的价值时,此工作流特别有效。两个适合的标志是:首先,当人类表达反馈时,LLM 响应可以得到明显改善;其次,LLM 可以提供此类反馈。这类似于人类作家在制作精炼文档时可能经历的迭代写作过程。
评估器-优化器有用的示例:
- 文学翻译,其中翻译 LLM 可能无法最初捕捉到细微差别,但评估器 LLM 可以提供有用的批评。
- 复杂的搜索任务,需要多轮搜索和分析以收集全面信息,评估器决定是否需要进一步搜索。
代理
随着 LLM 在关键能力上日趋成熟——理解复杂输入、参与推理和规划、可靠使用工具以及从错误中恢复——代理正在生产中涌现。代理从人类用户的命令或交互式讨论开始工作。一旦任务明确,代理会独立规划和操作,可能返回人类寻求进一步信息或判断。在执行过程中,代理在每一步从环境获取"真实信息"(如工具调用结果或代码执行)以评估其进展至关重要。代理然后可以在检查点或遇到阻碍时暂停以获取人类反馈。任务通常在完成时终止,但也常见包含停止条件(如最大迭代次数)以保持控制。
代理可以处理复杂任务,但其实现通常很简单。它们通常只是 LLM 在循环中基于环境反馈使用工具。因此,清晰而周到地设计工具集及其文档至关重要。我们在附录 2("提示工程你的工具")中扩展了工具开发的最佳实践。
**何时使用代理:**代理可用于开放式问题,其中难以或无法预测所需步骤数,且无法硬编码固定路径。LLM 可能会运行多轮,你必须对其决策有一定信任。代理的自主性使其非常适合在可信环境中扩展任务。
代理的自主性意味着更高的成本和累积错误的潜在可能。我们建议在沙盒环境中进行大量测试,并配合适当的防护措施。
代理有用的示例:
以下示例来自我们自己的实现:
- 用于解决 SWE-bench 任务的编码代理,涉及根据任务描述对多个文件进行编辑;
- 我们的"计算机使用"参考实现,其中 Claude 使用计算机完成任务。
组合和自定义这些模式
这些构建模块不是规范性的。它们是开发者可以塑造和组合以适应不同用例的常见模式。与任何 LLM 功能一样,成功的关键是衡量性能并迭代实现。重申一遍:你仅应在复杂度能明显改善结果时才考虑添加。
总结
在 LLM 领域的成功不在于构建最复杂的系统。而在于为你的需求构建正确的系统。从简单的提示开始,通过全面评估进行优化,仅在更简单的解决方案不足时才添加多步代理系统。
在实现代理时,我们尝试遵循三个核心原则:
- 在代理设计中保持简单性。
- 通过显式显示代理的规划步骤来优先考虑透明性。
- 通过彻底的工具文档和测试精心设计代理-计算机接口(ACI)。
框架可以帮助你快速入门,但在转向生产时不要犹豫减少抽象层并使用基本组件构建。通过遵循这些原则,你可以创建不仅强大而且可靠、可维护且受用户信任的代理。
致谢
由 Erik Schluntz 和 Barry Zhang 撰写。这项工作基于我们在 Anthropic 构建代理的经验以及客户分享的宝贵见解,对此我们深表感谢。
附录 1:实践中的代理
我们与客户的合作揭示了 AI 代理的两个特别有前途的应用,展示了上述模式的实用价值。这两个应用都说明了代理如何在需要对话和行动、有明确成功标准、支持反馈循环以及集成有意义的人类监督的任务中增加最大价值。
A. 客户支持
客户支持将熟悉的聊天机器人界面与通过工具集成增强的功能相结合。这非常适合更开放的代理,因为:
- 支持交互自然遵循对话流程,同时需要访问外部信息和操作;
- 可以集成工具以提取客户数据、订单历史和知识库文章;
- 退款或更新工单等操作可以通过编程方式处理;以及
- 成功可以通过用户定义的解决方案明确衡量。
几家公司通过基于使用量的定价模式(仅在成功解决时收费)展示了这种方法的可行性,显示出对其代理效果的信心。
B. 编码代理
软件开发领域显示了 LLM 功能的巨大潜力,能力从代码补全发展到自主问题解决。代理特别有效,因为:
- 代码解决方案可以通过自动化测试验证;
- 代理可以使用测试结果作为反馈迭代解决方案;
- 问题空间定义明确且结构化;以及
- 输出质量可以客观衡量。
在我们自己的实现中,代理现在可以仅根据拉取请求描述解决 SWE-bench Verified 基准测试中的真实 GitHub 问题。然而,虽然自动化测试有助于验证功能,但人工审查对于确保解决方案符合更广泛的系统要求仍然至关重要。
附录 2:提示工程你的工具
无论你构建哪种代理系统,工具都可能是代理的重要组成部分。工具使 Claude 能够通过在我们 API 中指定其确切结构和定义与外部服务和 API 交互。当 Claude 响应时,如果计划调用工具,它将在 API 响应中包含工具使用块。工具定义和规范应该与你的整体提示一样受到提示工程的关注。在这个简短的附录中,我们描述如何提示工程你的工具。
通常有几种方式可以指定相同的操作。例如,你可以通过编写 diff 或重写整个文件来指定文件编辑。对于结构化输出,你可以在 markdown 内或在 JSON 内返回代码。在软件工程中,像这样的差异是表面的,可以无损地相互转换。然而,某些格式对 LLM 来说比其他格式更难编写。编写 diff 需要在编写新代码之前知道块标题中更改了多少行。在 JSON 内编写代码(与 markdown 相比)需要额外的换行符和引号转义。
我们关于决定工具格式的建议如下:
- 给模型足够的 token 在它陷入困境之前"思考"。
- 使格式接近模型在互联网文本中自然看到的形式。
- 确保没有格式"开销",例如需要准确计算数千行代码,或对它编写的任何代码进行字符串转义。
一个经验法则是思考在人机接口(HCI)上投入多少努力,并计划投入同样的努力来创建良好的代理-计算机接口(ACI)。以下是如何这样做的一些想法:
- 设身处地为模型着想。根据描述和参数,如何使用此工具是显而易见的,还是需要仔细思考?如果是这样,那么对模型来说可能也是如此。好的工具定义通常包括示例用法、边缘情况、输入格式要求以及与其他工具的清晰边界。
- 如何更改参数名称或描述使事情更明显?把这想象为为团队中的初级开发人员编写优秀的文档字符串。这在使用许多类似工具时尤为重要。
- 测试模型如何使用你的工具:在我们的工作台中运行许多示例输入,查看模型犯什么错误,并迭代。
- 防错设计你的工具。更改参数以使其更难犯错。
在为 SWE-bench 构建代理时,我们实际上花在优化工具上的时间比整体提示更多。例如,我们发现当代理移出根目录后,模型会在使用相对文件路径的工具上犯错。为了解决这个问题,我们将工具更改为始终需要绝对文件路径——我们发现模型完美地使用了这种方法。