OpenAI:构建Agent的实用指南

本文译自OpenAI发布的Practical Guide to Building Agents（原文以PDF格式发布)。在研究Agents的过程中将之与Google、Claude等关于Agent的文章一起进行比较，学习业界对Agents的不同定位。

OpenAI的这份指南非常侧重于为产品和工程团队提供可操作的建议和最佳实践，目标是帮助开发者构建出能实际运行的Agent。它清晰定义了Agent的三大核心组件，并给出了选择模型、定义工具、配置指令的具体建议。它非常重视安全与责任，并且用显著篇幅详细阐述了“护栏 (Guardrails)”的重要性、类型和构建方法，体现了对负责任AI的关注，这是在其它的指南中没有的非常重要的参考。

我的体会，与Anthropic的指南一样，在本指南中也强调了先最大化单Agent能力，再考虑多Agent复杂性，以敏捷开发和风险控制的策略进行Agent开发。

引言

大语言模型（LLM）在处理复杂、多步骤任务方面的能力日益增强。推理、多模态和工具使用方面的进步，催生了 LLM 驱动的新型系统，即 Agent。

本指南旨在帮助产品和工程团队探索如何构建他们的第一个 Agent，它从大量的客户部署中提炼出实用且可操作的最佳实践。指南中包含了识别有前景用例的框架、设计 Agent 逻辑和编排的清晰模式，以及确保 Agent 安全、可预测和有效运行的最佳实践。

阅读本指南后，您将掌握自信地开始构建第一个 Agent 所需的基础知识。

什么是 Agent？

传统的软件让用户能够简化和自动化工作流程，而 Agent 则能够以高度独立的方式，代表用户执行相同的工作流程。

Agent 是能够独立代表您完成任务的系统。

工作流程是为实现用户目标而必须执行的一系列步骤，无论是解决客户服务问题、预订餐厅、提交代码更改还是生成报告。

集成了 LLM 但不使用它们来控制工作流程执行的应用程序——例如简单的聊天机器人、单轮 LLM 或情感分类器——不属于 Agent。

更具体地说，Agent 具备核心特征，使其能够可靠且一致地代表用户行事：(补。01，它利用大语言模型来管理工作流程的执行和决策。它能识别工作流程何时完成，并在需要时主动纠正其行为。在出现故障时，它可以停止执行并将控制权转回给用户。)

何时应该构建 Agent？

构建 Agent 需要重新思考您的系统如何做出决策和处理复杂性。与传统自动化不同，Agent 尤其适用于传统确定性方法和基于规则的方法力所不及的工作流程。

以支付欺诈分析为例。传统的规则引擎就像一个清单，根据预设标准标记交易。相比之下，LLM Agent 更像一位经验丰富的调查员，它评估上下文，考虑细微模式，即使在没有明确规则被违反的情况下也能识别可疑活动。正是这种细致入微的推理能力，使 Agent 能够有效管理复杂、模糊的场景。

在评估 Agent 何处能增加价值时，优先考虑那些以前难以自动化、特别是传统方法遇到阻碍的工作流程：

在决定构建 Agent 之前，请明确验证您的用例是否符合这些标准。否则，确定性解决方案可能就足够了。

Agent 设计基础

在其最基本的形式中，Agent 由三个核心组件组成：(补。01，模型，LLM驱动Agent进行推理和决策)

以下是使用 OpenAI 的 Agents SDK 时，这些概念在代码中的体现。您也可以使用您偏好的库或从头开始直接实现相同的概念。

weather_agent = Agent(   
 name = "Weather agent",   
 instructions = "$ You are a helpful agent who can talk to users about the weather.",
 tools = [get_weather],   
)

选择您的模型

不同的模型在任务复杂性、延迟和成本方面具有不同的优势和权衡。正如我们将在下一节“编排”中看到的，您可能需要考虑在工作流程中为不同任务使用各种模型。

并非所有任务都需要最智能的模型——简单的检索或意图分类任务可以由更小、更快的模型处理，而像决定是否批准退款这样更困难的任务则可能受益于更强大的模型。

一种行之有效的方法是，为每个任务都使用最强大的模型来构建您的 Agent 原型，以建立性能基线。在此基础上，尝试替换为更小的模型，看看它们是否仍能达到可接受的结果。这样，您就不会过早地限制 Agent 的能力，并且可以诊断出较小的模型在何处成功或失败。

总而言之，选择模型的原则很简单：

您可以在此处找到选择 OpenAI 模型的综合指南。

定义工具

工具通过使用底层应用程序或系统的 API 来扩展 Agent 的能力。对于没有 API 的传统系统，Agent 可以依靠计算机使用模型，像人类一样通过网页和应用程序 UI 直接与这些应用程序和系统交互。

每个工具都应有标准化的定义，以实现工具与 Agent 之间灵活的多对多关系。文档完善、经过彻底测试且可重用的工具可以提高可发现性，简化版本管理，并防止重复定义。

广义上讲，Agent 需要三种类型的工具：

例如，以下是您在使用 Agents SDK 时，如何为上述定义的 Agent 配备一系列工具：

from agents import Agent, WebSearchTool, function_tool

@function_tool   
def save_results(output):   
    db.insert({"output": output,"timestamp": datetime.time()})   
    return "File saved"   
  
search_agent = Agent(   
    name = "Search agent",   
    instructions = "Help the user search the internet and save results if asked.",   
    tools = [WebSearchTool(),save_results],   
)

随着所需工具数量的增加，考虑将任务拆分到多个 Agent 中（参见编排）。

配置指令

高质量的指令对于任何 LLM 驱动的应用程序都至关重要，但对于 Agent 来说尤其关键。清晰的指令可以减少歧义，改善 Agent 的决策，从而使工作流程执行更顺畅，错误更少。

Agent 指令的最佳实践

您可以使用高级模型，如 o1 或 o3-mini，从现有文档中自动生成指令。以下是一个说明此方法的示例提示：

“You are an expert in writing instructions for an LLM agent. Convert the following help center document into a clear set of instructions, written in a numbered list. The document will be a policy followed by an LLM. Ensure that there is no ambiguity, and that the instructions are written as directions for an agent. The help center document to convert is the following {{help_center_doc}}”

编排

在基础组件到位后，您可以考虑编排模式，以使您的 Agent 能够有效地执行工作流程。

虽然立即构建一个具有复杂架构的完全自主 Agent 很有吸引力，但客户通常通过增量方法取得更大的成功。

通常，编排模式分为两类：

让我们详细探讨每种模式。

单 Agent 系统

单个 Agent 可以通过增量添加工具来处理许多任务，从而保持复杂性可控，并简化评估和维护。每个新工具都扩展了其能力，而不会过早地强制您编排多个 Agent。

每种编排方法都需要‘运行’的概念，通常实现为一个循环，让 Agent 运行直到达到退出条件。常见的退出条件包括工具调用、特定的结构化输出、错误或达到最大轮次。

例如，在 Agents SDK 中，Agent 使用 Runner.run() 方法启动，该方法会循环调用 LLM，直到满足以下任一条件：

示例用法：

Agents.run(agent, [UserMessage("What's the capital of the USA?")])

这种 while 循环的概念是 Agent 运行的核心。在多 Agent 系统中，正如您接下来将看到的，您可以拥有 Agent 之间的一系列工具调用和 Handofsf，但允许模型运行多个步骤直到满足退出条件。

一种在不切换到多 Agent 框架的情况下有效管理复杂性的策略是使用提示模板。与其为不同的用例维护大量单独的提示，不如使用一个接受策略变量的灵活基础提示。这种模板方法可以轻松适应各种上下文，显著简化维护和评估。当出现新的用例时，您可以更新变量，而不是重写整个工作流程。

Unset

1 """ You are a call center agent. You are interacting with {{user_first_name}} who has been a member for {{user_tenure}}. The user's most common complains are about {{user_complaint_categories}}. Greet the user, thank them for being a loyal customer, and answer any questions the user may have!

何时考虑创建多个 Agent

我们通常建议首先最大化单个 Agent 的能力。更多的 Agent 可以提供直观的概念分离，但可能引入额外的复杂性和开销，因此通常一个带有工具的单个 Agent 就足够了。

对于许多复杂的工作流程，将提示和工具拆分到多个 Agent 中可以提高性能和可扩展性。当您的 Agent 未能遵循复杂指令或始终选择不正确的工具时，您可能需要进一步划分您的系统并引入更多不同的 Agent。

拆分 Agent 的实用指南包括：

多 Agent 系统

虽然多 Agent 系统可以根据特定的工作流程和需求以多种方式设计，但我们与客户的经验突出了两个广泛适用的类别：

多 Agent 系统可以建模为图，其中 Agent 表示为节点。在管理器模式中，边表示工具调用，而在去中心化模式中，边表示在 Agent 之间转移执行的 Handofsf。

无论采用何种编排模式，相同的原则都适用：保持组件灵活、可组合，并由清晰、结构良好的提示驱动。

管理器模式

管理器模式赋予中央 LLM——即“管理器”——通过工具调用无缝编排专业 Agent 网络的能力。管理器不会丢失上下文或控制权，而是智能地在正确的时间将任务委托给正确的 Agent，毫不费力地将结果合成为一个连贯的交互。这确保了流畅、统一的用户体验，并随时按需提供专业能力。

这种模式非常适合您只希望一个 Agent 控制工作流程执行并与用户交互的场景。

例如，以下是您如何在 Agents SDK 中实现此模式：

from agents import Agent, Runner   
   
manager_agent = Agent(   
    name = "manager_agent",   
    instructions = (
        "You are a translation agent. You use the tools given to you to translate."   
        "If asked for multiple translations, you call the relevant tools."
    ),   
    tools=[   
        spanish_agent.as_tool(   
            tool_name = "translate_to_spanish",   
            tool_description = "Translate the user's message to Spanish",   
        ),   
        french_agent.as_tool(   
            tool_name = "translate_to_french",   
            tool_description = "Translate the user's message to French",   
        ),   
        italian_agent.as_tool(   
            tool_name = "translate_to_italian",   
            tool_description = "Translate the user's message to Italian",   
        ),   
    ],   
)   
   
asyncdefmain():   
    msg = input("Translate 'hello' to Spanish, French and Italian for me!")   
   
    orchestrator_output = await Runner.run(manager_agent,msg)   
   
    for message in orchestrator_output.new_messages:   
        print(f"  - Translation step: {message.content}")

声明式与非声明式图

一些框架是声明式的，要求开发者通过由节点（Agent）和边（确定性或动态 Handofsf）组成的图，预先明确定义工作流程中的每个分支、循环和条件。虽然这有利于视觉清晰度，但随着工作流程变得更加动态和复杂，这种方法会迅速变得繁琐和具有挑战性，通常需要学习专门的领域特定语言。

相比之下，Agents SDK 采用更灵活、代码优先的方法。开发者可以直接使用熟悉的编程结构表达工作流程逻辑，而无需预先定义整个图，从而实现更动态和适应性强的 Agent 编排。

去中心化模式

在去中心化模式中，Agent 可以相互‘Handofsf’工作流程执行。Handofsf 是一种单向转移，允许一个 Agent 委托给另一个 Agent。在 Agents SDK 中，Handofsf 是一种工具或函数。如果一个 Agent 调用 Handofsf 函数，我们会立即在新 Agent 上开始执行，同时转移最新的对话状态。

这种模式涉及使用多个地位平等的 Agent，其中一个 Agent 可以直接将工作流程的控制权 Handofsf 给另一个 Agent。当您不需要单个 Agent 保持中央控制或综合时，这种模式是最佳选择——它允许每个 Agent 根据需要接管执行并与用户交互。

例如，以下是您如何使用 Agents SDK 为同时处理销售和支持的客户服务工作流程实现去中心化模式：

from agents import Agent, Runner   
   
technical_support_agent = Agent(   
    name = "Technical Support Agent",   
    instructions = (   
        "You provide expert assistance with resolving technical issues, system outages, or product troubleshooting."   
    ),   
    tools = [search_knowledge_base]   
)   
   
sales_assistant_agent = Agent(   
    name = "Sales Assistant Agent",   
    instructions = (   
        "You help enterprise clients browse the product catalog, recommend suitable solutions, and facilitate purchase transactions."   
    ),   
    tools = [initiate_purchase_order]   
)   
   
order_management_agent = Agent(   
    name = "Order Management Agent",   
    instructions = (   
        "You assist clients with inquiries regarding order tracking, delivery schedules, and processing returns or refunds."   
    ),   
    tools = [track_order_status, initiate_refund_process]   
)   

triage_agent = Agent(   
    name = "Triage Agent",   
    instructions = "You act as the first point of contact, assessing customer queries and directing them promptly to the correct specialized agent.",   
    handoffs = [technical_support_agent, sales_assistant_agent,   order_management_agent],   
)   
   
await Runner.run(   
    triage_agent,   
    input("Could you please provide an update on the delivery timeline for our recent purchase?")   
)

在上述示例中，初始用户消息被发送到 triage_agent。triage_agent 识别到输入与最近的购买有关，将调用 Handofsf 给 order_management_agent，将控制权转移给它。

这种模式对于对话分流等场景特别有效，或者当您希望专业 Agent 完全接管某些任务而无需原始 Agent 继续参与时。您可以选择为第二个 Agent 配备一个 Handofsf 回原始 Agent 的功能，允许它在必要时再次转移控制权。

Guardrails

精心设计的 Guardrails 有助于您管理数据隐私风险（例如，防止系统提示泄露）或声誉风险（例如，强制执行与品牌一致的模型行为）。您可以设置 Guardrails 来解决您已为用例识别的风险，并在发现新漏洞时分层添加更多 Guardrails。Guardrails 是任何基于 LLM 的部署的关键组成部分，但应与强大的身份验证和授权协议、严格的访问控制和标准软件安全措施相结合。

将 Guardrails 视为一种分层防御机制。虽然单个 Guardrail 不太可能提供足够的保护，但结合使用多个专业 Guardrails 可以创建更具弹性的 Agent。

在下图中，我们结合了基于 LLM 的 Guardrails、基于规则的 Guardrails（如正则表达式）以及 OpenAI 审核 API 来审查用户输入。

Guardrails 的类型

构建 Guardrails

设置 Guardrails 来解决您已为用例识别的风险，并在发现新漏洞时分层添加更多 Guardrails。

我们发现以下启发式方法是有效的：

例如，以下是您在使用 Agents SDK 时如何设置 Guardrails：

from agents import (   
    Agent,   
    GuardrailFunctionOutput,   
    InputGuardrailTripwireTriggered,   
    RunContextWrapper,   
    Runner,   
    TResponseInputItem,   
    input_guardrail,   
    Guardrail,   
    GuardrailTripwireTriggered   
)   
from pydantic import BaseModel   
   
classChurnDetectionOutput(BaseModel):   
    is_churn_risk: bool   
    reasoning: str   

churn_detection_agent = Agent(   
    name="Churn Detection Agent",   
    instructions="$ Identify if the user message indicates a potential customer churn risk.",   
    output_type=ChurnDetectionOutput,   
)   

@input_guardrail   
asyncdefchurn_detection_tripwire(
    ctx: RunContextWrapper , 
    agent: Agent, 
    input: str | list[TResponseInputItem] 
) -> GuardrailFunctionOutput: 
    result=await Runner.run(churn_detection_agent, input,   
context=ctx.context) 
    return GuardrailFunctionOutput( 
        output_info=result.final_output, 
        tripwire_triggered=result.final_output.is_churn_risk, 
    )

customer_support_agent=Agent( 
    name="Customer support agent", 
    instructions="You are a customer support agent. You help customers with their questions.", 
    input_guardrails=[ 
        Guardrail(guardrail_function=churn_detection_tripwire), 
    ],   
)   

asyncdefmain(): 
    # This should be ok 
    await Runner.run(customer_support_agent, "Hello!") 
    print("Hello message passed")

    # This should trip the guardrail 
    try: 
        await Runner.run(agent, "I think I might cancel my subscription") 
        print("Guardrail didn't trip - this is unexpected")
    except GuardrailTripwireTriggered:
        print("Churn detection guardrail tripped")

Agents SDK 将 Guardrails 视为一等公民概念，默认依赖乐观执行。在这种方法下，主 Agent 主动生成输出，而 Guardrails 并行运行，如果违反约束则触发异常。

Guardrails 可以作为函数或 Agent 实现，用于强制执行策略，例如越狱预防、相关性验证、关键词过滤、黑名单强制执行或安全分类。例如，上述 Agent 乐观地处理数学问题输入，直到 math_homework_tripwire Guardrail 识别出违规并引发异常。

规划人工干预

人工干预是一项关键的安全保障措施，它使您能够在不损害用户体验的情况下提高 Agent 的实际性能。在部署初期，它尤为重要，有助于识别故障、发现边缘情况并建立稳健的评估周期。

实施人工干预机制允许 Agent 在无法完成任务时优雅地转移控制权。在客户服务中，这意味着将问题升级给人工 Agent。对于编码 Agent，这意味着将控制权交还给用户。

通常，以下两个主要触发因素需要人工干预：

• • 超出失败阈值：设置 Agent 重试或行动的限制。如果 Agent 超出这些限制（例如，多次尝试后仍未能理解客户意图），则升级到人工干预。
• • 高风险行动：敏感、不可逆或风险高的行动应触发人工监督，直到对 Agent 可靠性的信心增强。示例包括取消用户订单、授权大额退款或进行支付。

结论

Agent 标志着工作流程自动化新时代的到来，系统能够通过模糊性进行推理，跨工具采取行动，并以高度自主性处理多步骤任务。与简单的 LLM 应用程序不同，Agent 端到端地执行工作流程，使其非常适合涉及复杂决策、非结构化数据或脆弱的基于规则的系统的用例。

要构建可靠的 Agent，请从坚实的基础开始：将强大的模型与定义明确的工具和清晰、结构化的指令相结合。使用与您的复杂性级别相匹配的编排模式，从单个 Agent 开始，仅在需要时才发展到多 Agent 系统。Guardrails 在每个阶段都至关重要，从输入过滤和工具使用到人工干预，有助于确保 Agent 在生产环境中安全、可预测地运行。

成功部署的道路并非一蹴而就。从小处着手，与真实用户验证，并随着时间的推移逐步增强能力。有了正确的基础和迭代方法，Agent 可以带来真正的商业价值——不仅自动化任务，还能以智能和适应性自动化整个工作流程。

如果您正在为您的组织探索 Agent 或准备首次部署，请随时与我们联系。我们的团队可以提供专业知识、指导和实践支持，以确保您的成功。