OpenAI Agents Python：多 Agent 工作流的轻量级框架

原文来源：OpenAI Agents Python GitHub — OpenAI 官方推出的轻量级多 Agent 工作流框架，26.1k Stars，4k Forks，1473 次提交，支持 Agent 编排、工具调用和 guardrails。

OpenAI Agents Python 是 OpenAI 官方推出的轻量级框架，专门用于构建多 Agent 工作流。与 LangChain、LlamaIndex 等重量级框架不同，它追求极简设计——核心代码不到 1000 行，但提供了构建生产级 Agent 系统所需的所有关键原语。

核心设计哲学

极简但完整

框架刻意保持轻量，不提供过多抽象。核心概念只有四个：

• Agent：执行任务的实体，有指令、工具和模型配置
• Tool：Agent 可以调用的函数
• Handoff：Agent 之间的任务交接
• Guardrail：输入/输出的安全检查

这种极简设计带来了几个好处。首先是学习成本低，你不需要理解复杂的抽象层次和概念体系，四个核心概念就能覆盖大部分使用场景。其次是调试简单，代码量少意味着出问题时有更少的嫌疑对象，更容易定位 bug。最后是灵活性高，框架不强制特定的架构模式，你可以根据自己的需求自由组合这些原语。

原生 OpenAI 集成

作为官方框架，它深度集成 OpenAI 的最新模型能力，包括：

• 函数调用（Function Calling）：模型可以识别需要调用工具的场景，并生成正确的参数
• 结构化输出（Structured Outputs）：强制模型返回符合 JSON Schema 的数据，适合对接下游系统
• 推理能力（Reasoning）：o1/o3 系列模型的思维链能力，适合复杂决策场景
• 视觉理解（Vision）：GPT-4o 的多模态能力，可以处理图片输入

这种原生集成意味着你不需要在框架和模型之间做适配层，新模型能力发布后可以立即使用。

多 Agent 编排

框架的核心优势是Agent 编排。你可以定义多个专门的 Agent，让它们协作完成复杂任务。

交接（Handoff）机制

一个 Agent 可以将任务交接给另一个 Agent。比如：

• 路由 Agent 接收用户请求，判断是技术问题还是账单问题
• 技术问题交接给技术支持 Agent
• 账单问题交接给客服 Agent

这种设计让系统可以像呼叫中心一样运作，每个 Agent 只处理自己擅长的领域。交接不是简单的转发，而是包含完整的上下文传递，下一个 Agent 能看到完整的对话历史。

上下文传递

交接时，对话历史可以完整传递，确保下一个 Agent 了解完整上下文。也可以选择性地传递部分信息，实现信息隔离。比如在医疗场景中，路由 Agent 知道患者的完整病史，但交接给预约 Agent 时只传递"需要预约皮肤科"这个信息，保护隐私。

并行执行

多个 Agent 可以同时工作，各自处理不同方面的任务。比如一个 Agent 分析情感，另一个 Agent 提取关键词，第三个 Agent 生成回复草稿，最后由一个汇总 Agent 整合结果。

工具系统

框架支持多种工具类型：

函数工具

用 Python 函数定义工具，框架自动处理参数解析和验证：

from agents import Agent, function_tool
 
@function_tool
def get_weather(location: str) -> str:
    """获取指定位置的天气"""
    return f"{location} 的天气是晴天"
 
agent = Agent(
    name="天气助手",
    instructions="帮助用户查询天气",
    tools=[get_weather]
)

装饰器会自动读取函数的签名和文档字符串，生成 OpenAI 需要的工具描述。你不需要手动写 JSON Schema。

内置工具

提供常用工具的原生支持：

• Web 搜索：查询实时信息
• 文件读取：加载本地文件内容
• 代码执行：在沙箱中运行 Python 代码

自定义工具

可以集成任意 API 或服务作为工具，框架负责与 OpenAI 的函数调用协议对接。比如连接内部数据库、调用第三方 SaaS API、操作云资源等。

Guardrails 安全机制

Guardrails 是框架的安全层，用于保护系统免受有害输入和输出：

输入 Guardrails

在 Agent 处理用户输入前进行检查，比如：

• 检测提示注入攻击：识别用户输入中试图覆盖系统指令的内容
• 过滤敏感信息：检测密码、API Key、个人身份信息
• 验证输入格式：确保输入符合预期的结构和类型

输出 Guardrails

在 Agent 输出结果前进行检查，比如：

• 检测有害内容：识别歧视、暴力、违法内容
• 验证输出格式是否符合预期：确保返回的数据可以被下游系统正确解析
• 确保不包含敏感信息：防止模型泄露训练数据中的隐私信息

自定义 Guardrails

可以用简单的 Python 函数定义自己的 guardrails 规则：

from agents import input_guardrail
 
@input_guardrail
def check_for_pii(user_input: str) -> bool:
    """检查输入是否包含个人身份信息"""
    # 自定义检查逻辑
    return "SSN" not in user_input

Guardrails 的设计哲学是默认安全。框架提供了基础的安全检查，同时允许你根据业务需求扩展。这种分层安全模型让系统既不会过度限制正常用例，也不会对危险输入毫无防备。

与重量级框架对比

OpenAI Agents 的定位是"快速构建生产级 Agent"。如果你已经在使用 OpenAI 模型，且不需要跨模型支持，这个框架能让你用最少代码搭建复杂工作流。

LangChain 和 LlamaIndex 的优势在于生态丰富和跨模型支持，但代价是复杂度高、学习曲线陡峭、升级时容易遇到 breaking changes。OpenAI Agents 选择了一条不同的路：不做所有事，但把核心的事做到极致简单。

适用场景

• 需要快速原型验证的 AI 应用
• 使用 OpenAI 模型的客服/支持系统
• 多步骤审批或处理工作流
• 需要严格输入输出控制的合规场景
• 作为更复杂系统的 Agent 编排层
• 教学和学习 Agent 开发的入门框架

安装

pip install openai-agents

需要 Python 3.9 及以上版本，以及 OpenAI API Key。

实际示例

以下是一个简单的多 Agent 客服系统示例：

from agents import Agent, Runner
 
# 定义专门的 Agent
billing_agent = Agent(
    name="账单助手",
    instructions="处理账单、退款、付款相关问题",
    tools=[check_balance, process_refund]
)
 
tech_agent = Agent(
    name="技术支持",
    instructions="解决技术问题和故障排查",
    tools=[run_diagnostics, search_docs]
)
 
# 路由 Agent
router = Agent(
    name="客服路由",
    instructions="将用户请求转给合适的专员",
    handoffs=[billing_agent, tech_agent]
)
 
# 运行
result = Runner.run(router, "我的账户被多扣费了")

这个例子展示了框架的核心价值：用不到 20 行代码定义一个能处理多种请求的智能路由系统。

OpenAI Agents Python 的出现表明 OpenAI 正在从"提供模型"向"提供完整 Agent 基础设施"转变。对于已经深度使用 OpenAI 生态的团队，这个框架提供了一条低摩擦的 Agent 化路径。它的极简哲学可能不适合所有场景，但对于快速构建和原型验证，它是当前最优的选择之一。