SDK OpenAI-Agents 官方轻量多智能体工作流开发框架

在自己的应用里接 AI，多数人的路径是直接调模型 API：自己管对话历史、自己拼工具调用、自己处理多智能体交接，几十行代码之外还有一堆边界情况——重试、护栏、人工介入、追踪调试。OpenAI 2025 年把内部智能体框架 Swarm 的经验沉淀成正式产品开源出来，就是 OpenAI Agents SDK（Python 版）：一个轻量但功能完备的多智能体工作流框架。官方对它的描述是「轻量而强大」，实际用下来的感受是「概念少、原语全」——智能体、工具、交接、护栏、会话、追踪，每个概念都直接可用，不逼你先学一套抽象。

项目采用 MIT 协议，Python 编写，当前版本 v0.24.0，最近更新 2026 年 10 月 22 日，GitHub 星数超过 3 万。它同时保持对供应商的开放：除 OpenAI 的 Responses 和 Chat Completions API 外，还通过兼容层支持一百多家大模型，不是绑定闭环。

项目基本信息

一、项目介绍

SDK 的核心原语覆盖了智能体应用的全生命周期。智能体（Agents）由指令、工具、护栏和交接规则配置而成；工具体系支持普通函数、MCP 服务器和托管工具；「智能体即工具」和交接（handoffs）两种模式让多智能体分工成为语言级特性——前者把子智能体当函数调，后者把对话控制权整个移交。护栏（guardrails）管输入输出校验，human-in-the-loop 提供人工介入机制，会话（sessions）自动管理跨轮次历史，追踪（tracing）内建运行可视化。

针对重场景它给了专门形态：沙箱智能体（SandboxAgent）预置容器环境，适合需要读文件、跑命令、打补丁的长周期任务，Windows 上用 Docker 客户端；实时智能体（RealtimeAgent）走 WebSocket 做低延迟语音和多模态；语音管线把语音识别、智能体工作流、语音合成串起来。JS/TS 版本独立成仓，前后端可用同一套概念。

二、核心优势

第一，官方血统加生产验证。它是 Swarm 实验框架的正式化产物，OpenAI 自家产品在用，API 设计经过真实场景打磨，不是社区玩具。

第二，抽象克制。没有层层封装的框架感，核心概念一个下午能学完；示例仓库覆盖从 hello world 到复杂工作流的完整梯度。

第三，多智能体是一等公民。交接和「智能体即工具」两种模式覆盖了绝大多数分工场景，写起来就是几行代码。

第四，可观测性内建。追踪不用接第三方SDK，运行过程、工具调用、耗时直接可视，调试体验和智能体开发的生产需求对齐。

第五，不锁供应商。OpenAI 模型是默认推荐，但一百多家模型通过兼容层可用；TypeScript 版本同步演进，全栈团队概念统一。

三、适用场景

应用内嵌 AI 功能：客服、审批、数据查询，用智能体加工具加护栏快速搭。多智能体工作流：研究、写作、代码等多角色协作，用 handoffs 编排。长周期任务：沙箱智能体在容器里读写文件、执行命令。语音产品：实时智能体加语音管线做语音助手。客服与审批流：护栏加 human-in-the-loop 保证关键决策有人把关。智能体系统教学：概念清晰、示例丰富，是学习多智能体设计的优质教材。

四、安装教程

创建虚拟环境后安装（Python 3.10 以上）：

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

用 uv 更省事：

uv init
uv add openai-agents

语音功能装扩展：pip install 'openai-agents[voice]'；Redis 会话支持：pip install 'openai-agents[redis]'。运行前设置环境变量：

export OPENAI_API_KEY=sk-...

常见报错：其一，沙箱智能体在 Windows 上报错——UnixLocalSandboxClient 只支持 macOS 和 Linux，Windows 需用 DockerSandboxClient（装 openai-agents[docker] 扩展）或托管沙箱客户端。其二，语音示例跑不起来——确认装的是 openai-agents[voice] 而非基础包。其三，追踪面板看不到数据——确认没有禁用追踪，且网络能访问追踪服务。其四，换用第三方模型报错——通过兼容层配置 base URL 和 key，参考文档的模型提供商章节。

五、使用示例

最小可运行例子，一个会写俳句的智能体：

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.——指令、执行、拿结果三步完成。

多智能体分工：先定义一个普通函数当工具，再建研究智能体和写作智能体，用 handoffs 串成流水线：

from agents import Agent, Runner, function_tool

@function_tool
def get_topic_notes(topic: str) -> str:
    """返回某个主题的调研要点"""
    return "向量数据库：语义检索、混合查询、生态工具链三条主线"

researcher = Agent(
    name="Researcher",
    instructions="调研给定主题，先调用工具拿要点，再整理成清单",
    tools=[get_topic_notes],
)

writer = Agent(
    name="Writer",
    instructions="把调研要点扩写成通俗短文",
    handoffs=[researcher],
)

result = Runner.run_sync(writer, "写一篇关于向量数据库的科普")
print(result.final_output)

运行时 writer 发现需要素材，交接给 researcher；researcher 调用 get_topic_notes 拿到要点后整理返回，控制权交回 writer 完成成文。运行过程在追踪面板里可见：哪次交接、调了哪些工具、每步耗时。要加安全边界，给智能体配护栏；关键步骤要人确认，用 human-in-the-loop 原语——都不需要引入额外库。

六、常见问题

问：必须用 OpenAI 模型吗？答：不是。默认走 OpenAI，兼容层支持一百多家模型；想用 Claude 或本地模型按文档配置即可。

问：和 LangChain 怎么选？答：SDK 更轻、原语更少、多智能体是一等公民，适合以 OpenAI 生态为中心或想快速起步；LangChain 生态组件更多，适合复杂集成。两者也常被混用。

问：追踪数据存在哪？答：默认走 OpenAI 的追踪服务，可自托管或按需配置，敏感流量先读文档确认数据流向。

问：沙箱智能体适合什么任务？答：需要读写文件、执行 shell、跨长周期保持工作区状态的任务，比如自动修 bug、批量处理仓库；短对话用普通智能体即可。

七、总结

OpenAI Agents SDK 的价值在于「刚刚好」：抽象足够轻，概念一个下午学完；原语足够全，工具、交接、护栏、人工介入、会话、追踪、沙箱、语音都在框架内；加上官方维护和生产背书、MIT 协议、多供应商兼容，它同时适合快速原型和生产部署。对正在把 AI 嵌进应用的团队，它省掉的是「重造智能体轮子」的几周工作量；对学习者，它的示例仓库和追踪面板是理解多智能体设计的最佳教材。如果只选一个 Python 多智能体框架入门，它是当前风险最低的选择。