中文翻译

引言

大型语言模型正日益能够处理复杂的多步骤任务。推理、多模态和工具使用方面的进步开启了一类新的由 LLM 驱动的系统，称为 agent。

本指南专为探索如何构建其首批 agent 的产品和工程团队而设计，将大量客户部署中的洞见提炼为实用且可操作的最佳实践。它包含用于识别有前景用例的框架、设计 agent 逻辑与编排的清晰模式，以及确保你的 agent 安全、可预测且高效运行的最佳实践。

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

什么是代理？

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

代理是能够代表你独立完成任务的系统。

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

集成了 LLM 但不用其控制工作流执行的应用程序——比如简单的聊天机器人、单轮 LLM 或情感分类器——都不是 agent。

更具体地说，agent 具备一些核心特征，使其能够代表用户可靠且一致地行动：

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

你应该在什么时候构建 agent？

构建 agent 需要重新思考你的系统如何做出决策并处理复杂性。与传统自动化不同，agent 特别适合那些传统确定性和基于规则的方法难以胜任的工作流。

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

在评估智能体可以在哪些方面增加价值时，优先考虑那些此前一直抗拒自动化的工作流，尤其是传统方法遇到阻力的地方：

在决定构建智能体之前，请明确验证你的用例能否满足这些标准。否则，确定性解决方案可能就足够了。

Agent 设计基础

在最基本的形式中，一个 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],
)

选择你的模型

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

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

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

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

你可以在这里找到选择 OpenAI 模型的全面指南。

定义工具

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

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

广义而言，智能体需要三类工具：

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

from agents import Agent, WebSearchTool, function_tool
@function_tool 
def save_results(output): 
    db.insert({ : output, : 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 的决策能力，从而实现更顺畅的工作流执行和更少的错误。

指令的最佳实践

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

编排

有了基础组件之后，你可以考虑编排模式，使你的智能体能够有效执行工作流。

虽然人们很容易想要立即构建一个具有复杂架构的完全自主智能体，但客户通常通过渐进式方法取得更大的成功。

一般来说，编排模式分为两类：

1. 单智能体系统，即单个模型配备适当的工具和指令，在循环中执行工作流
2. 多智能体系统，工作流执行分布在多个协同工作的智能体上

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

单智能体系统

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

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

例如，在 Agents SDK 中，agent 通过该方法启动，它会在 LLM 上循环，直到满足以下任一条件：Runner.run()

1. 调用最终输出工具，由特定的输出类型定义
2. 模型返回一个不包含任何工具调用的响应（例如，直接的用户消息）

示例用法：

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

while 循环这一概念对 agent 的运行至关重要。在多 agent 系统中，正如你接下来会看到的，你可以让一系列工具调用和 agent 之间的交接依次进行，但允许模型运行多个步骤，直到满足退出条件。

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

何时考虑创建多个智能体

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

对于许多复杂的工作流程，将提示和工具分散到多个智能体中可以提高性能和可扩展性。当你的智能体无法遵循复杂的指令或持续选择错误的工具时，你可能需要进一步拆分系统并引入更多不同的智能体。

拆分智能体的实用指南包括：

• 复杂逻辑：当提示词包含大量条件语句（多个 if-then-else 分支），且提示词模板难以扩展时，考虑将每个逻辑段划分到不同的智能体中。
• 工具过载：问题不仅仅在于工具的数量，还在于它们的相似性或重叠。有些实现成功管理了超过 15 个定义明确、各不相同的工具，而另一些则在不到 10 个重叠工具时就举步维艰。如果通过提供描述性名称、清晰的参数和详细的描述来提升工具清晰度后性能仍未改善，则应使用多个智能体。

多智能体系统

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

• 管理者（agent 即工具）：一个中央“管理者”agent 通过工具调用协调多个专业化 agent，每个 agent 处理特定任务或领域。
• 去中心化（智能体交接给智能体）：多个智能体作为对等体运行，根据各自的专长相互交接任务。

多智能体系统可以建模为图，智能体表示为节点。在管理者模式中，边表示工具调用，而在去中心化模式中，边表示在智能体之间转移执行的交接。

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

管理者模式赋予一个中央 LLM——即“管理者”——通过工具调用无缝编排专业化 agent 网络的能力。管理者不会丢失上下文或控制权，而是智能地在正确的时间将任务委派给正确的 agent，轻松地将结果综合为连贯的交互。这确保了流畅、统一的用户体验，专业化能力始终可按需调用。

这种模式非常适合那些你只希望由一个智能体控制工作流执行并直接与用户交互的工作流。

管理者模式

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)

    message orchestrator_output.new_messages:
        print(f"  - Translation step: {message.content}")

声明式图与非声明式图

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

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

去中心化模式

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

这种模式涉及在平等基础上使用多个智能体，其中一个智能体可以直接将工作流的控制权移交给另一个智能体。当你不需要单个智能体维持集中控制或综合时，这是最优选择——而是允许每个智能体接管执行并按需与用户交互。

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

# 源码太长见 pdf 文件

这种模式对于对话分流等场景特别有效，或者当你希望由专门的智能体完全接管某些任务、而原始智能体无需继续参与时，也非常适用。你还可以选择为第二个智能体配备一个移交回原始智能体的功能，使其在必要时能够再次转移控制权。

护栏

设计良好的护栏有助于你管理数据隐私风险（例如，防止系统提示泄露）或声誉风险（例如，确保模型行为符合品牌规范）。你可以设置护栏来应对已经为你的用例识别出的风险，并在发现新的漏洞时逐步增加更多护栏。护栏是任何基于 LLM 的部署的关键组成部分，但应与稳健的身份验证和授权协议、严格的访问控制以及标准软件安全措施相结合。

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

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

护栏类型

构建护栏

设置护栏以应对您已为用例识别的风险，并在发现新漏洞时增加更多护栏。

我们发现以下启发式方法非常有效：

1. 关注数据隐私和内容安全
2. 根据你在实际应用中遇到的边缘情况和失败案例，添加新的防护措施
3. 在安全性和用户体验之间进行优化，随着你的智能体不断演进，调整你的防护措施。

例如，以下是使用 Agents SDK 时设置护栏的方法：

# 源码太长见 pdf 文件

Agents SDK 将护栏视为一等概念，默认依赖乐观执行。在这种方法下，主智能体主动生成输出，而护栏则并发运行，一旦违反约束便触发异常。

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

人工干预计划

人工干预是一项关键保障，使你能够在不损害用户体验的情况下提升智能体在真实世界中的表现。它在部署初期尤为重要，有助于识别故障、发现边缘情况并建立稳健的评估循环。

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

通常有两种主要触发条件需要人工干预：

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

结论

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

要构建可靠的 Agent，首先要打好基础：将能力强的模型与定义明确的工具以及清晰、结构化的指令相结合。使用与你的复杂程度相匹配的编排模式，从单 Agent 开始，仅在需要时演进到多 Agent 系统。护栏在每个阶段都至关重要，从输入过滤和工具使用到人工介入干预，有助于确保 Agent 在生产环境中安全且可预测地运行。

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

如果您正在为您的组织探索智能体，或正在为首次部署做准备，欢迎随时联系我们。我们的团队可以提供专业知识、指导以及实操支持，确保您取得成功。