OpenAI 构建代理的实用指南

目录

引言

大型语言模型在处理复杂的多步骤任务方面能力日益增强。 推理、多模态和工具使用方面的进步开启了 LLM 驱动系统的一个新类别，即代理。 本指南专为探索如何构建其首个代理的产品和工程团队而设计，将众多客户部署的见解提炼为实用且可操作的最佳实践。 它包括用于识别有前景用例的框架、设计代理逻辑和编排的清晰模式，以及确保代理安全、可预测且有效运行的最佳实践。 阅读本指南后，您将掌握自信地开始构建首个代理所需的基础知识。

什么是代理？

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

代理是代表您独立完成任务的系统。

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

集成 LLM 但不使用它们来控制工作流程执行的应用程序（例如简单的聊天机器人、单轮 LLM 或情感分类器）不是代理。

更具体地说，代理具有使其能够可靠且一致地代表用户行事的核心特征：

1. 它利用 LLM 来管理工作流程执行并做出决策。 它能够识别工作流程何时完成，并能在需要时主动纠正其行为。 如果失败，它可以停止执行并将控制权交还给用户。
2. 它可以访问各种工具来与外部系统交互——既可以收集上下文，也可以采取行动——并根据工作流程的当前状态动态选择适当的工具，始终在明确定义的防护措施内操作。

何时应该构建代理？

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

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

在评估代理可以在哪些方面增加价值时，优先考虑以前难以自动化的工作流程，尤其是在传统方法遇到阻力的地方：

1. 复杂的决策制定： 涉及细致判断、例外情况或上下文相关决策的工作流程，例如客户服务工作流程中的退款审批。
2. 难以维护的规则： 由于规则集庞大而复杂，导致更新成本高昂或容易出错的系统，例如执行供应商安全审查。
3. 严重依赖非结构化数据： 涉及解释自然语言、从文档中提取含义或与用户进行对话式交互的场景，例如处理房屋保险索赔。

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

代理设计基础

代理最基本的形式包含三个核心组件：

以下是使用 OpenAl 的代理 SDK 时代码中的样子。 您也可以使用您偏好的库或从头开始构建来实现相同的概念。

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

选择您的模型

不同的模型在任务复杂性、延迟和成本方面具有不同的优势和权衡。 正如我们将在下一节关于编排的内容中看到的，您可能需要考虑为工作流程中的不同任务使用各种模型。 并非每个任务都需要最智能的模型——简单的检索或意图分类任务可以由更小、更快的模型处理，而更难的任务（如决定是否批准退款）则可能受益于功能更强大的模型。

一种行之有效的方法是使用最强大的模型为每个任务构建代理原型，以建立性能基准。 然后，尝试换用较小的模型，看看它们是否仍能达到可接受的结果。 这样，您就不会过早地限制代理的能力，并且可以诊断出较小模型在哪些方面成功或失败。

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

1. 设置评估以建立性能基准
2. 专注于使用可用的最佳模型达到您的准确性目标
3. 通过尽可能用较小的模型替换较大的模型来优化成本和延迟

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

定义工具

工具通过使用来自底层应用程序或系统的 API 来扩展代理的功能。 对于没有 API 的旧系统，代理可以依靠计算机使用模型通过 Web 和应用程序 UI 直接与这些应用程序和系统交互——就像人类一样。

每个工具都应该有一个标准化的定义，从而实现工具和代理之间灵活的多对多关系。 文档齐全、经过全面测试且可重用的工具可以提高可发现性、简化版本管理并防止冗余定义。

广义而言，代理需要三种类型的工具：

例如，以下是如何在使用代理 SDK 时为上面定义的代理配备一系列工具：

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],
)

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

配置说明

高质量的指令对于任何由 LLM 驱动的应用程序都至关重要，但对于代理尤其关键。 清晰的指令可以减少模糊性并改善代理的决策制定，从而实现更顺畅的工作流程执行和更少的错误。

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

您是一位为 LLM 代理编写指令的专家。将以下帮助中心文档转换为一组清晰的指令，并以编号列表的形式编写。该文档将作为 LLM 遵循的策略。确保没有歧义，并且指令是为代理编写的。要转换的帮助中心文档如下 {{help_center_doc}}

编排

有了基本组件后，您就可以考虑编排模式，以使您的代理能够有效地执行工作流程。 虽然人们很容易立即构建具有复杂架构的完全自主的代理，但客户通常通过渐进的方法取得更大的成功。

总的来说，编排模式分为两类：

1. 单代理系统，其中单个模型配备适当的工具和指令，以循环方式执行工作流程
2. 多代理系统，其中工作流程执行分布在多个协调的代理之间

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

单代理系统

单个代理可以通过逐步添加工具来处理许多任务，从而保持复杂性可控并简化评估和维护。 每个新工具都会扩展其功能，而不会过早地迫使您编排多个代理。

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

例如，在代理 SDK 中，代理使用 Runner.run() 方法启动，该方法会循环访问 LLM，直到：

1. 调用最终输出工具，该工具由特定的输出类型定义
2. 模型返回响应而没有任何工具调用（例如，直接的用户消息）

示例用法：

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

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

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

您是一名呼叫中心座席。您正在与 {{user_first_name}} 互动，他/她成为会员已有 {{user_tenure}}。用户最常见的抱怨是关于 {{user_complaint_categories}}。问候用户，感谢他们成为忠实客户，并回答用户可能提出的任何问题！

何时考虑创建多个代理

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

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

拆分代理的实用指南包括：

复杂逻辑

当提示包含许多条件语句（多个 if-then-else 分支）并且提示模板难以扩展时，请考虑将每个逻辑段划分到不同的代理。

工具过载

问题不仅仅在于工具的数量，还在于它们的相似性或重叠性。 一些实现成功管理了超过 15 个定义明确、功能各异的工具，而另一些则在少于 10 个功能重叠的工具时就遇到了困难。 如果通过提供描述性名称、清晰的参数和详细的描述来提高工具的清晰度并不能改善性能，请使用多个代理。

多代理系统

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

管理者（代理即工具）

一个中央“管理者”代理通过工具调用协调多个专业代理，每个代理处理特定的任务或领域。

去中心化（代理将任务移交给代理）

多个代理作为对等方运行，根据其专业将任务移交给彼此。

多代理系统可以建模为图，其中代理表示为节点。 在管理者模式中，边表示工具调用，而在去中心化模式中，边表示在代理之间转移执行的移交。 无论采用哪种编排模式，都适用相同的原则：保持组件的灵活性、可组合性，并由清晰、结构良好的提示驱动。

管理者模式

管理者模式使中央 LLM（即“管理者”）能够通过工具调用无缝地编排专业代理网络。 管理者不会丢失上下文或控制权，而是智能地在正确的时间将任务委派给正确的代理，毫不费力地将结果合成为一个有凝聚力的交互。 这确保了流畅、统一的用户体验，并且专业功能始终按需可用。

此模式非常适用于您只希望一个代理控制工作流程执行并有权访问用户的工作流程。

例如，以下是如何在代理 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",
        ),
    ],
)
async def main():
    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}")

声明式与非声明式图

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

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

去中心化模式

在去中心化模式中，代理可以将工作流程执行“移交”给彼此。 移交是一种单向转移，允许代理委派给另一个代理。 在代理 SDK 中，移交是一种工具或函数。 如果代理调用移交函数，我们会立即在移交到的新代理上开始执行，同时也会转移最新的对话状态。

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

例如，以下是如何使用代理 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 识别出输入与最近的购买有关，将调用切换到 order_management_agent，并将控制权转移给它。

此模式对于对话分流等场景特别有效，或者在您希望专门的代理完全接管某些任务而无需原始代理保持参与的情况下。 （可选）您可以为第二个代理配备一个切换回原始代理的功能，以便在必要时允许它再次转移控制权。

防护措施

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

将防护措施视为分层防御机制。 虽然单个防护措施不太可能提供足够的保护，但将多个专门的防护措施一起使用可以创建更具弹性的代理。 在下图中，我们结合了基于 LLM 的防护措施、基于规则的防护措施（例如正则表达式）和 OpenAl 审核 API 来审查我们的用户输入。

防护措施类型

基于规则的保护

简单的确定性措施（黑名单、输入长度限制、正则表达式过滤器）可防止已知威胁，如禁用词或 SQL 注入。

输出验证

通过提示工程和内容检查确保响应符合品牌价值，防止可能损害品牌完整性的输出。

构建防护措施

设置解决您已为用例识别的风险的防护措施，并在发现新漏洞时分层添加其他防护措施。

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

1. 专注于数据隐私和内容安全
2. 根据您遇到的实际边缘案例和故障添加新的防护措施
3. 随着代理的发展，优化安全性和用户体验，并调整您的防护措施

例如，以下是如何在使用代理 SDK 时设置防护措施：

from agents import (
    Agent,
    GuardrailFunctionOutput,
    InputGuardrailTripwireTriggered,
    RunContextWrapper,
    Runner,
    TResponseInputItem,
    input_guardrail,
    Guardrail,
    GuardrailTripwireTriggered
)
from pydantic import BaseModel

class ChurnDetectionOutput(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
async def churn_detection_tripwire(
    ctx: RunContextWrapper[None], 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),
    ],
)

async def main():
    # 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")

代理 SDK 将防护措施视为一流概念，默认情况下依赖于乐观执行。 在这种方法下，主代理主动生成输出，而防护措施同时运行，如果违反约束则触发异常。 防护措施可以实现为强制执行策略的函数或代理，例如越狱预防、相关性验证、关键字过滤、黑名单强制执行或安全分类。 例如，上面的代理乐观地处理数学问题输入，直到 math_homework_tripwire 防护措施识别出违规并引发异常。

规划人工干预

人工干预是一项关键的保障措施，使您能够在不影响用户体验的情况下提高代理的实际性能。 这在部署早期尤其重要，有助于识别故障、发现边缘案例并建立强大的评估周期。

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

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

超出失败阈值： 设置代理重试或操作的限制。 如果代理超出这些限制（例如，在多次尝试后未能理解客户意图），则升级到人工干预。

高风险操作： 敏感、不可逆或具有高风险的操作应触发人工监督，直到对代理可靠性的信心增强为止。 示例包括取消用户订单、授权大额退款或进行付款。

结论

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

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

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

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

更多资源

API 平台
OpenAl 商业版
OpenAl 故事
ChatGPT 企业版
OpenAl 与安全
开发者文档

原文下载

OpenAl 是一家人工智能研究和部署公司。 我们的使命是确保通用人工智能造福全人类。