OpenAI Agents Python 项目详细介绍

项目概述

OpenAI Agents SDK 是一个轻量级且功能强大的Python多智能体工作流构建框架。这是OpenAI官方发布的生产级智能体开发工具，是对之前实验性项目Swarm的升级版本。该框架设计简洁但功能完备，专门用于构建复杂的多智能体AI应用。

核心特性

1. 跨平台兼容性

• 模型无关性：支持OpenAI的Responses和Chat Completions API
• 广泛兼容：支持100+种不同的大语言模型
• API灵活性：可以轻松切换不同的AI服务提供商

2. 核心组件

智能体（Agents）

• 配置了指令、工具、安全防护和交接机制的LLM实例
• 每个智能体都有明确的职责和能力边界
• 支持自定义指令和行为模式

交接机制（Handoffs）

• 专门的工具调用机制，用于在智能体之间转移控制权
• 实现智能体间的无缝协作
• 支持复杂的工作流编排

安全防护（Guardrails）

• 可配置的输入输出验证安全检查
• 确保AI应用的安全性和可靠性
• 防止恶意输入和不当输出

流程追踪（Tracing）

• 内置的智能体运行跟踪功能
• 支持查看、调试和优化工作流
• 可扩展的追踪系统，支持多种外部集成

技术架构

安装与配置

# 创建Python虚拟环境
python -m venv env
source env/bin/activate

# 安装基础版本
pip install openai-agents

# 安装包含语音支持的版本
pip install 'openai-agents[voice]'

基础使用示例

简单智能体

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)

多语言协作智能体

from agents import Agent, Runner
import asyncio

spanish_agent = Agent(
    name="Spanish agent",
    instructions="You only speak Spanish.",
)

english_agent = Agent(
    name="English agent", 
    instructions="You only speak English",
)

triage_agent = Agent(
    name="Triage agent",
    instructions="Handoff to the appropriate agent based on the language of the request.",
    handoffs=[spanish_agent, english_agent],
)

async def main():
    result = await Runner.run(triage_agent, input="Hola, ¿cómo estás?")
    print(result.final_output)

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

工具调用示例

import asyncio
from agents import Agent, Runner, function_tool

@function_tool
def get_weather(city: str) -> str:
    return f"The weather in {city} is sunny."

agent = Agent(
    name="Weather Assistant",
    instructions="You are a helpful weather agent.",
    tools=[get_weather],
)

async def main():
    result = await Runner.run(agent, input="What's the weather in Tokyo?")
    print(result.final_output)

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

工作流执行机制

运行循环逻辑

1. LLM调用：使用智能体的模型和设置，结合消息历史进行调用
2. 响应处理：LLM返回响应，可能包含工具调用
3. 输出检查：如果有最终输出，返回并结束循环
4. 交接处理：如果有交接请求，切换到新智能体并重新开始
5. 工具执行：处理工具调用并将响应添加到消息中，然后重新开始循环

最终输出机制

• 结构化输出：如果设置了output_type，当LLM返回匹配类型的内容时结束
• 文本输出：如果没有output_type，当智能体产生没有工具调用或交接的消息时结束

工具系统

三类工具支持

1. 托管工具（Hosted Tools）

• 在LLM服务器上运行
• OpenAI提供检索、网络搜索和计算机使用等托管工具

2. 函数调用（Function Calling）

• 支持将任何Python函数用作工具
• 灵活的自定义工具开发

3. 智能体作为工具

• 允许智能体调用其他智能体
• 支持复杂的层级协作结构

内置工具

• WebSearchTool：网络搜索功能
• Computer Use：计算机操作能力
• Retrieval：信息检索功能

追踪与监控

自动追踪功能

• 自动跟踪智能体运行过程
• 便于调试和优化工作流
• 可扩展的设计支持自定义span

外部集成支持

• Logfire：日志管理
• AgentOps：智能体操作监控
• Braintrust：AI应用开发平台
• Scorecard：性能评估
• Keywords AI：关键词AI集成

应用场景

适用场景

• 复杂业务流程自动化：多步骤的业务处理流程
• 多语言客服系统：支持不同语言的智能客服
• 专业领域助手：法律、医疗、教育等专业领域的AI助手
• 数据处理流水线：多阶段的数据分析和处理
• 创意协作系统：多个AI角色协作完成创意任务

工作流模式

• 确定性流程：预定义的工作流步骤
• 迭代循环：需要多次迭代优化的任务
• 条件分支：根据条件选择不同处理路径
• 并行处理：多个智能体同时处理不同任务

开发环境

开发要求

• Python 3.8+
• 需要设置OPENAI_API_KEY环境变量
• 支持异步和同步两种调用方式

开发工具链

# 安装uv包管理器
uv --version

# 安装依赖
make sync

# 运行测试
make tests

# 类型检查
make mypy

# 代码规范检查
make lint

项目优势

1. 简洁设计

• 极少的抽象层次
• 核心概念清晰明确
• 易于理解和使用

2. 生产就绪

• 基于OpenAI的实际经验构建
• 稳定可靠的API设计
• 完善的错误处理机制

3. 高度灵活

• 支持复杂的智能体关系建模
• 可以表达各种工作流模式
• 强大的自定义能力

总结

OpenAI Agents Python是一个专业级的多智能体开发框架，它将复杂的AI协作变得简单易用。通过其核心的智能体、交接、防护和追踪机制，开发者可以快速构建出功能强大的AI应用系统。无论是简单的单智能体任务还是复杂的多智能体协作场景，这个框架都能提供优雅的解决方案。