Simon Wong 的非线性漫游
Agent

精读 OpenAI 指南：构建 Agent 的最佳实践

发布于 2025年4月21日

引言

大型语言模型（LLM）现在越来越擅长处理复杂、多步骤的任务了。 因为 LLM 在推理、多模态能力和工具使用上的进步，诞生了一类新的由 LLM 驱动的系统，叫做 Agents。 这份指南是写给那些想尝试构建第一个 Agent 的产品和工程团队看的。 里面总结了很多实际部署经验，提供了识别应用场景的框架、设计 Agent 逻辑和编排的清晰模式，以及保证 Agent 安全、可预测、有效运行的最佳实践。 读完这份指南，你将拥有开始构建第一个 Agent 所需的基础知识。

什么是 Agent？

Agent 是能够独立地代表你完成任务的系统。这和传统软件帮你简化工作流不一样，Agent 是自己帮你干。 一个工作流（workflow）指的是为了达到用户目标必须执行的一系列步骤。 那些集成了 LLM 但不用 LLM 来控制工作流执行的应用（比如简单的聊天机器人、单轮 LLM 调用或情感分类器）不是 Agents。

一个真正的 Agent 有两个核心特征：

  1. 它利用 LLM 来管理工作流的执行和做决策。它知道什么时候任务完成了，需要的话还能主动纠正自己的行为。如果失败了，它能停下来把控制权交还给用户。
  2. 它能访问各种工具（Tools）来和外部系统互动（比如获取信息或执行操作），并且能根据工作流当前的状态动态选择合适的工具，同时始终在明确设定的“护栏”（guardrails）内运行。

你什么时候应该构建一个 Agent？

构建 Agent 需要我们重新思考系统如何做决策和处理复杂性。 Agent 特别适合用在那些传统的、确定性的、基于规则的自动化方法搞不定的工作流上。 在评估哪里可以用 Agent 时，应该优先考虑那些以前自动化尝试效果不好，特别是传统方法遇到以下困难的工作流：

  1. 复杂的决策制定 (Complex decision-making)：比如需要细微判断、处理例外情况、或者依赖上下文做决策的场景（例如客服流程里的退款审批）。
  2. 难以维护的规则 (Difficult-to-maintain rules)：系统因为规则集太庞大复杂而变得笨重，更新起来成本高还容易出错（例如执行供应商安全审查）。
  3. 严重依赖非结构化数据 (Heavy reliance on unstructured data)：需要理解自然语言、从文档里提取信息、或者和用户进行对话式交互的场景（例如处理一份房屋保险索赔）。

在你决定要构建一个 Agent 之前，一定要确认你的应用场景确实符合这些标准。不然的话，可能一个更简单的确定性解决方案就足够了。

Agent 设计基础

Agent 最基础的形态包含三个核心部分：

  1. 模型 (Model)：驱动 Agent 进行推理和决策的 LLM。
  2. 工具 (Tools)：Agent 可以用来执行动作的外部功能或 API。
  3. 指令 (Instructions)：明确的指导方针和护栏，用来定义 Agent 的行为方式。

选择你的模型

不同的模型在处理任务的复杂性、延迟和成本方面有各自的优缺点。在一个工作流里，可能需要根据不同任务使用不同的模型组合。不是所有任务都需要最聪明的模型。

一个比较好的做法是：

  1. 先用能力最强的模型构建 Agent 原型，以此建立一个性能基线。
  2. 然后，尝试换用更小、更快的模型，看它们是否仍然能达到可接受的效果。

选择模型的简单原则：

  • 建立评估（evals）来确定性能基线。
  • 用最好的可用模型来达到你的准确度目标。
  • 在可能的情况下，用较小的模型替换较大的模型，来优化成本和延迟。

定义工具

工具（Tools）通过调用底层应用或系统的 API 来扩展 Agent 的能力。对于没有 API 的老旧系统，Agent 可以像人一样通过操作 Web 或应用的用户界面 (UI) 来交互。 每个工具都应该有一个标准化的定义，文档要清晰，经过充分测试，并且是可重用的。 Agent 通常需要三种类型的工具：

数据 (Data)：让 Agent 能获取执行工作流所需的上下文和信息（例如查询数据库、读 PDF、搜索网页）。 行动 (Action)：让 Agent 能与系统交互并采取行动（例如发邮件、更新 CRM 记录、将工单转给人工客服）。 编排 (Orchestration)：Agent 本身也可以作为其他 Agent 的工具（参考后面“编排”部分的“管理者模式”）。

配置指令

高质量的指令对于任何基于 LLM 的应用都很重要，但对 Agent 来说尤其关键。清晰的指令能减少模糊性，改善 Agent 的决策能力，让工作流执行更顺畅，减少错误。 配置指令的最佳实践：

  1. 利用现有文档 (Use existing documents)：用已有的操作流程、客服脚本或政策文件来创建适合 LLM 理解的指令。
  2. 提示 Agent 分解任务 (Prompt agents to break down tasks)：把复杂冗长的内容拆分成更小、更清晰的步骤，帮助模型更好地理解和遵循。
  3. 定义清晰的行动 (Define clear actions)：确保指令中的每一步都对应一个具体的动作或输出。明确说明动作（甚至是用词）可以减少误解的空间。
  4. 覆盖边缘情况 (Capture edge cases)：现实世界的交互常常有意外。指令要能预见到常见变化，并包含处理这些情况的说明（例如用户提供信息不全怎么办）。可以使用像 o1 或 o3-mini 这样的高级模型，从现有文档自动生成指令。

编排

有了基础组件后，就可以考虑用编排模式来让 Agent 有效地执行工作流了。通常，采用增量方法比一开始就构建复杂系统更容易成功。

编排模式主要分两类：

  1. 单 Agent 系统 (Single-agent systems)：一个 Agent 配备了所需的工具和指令，在一个循环（loop）里执行工作流。
  2. 多 Agent 系统 (Multi-agent systems)：工作流的执行分布在多个相互协调的 Agent 之间。

单 Agent 系统

通过不断给单个 Agent 增加工具，可以处理很多任务，同时保持复杂性可控，简化评估和维护。 Agent 的运行通常是一个循环（run loop），直到达到某个退出条件为止，比如调用了表示最终输出的工具、模型直接回复用户（没有调用工具）、发生错误或达到最大交互轮次。 可以用提示词模板 (prompt templates) 加变量的方式来管理复杂性，而不是为每个场景维护单独的提示。

何时考虑创建多个 Agent

一般建议是先尽量发挥单个 Agent 的能力。 但在以下情况，你可能需要把任务拆分给多个 Agent：

  1. 复杂逻辑 (Complex logic)：当提示中包含大量条件分支（if-then-else），并且提示模板变得难以扩展时。
  2. 工具过载 (Tool overload)：问题不只在于工具数量，更在于它们的相似性或重叠。如果 Agent 难以区分和选择功能相似的工具（即使数量不多，比如少于10个但很相似），或者工具数量确实很多（比如超过15个定义清晰的工具也可能出问题），可以考虑拆分。

多 Agent 系统

多 Agent 系统可以看作一个图（graph），其中 Agent 是节点（nodes）。有两种常见的模式：

  1. 管理者模式 (Manager pattern - agents as tools)： 有一个中心的“管理者”（manager）Agent，它通过工具调用（tool calls）来协调多个专门的 Agent。 每个专门 Agent 处理特定的任务或领域。 管理者 Agent 负责理解用户需求，并将任务分配给合适的专业 Agent，最后整合结果。 这种模式适合只需要一个 Agent 来控制流程并与用户交互的场景。 例如： 一个翻译 Agent 作为管理者，根据用户需要调用的西班牙语翻译 Agent 工具、法语翻译 Agent 工具等。

  2. 去中心化模式 (Decentralized pattern - agents handing off to agents)： 多个 Agent 作为对等的（peers）工作，它们之间可以相互“交接”（handoff）工作流的控制权。 交接（handoff）是一种单向的转移，允许一个 Agent 把任务委托给另一个 Agent。在 Agents SDK 中，handoff 是一种特殊的工具或函数。 当一个 Agent 调用 handoff 函数时，执行会立即转移到被交接的那个 Agent 上，并且会传递最新的对话状态。 这种模式适合不需要单一 Agent 维持中心控制或合成结果的场景，比如客服分诊，或者让每个专业 Agent 完全接管特定任务。 例如： 一个分诊 Agent 接到用户关于订单的问题，直接将对话 handoff 给订单管理 Agent 处理。

注意： Agents SDK 采用的是更灵活的、代码优先 (code-first) 的方式，开发者可以直接用熟悉的编程方式表达工作流逻辑，而不需要预先定义整个图（声明式 declarative 图）。

护栏 (Guardrails)

设计良好的护栏有助于管理风险，比如数据隐私风险（防止系统提示泄露）或声誉风险（强制执行符合品牌形象的模型行为）。 护栏应被视为分层防御机制。单一护栏通常不够，多种专门护栏结合使用能构建更具韧性的 Agent。可以结合基于 LLM 的护栏、基于规则的护栏（如正则表达式 regex）和 OpenAI Moderation API 等。 常见的护栏类型：

  1. 相关性分类器 (Relevance classifier)：确保 Agent 的回应在预定范围内，标记离题的查询。
  2. 安全分类器 (Safety classifier)：检测不安全的输入，如越狱 (jailbreaks) 或提示注入 (prompt injections)。
  3. PII 过滤器 (PII filter)：审查模型输出，防止不必要的个人身份信息 (PII) 泄露。
  4. 内容审核 (Moderation)：标记有害或不当的输入（如仇恨言论、骚扰、暴力）。
  5. 工具安全防护 (Tool safeguards)：评估 Agent 可用工具的风险级别（低、中、高），基于读/写权限、操作可逆性、所需账户权限、财务影响等因素。根据风险级别触发自动化措施，比如执行高风险功能前暂停进行护栏检查，或在需要时升级给人工处理。
  6. 基于规则的保护 (Rules-based protections)：使用简单的确定性措施（如黑名单 blocklists、输入长度限制、正则表达式过滤器）来阻止已知威胁（如禁用词、SQL 注入）。
  7. 输出验证 (Output validation)：通过提示工程和内容检查，确保 Agent 的响应符合品牌价值，防止输出损害品牌形象。

构建护栏

从你为应用场景已经识别出的风险开始设置护栏。 随着发现新的漏洞，逐步增加额外的护栏层。 一个有效的策略是：

  1. 首先关注数据隐私和内容安全。
  2. 根据遇到的真实世界的边缘案例和失败情况，添加新的护栏。
  3. 随着 Agent 的发展，不断调整护栏，以优化安全性和用户体验。

规划人工干预

人工干预是一个关键的保障措施，使你能在不牺牲用户体验的情况下改进 Agent 的真实世界表现。在部署初期尤其重要。 实现人工干预机制，可以让 Agent 在无法完成任务时，优雅地将控制权转移。 通常需要人工干预的两种主要触发条件：

  1. 超出失败阈值 (Exceeding failure thresholds)：为 Agent 的重试或操作次数设置限制。如果 Agent 超出这些限制（例如，多次尝试后仍无法理解用户意图），则应升级到人工干预。
  2. 高风险操作 (High-risk actions)：对于敏感、不可逆或风险高的操作，应该触发人工监督，直到对 Agent 的可靠性有足够信心为止。例如取消用户订单、批准大额退款或进行支付。

结论

Agent 系统能够理解模糊性、跨工具采取行动，并高度自主地处理多步骤任务。这使得它们非常适合处理涉及复杂决策、非结构化数据或脆弱的基于规则的系统。 要构建可靠的 Agent，需要从坚实的基础开始：将强大的模型与定义良好的工具和清晰、结构化的指令配对。 使用与你的复杂性级别相匹配的编排模式，从单个 Agent 开始，仅在需要时才演进到多 Agent 系统。 护栏在每个阶段都至关重要，从输入过滤和工具使用到人工干预，有助于确保 Agent 在生产环境中安全、可预测地运行。 成功部署并非一蹴而就。从小处着手，通过真实用户进行验证，并随着时间的推移逐步扩展能力。 凭借正确的基础和迭代的方法，Agent 可以提供真正的商业价值——不仅仅是自动化任务，而是以智能和适应性自动化整个工作流。

原文：https://cdn.openai.com/business-guides-and-resources/a-practical-guide-to-building-agents.pdf