一文快速理清 OpenAI Agents SDK

OpenAI Agents SDK 是 OpenAI 推出的一个轻量级 Agent 开发框架，可以帮助我们快速搭建强大的、可扩展的多智能体系统，从而为我们的 AI 应用提供更智能的工作流。

本文将帮助你快速理清 OpenAI Agents SDK 的设计原则、核心概念以及与其他框架相比的优劣势。

两大设计原则：易用性与可扩展性兼备

OpenAI Agents SDK 的设计遵循以下两个原则：

1. 功能丰富，概念精简——提供强大能力的同时，保持简洁的概念设计，使开发者能够快速上手。
2. 开箱即用，灵活定制——既可直接使用默认配置，也支持高度自定义，以适应不同业务需求。

这样的设计使得此 SDK 既赋予了初学者平滑的学习曲线，也满足了资深开发者对于复杂工作流的构建需求。

四大核心概念：构建 Agent 系统的基石

OpenAI Agents SDK 的核心由以下四个概念构成：

1. Agents（智能体）
   基于 LLM（大语言模型）构建，配置了指令（Instructions）、工具（Tools）等内容，用于执行特定任务。
2. Handoffs（交接机制）
   交接机制允许一个 Agent 将任务委派给另一个 Agent，以提高任务处理的专业性和效率。例如，在客服应用中，不同的 Agent 可以分别处理订单查询、退款处理和技术支持的工作。
3. Guardrails（安全护栏）
   这是 SDK 提供的安全检查机制，用于验证输入和输出，确保 Agent 的行为符合预期。例如，可以通过护栏拦截违规内容或防止滥用计算资源。
4. Tracing（追踪功能）
   SDK 内置了追踪功能，可监控智能体的运行情况，包括调用记录、工具使用、交接过程等，便于开发者进行调试、优化和可视化分析。

这四个核心概念构成了 OpenAI Agents SDK 的基础，使得开发者能够更加高效、可靠地管理 AI Agent系统。

智能体（Agents）：核心执行单元

在 OpenAI Agents SDK 中，Agent 是具备特定能力的 AI 实体。要创建一个最基本的 Agent，只需指定其名称和指令即可：

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

result = Runner.run_sync(agent, "Write a haiku about recursion in programming.")
print(result.final_output)

上面的示例就定义了一个名为“Assistant”的 Agent，并指示其充当“有帮助的助手”。当运行 Runner.run_sync() 时，该 Agent 会根据输入生成相应的回应，比如这里是让它“写一首关于编程中的递归的俳句”。

代码自调用，

环舞无歇寂无喧，

重重皆是象。

智能体循环（Agent Loop）

每当 Runner.run() 被调用时，Agent 会进入一个循环，直到获取最终输出。其执行流程如下：

1. 调用 LLM —— Agent 使用预设的模型、配置以及消息历史来调用LLM进行推理。
2. 处理 LLM 响应 —— LLM 返回的结果可能包含最终输出，也可能包含工具调用或交接请求。
3. 判断是否完成 —— 若响应包含最终输出，则返回结果并结束循环。
4. 执行交接 —— 若响应涉及交接，则切换到新的代理，并重复上述步骤。
5. 调用工具 —— 若响应涉及工具调用，则执行相应操作，并将结果反馈给 LLM，再次进入循环。

交接机制（Handoffs）：Agent 协作的关键

在复杂的 AI 交互场景中，单一 Agent 往往难以满足所有需求。交接机制允许 Agent 根据任务内容将请求转移给另一个更合适的 Agent，从而实现高效协作。例如，在教育应用中，可以创建不同领域的专家 Agent：

from agents import Agent
import asyncio

history_tutor_agent = Agent(
    name="History Tutor",
    handoff_description="Specialist agent for historical questions",
    instructions="You provide assistance with historical queries. Explain important events and context clearly.",
)

math_tutor_agent = Agent(
    name="Math Tutor",
    handoff_description="Specialist agent for math questions",
    instructions="You provide help with math problems. Explain your reasoning at each step and include examples",
)

然后，将这些 Agent 整合到一个更高层的 Triage Agent 中，由它负责判断用户输入，并将问题交给合适的 Agent 处理：

from agents import Agent
import asyncio

triage_agent = Agent(
    name="Triage Agent",
    instructions="You determine which agent to use based on the user's homework question",
    handoffs=[history_tutor_agent, math_tutor_agent]
)

asyncdefmain():
    result = await Runner.run(triage_agent, "What is the capital of France?")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())   

上面的示例就整合了历史导师、数学导师两个 Agent，然后我们输入了“法国的首都是什么？”，它会识别问题，然后将其交给历史导师 Agent 来回答。

法国首都是巴黎。几个世纪以来，巴黎一直是一座重要的城市，是欧洲的文化、政治和经济中心。巴黎以其丰富的历史、标志性地标（如埃菲尔铁塔、卢浮宫博物馆）以及在法国大革命等各种历史事件中发挥的作用而闻名。

安全护栏（Guardrails）：增强安全性与可靠性

安全护栏用于审核用户输入和 Agent 输出，以防止不当使用或违规行为。例如，可以使用安全护栏检测用户是否在试图让 AI 执行指导作业之外的操作：

from agents import GuardrailFunctionOutput, Agent, Runner
from pydantic import BaseModel

classHomeworkOutput(BaseModel):
    is_homework: bool
    reasoning: str

guardrail_agent = Agent(
    name="Guardrail check",
    instructions="Check if the user is asking about homework.",
    output_type=HomeworkOutput,
)

asyncdefhomework_guardrail(ctx, agent, input_data):
    result = await Runner.run(guardrail_agent, input_data, context=ctx.context)
    final_output = result.final_output_as(HomeworkOutput)
return GuardrailFunctionOutput(
        output_info=final_output,
        tripwire_triggered=not final_output.is_homework,
    )

from agents import Agent, Runner
import asyncio
from homework_output import HomeworkOutput

triage_agent = Agent(
    name="Triage Agent",
    instructions="You determine which agent to use based on the user's homework question",
    handoffs=[history_tutor_agent, math_tutor_agent],
    output_type=HomeworkOutput
)

asyncdefmain():
    result = await Runner.run(triage_agent, "Can you teach me how to make a bomb?")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())   

上面的示例中，我们通过护栏 Agent 限定了用户只能询问作业相关的问题，然而我们却输入了“你能教我怎么制作炸弹吗？”，它会意识到用户问出了安全护栏之外的问题，从而拒绝回答并给出理由：

is_homework=False, reasoning="该请求涉及非法活动并带来安全隐患。它与任何学术或建设性的教育背景无关，例如数学或历史，我会将询问转交给专业导师。"

追踪功能（Tracing）：监控与优化 Agent 运行

追踪功能记录 Agent 运行过程中的所有事件，包括生成、工具调用、交接过程、防护措施以及自定义事件等。借助这些日志，开发者可以：

• 分析模型行为，优化 Agent 逻辑
• 调试错误，快速定位问题
• 可视化Agent工作流，提升系统透明度

这一功能在开发和生产环境中都极具价值，确保 Agent 能够稳定、高效地运行。

更多功能：工具集成与多模型支持

除了以上这些，OpenAI Agents SDK 还提供了工具集成和多模型支持，进一步增强 Agent 的能力：

1. 工具类别

• 内置工具：包含文件检索、网页搜索和计算机使用，由 OpenAI 提供。
• 函数转换：允许使用 Python 函数作为工具，也可以以此形式自定义工具。
• Agent 转换：允许将 Agent 直接转换为工具使用。

• OpenAI模型：支持最新的 Responses API 和传统的  Chat Completions API。
• 其他模型：许多模型提供商都支持 OpenAI API 格式，只需提供base_url即可实现切换。

比较：与 SmolAgents 框架孰优孰劣？

我前段时间刚好也分享了另一个 Agent 开发框架 SmolAgents，这两个框架都以轻量级和快速构建强大 Agent 为卖点。因此，我想借此机会，从多个维度对它们进行对比分析，帮助开发者更好地了解它们的适用场景和优劣势。

模型支持

工具调用

安全护栏

交接机制

追踪功能

社区支持

总结

OpenAI Agents SDK 在 OpenAI 生态内无疑是最佳选择，适合快速构建 API 驱动的智能体应用，而 SmolAgents 则凭借极简设计、代码执行能力和丰富的 LLM 兼容性，为开发者提供了更大的自由度。

未来，我们期待 OpenAI Agents SDK 在模型兼容性、代码执行、任务编排等方面进一步优化，以满足更广泛的 Agent 应用需求。