OpenAI Agents SDK：OpenAI 官方多智能体工作流框架完整中文说明

官方信息

项目	说明
项目名称	OpenAI Agents SDK（Python 版）
开源仓库	openai/openai-agents-python
所属公司	OpenAI
PyPI 包	openai-agents
语言要求	Python 3.10 及以上
官方文档	openai.github.io/openai-agents-python
JS/TS 版	openai/openai-agents-js
开源协议	源码公开，贡献见 CONTRIBUTING.md

OpenAI Agents SDK 官方图

项目背景

OpenAI Agents SDK 是一个轻量但功能强大的框架，用于构建多智能体工作流。它的设计哲学是"轻量、可组合、不锁定"：虽然由 OpenAI 出品，但它是模型无关（provider-agnostic）的，既支持 OpenAI 的 Responses API 和 Chat Completions API，也通过 any-llm、LiteLLM 等适配层支持 100 多个其他大模型。这意味着你可以用同一套 API 先在 OpenAI 模型上开发，再平滑切到其他厂商的模型。

SDK 把"智能体"抽象成一组核心概念：Agent（带指令、工具、护栏的 LLM）、工具调用、 handoff（把任务交给另一个智能体）、护栏（输入输出安全检查）、人在回路、会话管理和 Tracing（全链路追踪）。官方提供了配套的 Tracing UI，可以可视化地看到每一次智能体运行的过程，方便调试和优化。

理解这个 SDK 的定位，关键是抓住它和 OpenAI 官方 Playground、和其他智能体框架的区别：它不是一个"在线服务配置台"，而是一个可以嵌入你自己 Python 程序的库。你写的每一行业务代码，都可以在任意位置 import agents，然后构造一个 Agent、用 Runner 跑起来。它刻意保持轻量——不强制你用特定的目录结构、不强制你用特定的前端、也不强制你把数据存到特定数据库——但又把多智能体协作、工具调用、会话记忆这些常见需求做成了内置一等公民。

核心概念（Core Concepts）

官方文档列出的核心概念如下，逐条说明：

Agents（智能体）：配置了指令、工具、护栏和 handoff 能力的 LLM。详见 Agents 文档。
Sandbox agents（沙箱智能体）：预先配置为在容器中工作的智能体，适合需要长时间跨度、读写文件、执行命令的任务。详见 Sandbox agents。
Realtime agents（实时语音智能体）：基于 gpt-realtime-2.1 构建低延迟语音和多模态智能体，具备完整智能体能力。详见 Realtime 快速开始。
Voice agents（语音智能体）：构建语音管线，串联语音识别、智能体工作流和语音合成。详见 Voice 快速开始。
Agents as tools / Handoffs（智能体即工具 / 任务交接）：把任务委派给其他智能体完成特定子任务。详见 Tools 与 Handoffs。
Tools（工具）：让智能体可以采取行动的各种能力，包括函数工具、MCP 工具和托管工具。详见 Tools。
Guardrails（护栏）：可配置的安全检查，用于输入和输出校验。详见 Guardrails。
Human in the loop（人在回路）：在内置机制中让人类参与到智能体运行过程中。详见 Human in the loop。
Sessions（会话）：跨多次智能体运行自动管理对话历史。详见 Sessions。
Tracing（追踪）：内置的智能体运行追踪，让你可以查看、调试和优化工作流。详见 Tracing。

更多可运行的例子见仓库的 examples 目录。

这组概念可以按"做什么"和"怎么管"分成两类。做什么的一类是：Agent 本身、Tools、Handoffs、Guardrails——它们决定智能体能不能干活、干什么活、出错时怎么兜底。怎么管的一类是：Sessions、Tracing、Human in the loop——它们决定多次运行之间状态怎么衔接、运行过程怎么观察、人在什么时候介入。Sandbox、Realtime、Voice 则是三种特殊的运行形态，分别对应"要文件系统""要低延迟语音""要自己控制音频管线"三种典型业务场景。理解了这张概念地图，再去读 examples 目录里的代码，就不会觉得每个例子都是孤立的魔法。

其中 Tracing 尤其值得单独提：很多智能体项目调试起来最痛苦的地方，是模型明明给了一个奇怪的答案，你却不知道它中间调了哪个工具、看到了什么上下文。OpenAI Agents SDK 把每一次运行的全链路自动记录下来，你可以在 UI 里逐层展开看：模型这一轮的输入是什么、工具返回了什么、handoff 发生在哪一步，从而把"黑盒"变成"白盒"。

环境要求与安装

SDK 要求 Python 3.10 或更新版本。运行任何示例前，先设置环境变量 OPENAI_API_KEY。如果你用的是其他厂商的模型，则按对应适配层（any-llm 或 LiteLLM）的要求配置对应的 API Key。

方式一：venv + pip

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install openai-agents

如果需要语音能力，安装可选的 voice 依赖组：

pip install 'openai-agents[voice]'

如果需要 Redis 会话支持，安装可选的 redis 依赖组：

pip install 'openai-agents[redis]'

方式二：uv

如果你熟悉 uv，安装会更简单：

uv init
uv add openai-agents

同样，语音支持用 uv add 'openai-agents[voice]'，Redis 会话支持用 uv add 'openai-agents[redis]'。

运行你的第一个智能体

SDK 提供四种主要的运行方式：文本智能体、沙箱智能体、实时语音智能体和语音管线智能体。

运行一个文本智能体

对于不需要持久实时连接、也不需要沙箱工作区的工作流，用最普通的文本 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)

# Code within the code,
# Functions calling themselves,
# Infinite loop's dance.

这里 Runner.run_sync 是同步入口，传入智能体和用户输入，返回结果对象，result.final_output 就是模型的最终回复。这个例子让智能体写一首关于"编程中的递归"的俳句。Jupyter notebook 用户可以参考官方示例 examples/basic/hello_world_jupyter.ipynb。

为什么把"运行"和"定义"分成 Agent 和 Runner 两个对象？这是因为同一个 Agent 可以被反复运行、可以被传给多个 Runner、也可以被注册成别的智能体的工具；而 Runner 才负责具体一次运行时的模型选择、上下文传递、工具执行和追踪记录。这种分离让智能体定义可以复用、测试和版本管理。

运行一个沙箱智能体

当智能体需要检查文件、运行命令、打补丁，或者需要在较长任务中保留工作区状态时，使用 SandboxAgent。下面的例子用 UnixLocalSandboxClient，它支持 macOS 和 Linux；Windows 用户应改用 DockerSandboxClient（需要安装 openai-agents[docker]）或托管沙箱客户端，详见 Sandbox clients。

from agents import Runner
from agents.run import RunConfig
from agents.sandbox import Manifest, SandboxAgent, SandboxRunConfig
from agents.sandbox.entries import GitRepo
from agents.sandbox.sandboxes import UnixLocalSandboxClient

agent = SandboxAgent(
    name="Workspace Assistant",
    instructions="Inspect the sandbox workspace before answering.",
    default_manifest=Manifest(
        entries={"repo": GitRepo(repo="openai/openai-agents-python", ref="main")}
    ),
)

result = Runner.run_sync(
    agent,
    "Inspect the repo README and summarize what this project does.",
    run_config=RunConfig(sandbox=SandboxRunConfig(client=UnixLocalSandboxClient())),
)
print(result.final_output)

这个例子把 openai/openai-agents-python 仓库的 main 分支挂载到沙箱里，让智能体自己去读 README 并总结项目是做什么的。和普通文本智能体的区别在于：它真的有一个文件系统可以操作，并且这个文件系统是隔离的。

Manifest（清单）用来声明这个沙箱一开始应该有什么内容——例子里通过 GitRepo 把一个 GitHub 仓库克隆进来；RunConfig 则在运行时指定用哪个沙箱客户端。这种设计让智能体可以放心地执行代码、写文件、跑命令，而不会污染你本机的目录，也不会把不同任务之间的状态搞混。

运行一个实时语音智能体

通过 WebSocket 提供低延迟、服务端的语音和多模态体验，使用 RealtimeAgent：

import asyncio
from agents.realtime import RealtimeAgent, RealtimeRunner


async def main() -> None:
    agent = RealtimeAgent(
        name="Assistant", instructions="You are a helpful voice assistant. Keep responses short."
    )
    runner = RealtimeRunner(starting_agent=agent)
    session = await runner.run()

    async with session:
        await session.send_message("Say hello in one short sentence.")
        async for event in session:
            if event.type == "audio":
                # Forward or play event.audio.data.
                pass
            elif event.type == "history_added":
                print(event.item)
            elif event.type == "agent_end":
                break


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

实时语音智能体走的是全双工 WebSocket 通道，模型可以边听边说，延迟远低于"录音→识别→文本对话→合成"的串管线。代码里通过 async for event in session 流式接收事件，audio 事件就是模型输出的音频数据，history_added 是对话历史更新，agent_end 表示这一轮结束。

这种方式适合做语音助手、客服电话、会议记录这类要求"开口即答"的场景；因为是异步事件流，你可以把 audio 事件直接转发给扬声器，也可以在中间加一层降噪或情感识别。

运行一个语音管线智能体

如果你想自己控制音频输入输出，用 VoicePipeline 把音频转成文本、跑智能体工作流、再把生成的语音流式播放出来：

import asyncio

import numpy as np

from agents import Agent
from agents.voice import AudioInput, SingleAgentVoiceWorkflow, VoicePipeline


async def main() -> None:
    agent = Agent(name="Assistant", instructions="You are a helpful voice assistant.")
    pipeline = VoicePipeline(workflow=SingleAgentVoiceWorkflow(agent))
    audio_input = AudioInput(buffer=np.zeros(24000 * 3, dtype=np.int16))

    result = await pipeline.run(audio_input)
    async for event in result.stream():
        if event.type == "voice_stream_event_audio":
            # Forward or play event.data.
            pass


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

和实时智能体的区别是：VoicePipeline 是"识别→智能体→合成"的串管线，你可以自己喂音频 buffer（例子里用 np.zeros(24000*3) 模拟 3 秒静音），也可以自己处理每一段输出音频，灵活性更高。

这种方式适合你已经有自己的语音识别或合成服务、想把中间的"大脑"换成智能体工作流的场景；也适合做离线批处理——先把录音文件准备好，再一段段喂给管线，不必一直开着 WebSocket。

常见问题（FAQ）

问：必须用 OpenAI 的模型吗？ 答：不是。SDK 支持 OpenAI Responses API 和 Chat Completions API，同时通过 any-llm、LiteLLM 适配层支持 100 多个其他 LLM，可以在不改动业务代码的前提下切换模型。

问：Windows 下能用沙箱智能体吗？ 答：UnixLocalSandboxClient 只支持 macOS 和 Linux。Windows 用户需要安装 openai-agents[docker]，改用 DockerSandboxClient，或者使用托管沙箱客户端。

问：语音能力需要额外安装什么？ 答：安装 openai-agents[voice] 可选依赖组；如果要用 Redis 做跨会话状态，再装 openai-agents[redis]。

问：怎么调试智能体到底做了什么？ 答：SDK 内置 Tracing 功能，会自动记录每一次运行的全过程，并在官方 Tracing UI 中可视化展示，包括每一步工具调用、handoff、中间输出，方便定位是哪一步出了问题。

问：支持把任务交给另一个智能体吗？ 答：支持，这就是 Handoffs（或"智能体即工具"）：你可以把一个智能体注册成另一个智能体的工具，由模型决定什么时候该把任务转交给更专精的同事。

问：怎么防止智能体被诱导说出不该说的话？ 答：用 Guardrails（护栏）机制，对输入和输出做可配置的校验；高风险操作还可以配 Human in the loop，让人在关键节点点头确认。

问：多轮对话的历史要不要自己维护？ 答：不需要。Sessions 功能会自动跨多次运行管理对话历史；如果你想把会话持久化到 Redis，安装 openai-agents[redis] 即可，这样服务重启后对话上下文也不丢。

问：我能接自己写的函数当工具吗？ 答：可以。把 Python 函数加上类型标注，SDK 会自动生成工具描述并在模型要求时调用；除了函数工具，还可以通过 MCP 协议接入外部工具服务器，或使用 OpenAI 托管工具。

问：这个 SDK 和 OpenAI 官方的 Agents in API 是什么关系？ 答：SDK 是对 OpenAI 智能体能力的 Python 封装，你写的是本地 Python 代码，但可以调用 OpenAI 的 Responses API 作为后端；同时它又不锁定 OpenAI，通过适配层可以跑其他模型。它定位是"开发者在自己代码里编排智能体"的库，不是云端托管服务。

问：语音能力和实时能力有什么区别？ 答：RealtimeAgent 走 WebSocket 全双工通道，模型边听边说，延迟最低，适合实时对话；VoicePipeline 是"语音识别→文本智能体→语音合成"的串管线，你完全掌控音频输入输出，可以接到自己的录音设备或播放器上。两者按场景选。

适用场景与学习建议

综合来看，OpenAI Agents Python SDK 适合这几类需求：一是需要在自己 Python 后端里嵌入"会调工具、会多步推理"的智能体，而不是用一个在线服务；二是需要做多智能体协作，让一个主智能体把任务 handoff 给专家智能体；三是需要沙箱隔离执行代码或操作文件；四是要做语音助手或语音管线。对中文开发者，建议先从 examples 里的 hello_world 跑起，再依次试工具调用、handoff、guardrail，最后再碰 sandbox 和 voice 这两个需要额外环境的高级能力。

贡献与致谢

bug 报告和特性请求通过 GitHub Issues 提交；Pull Request 仅限仓库协作者，不接受非协作者的 PR。贡献政策和开发指南见 CONTRIBUTING.md，安全漏洞披露见 SECURITY.md。

这一点和很多开源项目不同：OpenAI 出于代码治理考虑，只接受内部协作者的 PR，但外部用户仍然可以通过 Issue 报告 bug、提需求，并且官方明确表示会持续把 Agents SDK 作为开源框架维护下去，让社区在他们这套思路上继续扩展。

官方致谢了开源社区的优秀工作：Pydantic、Requests、MCP Python SDK、Griffe。可选依赖包括 websockets、SQLAlchemy、any-llm 和 LiteLLM。项目管理工具使用 uv、ruff、mypy、Pyright、pytest、Coverage.py 和 MkDocs。

跳转链接

开源仓库：openai/openai-agents-python
官方文档：openai.github.io/openai-agents-python
PyPI：openai-agents
JS/TS 版：openai/openai-agents-js
示例目录：examples
问题反馈：GitHub Issues

OpenAI Agents SDK：OpenAI 官方多智能体工作流框架