OpenAI Agents Python SDK

OpenAI Agents (Python) 项目介绍

版本基线: v0.17.4 · 6d5b888f · 2025 年末发布

项目定位

OpenAI 官方的 Python 多 Agent 编排 SDK——轻量但功能完整，从单 Agent 函数调用到多 Agent Handoff、沙箱执行、人类在环（HITL）、对话压缩与 OpenAI 原生 Tracing 全覆盖。

一句话：用最少的 API 层抽象，构建可在生产环境中运行的多 Agent 工作流。

核心能力

能力	说明
Agent 核心循环	`Runner.run()` 驱动的 turn-based 循环，支持同步/异步/流式三种模式，默认 10 turn 上限，自动工具规划与执行
Handoffs 多 Agent	Agent 间通过工具调用式 handoff 转移控制权，支持历史嵌套压缩、输入过滤、结构化输入校验
Agents as Tools	Agent 可作为 FunctionTool 被其他 Agent 调用，调用方拿回结果后继续对话，不转移控制权
工具系统	`FunctionTool`（自动 Pydantic 类型推导 + strict JSON schema）、Hosted MCP、Shell、Computer、Code Interpreter、ApplyPatch、ToolSearch 等 12 种工具类型
Guardrails 护栏	输入/输出/工具三级 guardrails，支持 tripwire 触发即中断的阻断模式，首轮输入 guardrail 可与模型调用并行执行
记忆与 Session	SQLite、OpenAI Conversations API、文件级 session 三种持久化方案，内置自动对话压缩（responses.compact）
沙箱 Agent	预配置容器环境的 Agent，支持 Docker/Modal 后端、Manifest 文件系统描述、Capability 插件系统
Tracing 可观测性	Trace/Span 层次结构，BatchTraceProcessor + BackendSpanExporter 直连 OpenAI Tracing，12 种 span 类型
多模型路由	MultiProvider 前缀路由，支持 OpenAI Responses/ChatCompletions、LiteLLM、AnyLLM，可自定义任意兼容端点
Human-in-the-Loop	工具审批中断 → RunState 序列化 → approve/reject → 恢复执行，支持流式与非流式两种模式
Realtime Agent	WebSocket 连接的实时语音 Agent（v0.17 新增），`gpt-realtime-2` 模型
Voice Pipeline	端到端语音 Agent 管线：STT → LLM → TTS，内置 tracing 支持

技术栈

层	技术
语言	Python 3.10+
核心依赖	Pydantic (数据校验)、Griffe (docstring 解析)、`openai` SDK (底层 API)
可选依赖	`websockets` (WebSocket 传输)、`SQLAlchemy` (数据库 session)、`LiteLLM`/`any-llm` (多模型路由)
构建分发	`uv` / `pip` + `pyproject.toml`，PyPI 分发
测试	pytest + inline snapshot (pytest-snapshot)
类型检查	mypy + pyright
文档	MkDocs Material

架构概览

快速体验

pip install openai-agents

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="你是一个乐于助人的助手。",
)
result = Runner.run_sync(agent, "你好，请介绍一下自己。")
print(result.final_output)

教程导读

本教程分为 AI 应用通用知识 与 编程核心技术 两部分，覆盖以下内容：

AI 篇（6 章）

章节	核心知识点	Common 引用
01	Agent 核心循环与事件流	Agent 核心循环设计
02	工具系统四层架构	工具调用协议与执行模型
03	Handoffs 与多 Agent 协作	多 Agent 路由与隔离
04	记忆、Session 与对话压缩	记忆系统设计
05	上下文管理模型路由	上下文压缩与 Token 优化
06	Guardrails 与安全护栏	—

Dev 篇（6 章）

章节	核心知识点
01	项目架构与 `run_internal/` 分层设计
02	异步编程模型与 asyncio 编排
03	沙箱 Agent 与 Manifest/Capability 系统
04	Tracing 可观测性与 OpenAI Tracing 集成
05	构建、测试与分发
06	Realtime Agent 与 Voice 管线