OpenAI 官方 Agent SDK 来了：22k Star，支持 100+ 模型，Python 10 行代码上手

OpenAI 官方 Agent SDK 来了：22k Star，支持 100+ 模型，Python 10 行代码上手

等了一年多，OpenAI 终于给出了官方的 Agent 答案——不是 Swam 那个实验品，是一个正经的、生产级的 SDK。openai-agents-python，22k Star，MIT 协议，v0.14.2，迭代速度很快（最近一个月发了 5 个版本）。

最让我意外的是：它不绑定 OpenAI 自己的模型，支持 100+ LLM。这不像 OpenAI 的风格。

本文提纲

1. 这个 SDK 到底是什么
2. 核心概念：Agent、Handoff、Guardrail
3. Sandbox Agent：能操作文件系统的新物种
4. 跟 LangChain、CrewAI 有什么不同
5. 10 行代码跑起来
6. 值不值得用

这个 SDK 到底是什么

一句话：OpenAI 官方出的轻量级 Multi-Agent 框架。

它解决的问题是——怎么用 Python 把多个 LLM Agent 串起来协同工作。跟 LangChain 那种"什么都包"的思路不同，OpenAI Agents SDK 只做几件事，但做得干净：

• Agent 定义：指令 + 工具 + Handoff + Guardrail
• Agent 协作：Handoff（交接）和 Agent-as-Tool（Agent 当工具用）
• 安全护栏：输入/输出 Guardrail，支持 LLM 做判断
• Human-in-the-loop：内置的人机交互机制
• Tracing：内置追踪和调试 UI
• Realtime Agent：支持 gpt-realtime-1.5 做语音 Agent
• Sandbox Agent：v0.14.0 新增，Agent 可以操作文件系统和容器

安装就一行：

pip install openai-agents

语音支持加个 voice 分组，Redis Session 支持加个 redis 分组。

核心概念：Agent、Handoff、Guardrail

Agent：一切的基础

一个 Agent 就是 LLM + 指令 + 工具的组合：

from agents import Agent, Runner

agent = Agent(
    name="Assistant",
    instructions="You only respond in haikus.",
)

result = await Runner.run(agent, "Tell me about recursion in programming.")
print(result.final_output)
# Function calls itself,
# Looping in smaller pieces,
# Endless by design.

就这么简单。Runner.run() 是异步的，也有同步版本 Runner.run_sync()。

Handoff：Agent 之间怎么交接

Handoff 是 Multi-Agent 的核心机制——一个 Agent 觉得自己搞不定，把任务转给另一个更合适的 Agent：

from agents import Agent, Runner

spanish_agent = Agent(
    name="spanish_agent",
    instructions="You translate the user's message to Spanish",
    handoff_description="An english to spanish translator",
)

french_agent = Agent(
    name="french_agent",
    instructions="You translate the user's message to French",
    handoff_description="An english to french translator",
)

orchestrator = Agent(
    name="orchestrator",
    instructions="You are a translation agent. You use the tools given to you to translate.",
    tools=[
        spanish_agent.as_tool(tool_name="translate_to_spanish", tool_description="..."),
        french_agent.as_tool(tool_name="translate_to_french", tool_description="..."),
    ],
)

这里有两种模式：
- Handoff：Agent A 把控制权完全交给 Agent B
- Agent-as-Tool：Agent A 调用 Agent B 当工具用，拿到结果后继续自己的流程

两种模式适用不同场景。Handoff 适合"接力赛"，Agent-as-Tool 适合"指挥官模式"。

Guardrail：安全护栏

Guardrail 是跑在 Agent 执行旁边的并行检查，不阻塞主流程，但可以中断执行：

from pydantic import BaseModel
from agents import Agent, GuardrailFunctionOutput, input_guardrail

class MathHomeworkOutput(BaseModel):
    reasoning: str
    is_math_homework: bool

guardrail_agent = Agent(
    name="Guardrail check",
    instructions="Check if the user is asking you to do their math homework.",
    output_type=MathHomeworkOutput,
)

@input_guardrail
async def math_guardrail(context, agent, input):
    result = await Runner.run(guardrail_agent, input, context=context.context)
    final = result.final_output_as(MathHomeworkOutput)
    return GuardrailFunctionOutput(
        output_info=final,
        tripwire_triggered=final.is_math_homework,
    )

用 Pydantic Model 定义输出结构，用 LLM 做判断，tripwire_triggered=True 就会中断 Agent 执行。输入和输出都可以加 Guardrail。

Sandbox Agent：能操作文件系统的新物种

v0.14.0 新增的 Sandbox Agent 是这个 SDK 最大的亮点之一。普通 Agent 只能调用 API 和函数，Sandbox Agent 可以操作真实的文件系统：

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)

这个 Agent 能：
- 克隆 Git 仓库到沙箱
- 读取和检查文件
- 运行命令
- 应用 patch
- 在长时间任务中保持工作区状态

本质上就是一个有文件系统和执行环境的 Agent，跟 Claude Code 的能力很像。

跟 LangChain、CrewAI 有什么不同

我列个表：

特性	OpenAI Agents SDK	LangChain/LangGraph	CrewAI
定位	轻量 Agent 框架	全栈 LLM 框架	Multi-Agent 编排
学习曲线	低，概念少	高，概念非常多	中等
模型支持	100+ LLM（via any-llm/LiteLLM）	100+ LLM	OpenAI + 部分
核心抽象	Agent + Handoff	Chain/Graph/Tool	Crew + Task + Agent
Sandbox	内置	无	无
Realtime/Voice	内置	需额外集成	无
Guardrail	内置	需自己实现	无
Tracing	内置	LangSmith（付费）	无
代码量	10 行 Hello World	30+ 行 Hello World	20+ 行
许可证	MIT	MIT	MIT

几个关键区别：

1. 概念极简

OpenAI Agents SDK 的核心概念只有 Agent、Runner、Handoff、Guardrail、Tool 五个。LangChain 光是 Chain 就有 LLMChain、SequentialChain、RouterChain……学完文档就累了。

2. 不绑定 OpenAI

这一点最出乎意料。SDK 底层使用 any-llm 和 LiteLLM，支持 OpenAI Responses API、Chat Completions API，以及其他 100+ 模型。用 Claude、Gemini、DeepSeek 都行。

3. Sandbox Agent 是杀手级功能

能操作文件系统和容器的 Agent，目前其他框架都没有开箱即用的支持。这让 Agent 从"只能调 API"进化到了"能做实际工作"。

4. Tracing 免费

LangChain 的 LangSmith 追踪要付费。OpenAI Agents SDK 内置 Tracing，开箱即用，不收钱。

10 行代码跑起来

最快的上手方式：

# 安装
pip install openai-agents

# 设置 API Key（支持任何 OpenAI 兼容的 Key）
export OPENAI_API_KEY=sk-...

import asyncio
from agents import Agent, Runner

async def main():
    agent = Agent(name="Assistant", instructions="You only respond in haikus.")
    result = await Runner.run(agent, "Tell me about recursion in programming.")
    print(result.final_output)

asyncio.run(main())

跑起来。官方 examples 目录有 15+ 场景的完整示例，从 basic 到 customer_service 到 financial_research_agent，拿来就能改。

值不值得用

适合用的场景：

• 需要快速搭建 Multi-Agent 原型，不想学 LangGraph 那套复杂概念
• 需要 Sandbox 能力（文件操作、命令执行）
• 需要 Voice/Realtime Agent
• 团队用 Python，追求简单直接

不太适合的场景：

• 需要非常复杂的 DAG 编排（LangGraph 更灵活）
• 需要 RAG pipeline（LangChain 的文档加载器更丰富）
• 已有 LangChain 生态的大量代码，迁移成本高

我的判断：如果你是刚开始做 Agent 开发，OpenAI Agents SDK 是目前最好的起点。概念少、代码干净、文档清晰，而且有 OpenAI 团队持续维护。22k Star 说明社区也认可。

项目地址：github.com/openai/openai-agents-python

文档：openai.github.io/openai-agents-python

---

作者: itech001
来源: 公众号：AI人工智能时代
主页: https://www.theaiera.cn，每日分享最前沿的AI新闻和技术。

本文首发于 AI人工智能时代，转载请注明出处。