OpenAI Agents SDK翻译站点

OpenAI Agents SDK 是 OpenAI 推出的轻量级、生产就绪的多智能体工作流框架，它是 OpenAI 早前实验性项目 Swarm 的生产级升级版 。

SDK 的设计哲学是”足够好用但原语极少“——只有 Agent、Handoffs、Guardrails 等少量核心概念，开发者用常规 Python/TypeScript 代码即可编排复杂多智能体关系，无需学习新的图抽象或 DSL 。

它适合需要运行时管理多轮对话、工具执行、护栏校验、智能体交接、会话保持的 Agent 应用。

 

产品概述

OpenAI Agents SDK 于 2026 年初作为独立库发布，脱离 Assistants API 体系，采用 MIT 开源协议 。框架提供 Python（3.10+）与 JavaScript/TypeScript（Node.js 22+）双语言版本，两者共享相同的核心概念 。SDK 默认使用 OpenAI Responses API 调用模型，但通过 LiteLLM 等适配层支持 100+ 其他 LLM 。

v0.14.0 起引入 Sandbox Agents（沙箱智能体），支持在隔离的容器/文件系统工作区中执行长时间任务 。截至 2026 年 4 月，PyPI 最新版本 0.14.2，GitHub 约 19.4K Star 。

 

核心能力

• Agent（智能体）：配置指令、工具、护栏与交接的 LLM 基本单元
• Handoffs（交接）：SDK 最具代表性的能力——一个智能体可将控制权转移给另一个智能体，接收方继承完整对话历史并接管后续回合；适用于客服路由等场景
• Agents as Tools：与 Handoff 互补的编排模式——主管智能体调用专家智能体作为工具，将专家输出纳入更大的任务（适用于 research → write → review 流水线）
• Guardrails（护栏）：对输入/输出并行运行可编程安全检查，校验不通过时快速失败（fail fast），不增加主流程延迟
• Function Tools：用装饰器将任意 Python 函数转为工具，自动生成 schema 并通过 Pydantic 进行参数校验
• MCP 工具调用：内置 MCP 服务器工具集成，使用方式与 Function Tools 一致
• Sessions（会话）：跨 Agent 运行的自动对话历史管理，持久化记忆层
• Human-in-the-Loop：内置跨 Agent 运行的人类介入机制
• Tracing（追踪）：默认开启，可视化、调试和监控工作流，与 OpenAI 平台的评估、微调、蒸馏工具联动
• Realtime Agents：基于 gpt-realtime 构建语音智能体，支持自动中断检测、上下文管理与护栏
• Sandbox Agents：为智能体预配置容器/工作区，适用于需要检查文件、运行命令、应用补丁或在长时间任务中保持工作区状态的场景

 

优势亮点

• 原语极简、上手快：核心概念仅 Agent、Handoffs、Guardrails 等少数几个，相比 LangGraph 的 StateGraph/Node/Edge 抽象，学习曲线显著更低
• Python-first 编排：用常规语言特性（对象、函数、控制流）编排智能体，无需学习图 DSL
• Handoffs 是多智能体路由的最佳原语：一个 triage agent 分类请求并交接给 specialist agent，用户对交接无感知，只拿到正确专家的答案
• 护栏并行执行不增延迟：输入/输出护栏与 Agent 执行并行运行，校验失败时快速失败
• Provider-agnostic：默认 OpenAI 模型，但通过 LiteLLM 支持 100+ LLM，Claude 等可通过社区模型适配器接入
• 双语言支持：Python 与 TypeScript 共享同一套概念模型，全栈团队技术栈统一
• OpenAI 平台原生集成：Tracing 自动上报至 OpenAI Dashboard，配合评估、微调、蒸馏工具形成完整闭环
• 生产级迭代快：v0.14 引入 Sandbox Agents，朝”可恢复执行、真实工作区”的生产场景演进

 

短板

• 生态规模不及 LangChain：第三方集成、社区插件、Stack Overflow 答案数量明显少于 LangChain
• 复杂状态编排弱于 LangGraph：对于需要显式图状态管理、循环分支、检查点恢复的极复杂场景，LangGraph 更灵活
• 护栏不覆盖 Handoff 管道：Guardrails 应用于 Function Tools，而 Handoff 管道独立运行——意味着交接本身不受护栏校验保护
• 默认模型绑定 OpenAI：虽然支持 100+ LLM，但默认与最优体验仍绑定 OpenAI Responses API；使用其他模型需借助 LiteLLM 等适配层
• Agent 框架赛道新兵：2026 年初才作为独立库发布，生产案例与最佳实践仍在积累中
• 版本迭代快：作为 0.x 版本项目，API 可能会有 breaking changes

 

适用企业/部门

AI 应用开发团队、后端工程师、全栈团队。特别适合：多智能体路由系统（客服分流、专家分发）、需要 Handoff + Guardrails + Tracing 的生产级 Agent 应用、语音智能体（Realtime Agents）、使用 Python/TypeScript 且希望避免重图抽象的团队、已采用 OpenAI 模型生态的项目。

 

安装教程

前提条件

• Python 3.10 或更高版本（PyPI 要求 Requires: Python >=3.10）
• pip 或 uv 包管理器
• OpenAI API Key

快速安装

# 创建虚拟环境（推荐）
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 安装核心包
pip install openai-agents

# 语音支持（可选）
pip install 'openai-agents[voice]'

# Redis 会话支持（可选）
pip install 'openai-agents[redis]'

# 沙箱支持（可选，Windows 下使用 Docker 沙箱客户端）
pip install 'openai-agents[docker]'

使用 uv：

uv init
uv add openai-agents

验证安装：Hello World

import asyncio
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)

运行前设置 API Key：

export OPENAI_API_KEY=sk-...

多智能体交接（Handoff）示例

import asyncio
from agents import Agent, Runner, handoff

# 专家智能体
billing_agent = Agent(
    name="Billing",
    instructions="You handle billing questions: invoices, payments, refunds, and subscription changes.",
)
technical_agent = Agent(
    name="Technical",
    instructions="You handle technical support: API errors, integration issues, and debugging.",
)

# 路由智能体——分类请求并交接给专家
triage_agent = Agent(
    name="Triage",
    instructions=(
        "You are the front-line support agent. Determine what the user needs "
        "and hand off to the appropriate specialist."
    ),
    handoffs=[billing_agent, technical_agent],
)

async def main():
    result = await Runner.run(triage_agent, "I got a 429 error when calling the API")
    print(result.final_output)

asyncio.run(main())
# 输出将由 technical_agent 生成——用户无感知交接过程

输入护栏（Guardrails）示例

import asyncio, re
from agents import Agent, Runner, InputGuardrail, GuardrailFunctionOutput

async def check_for_pii(ctx, agent, input_data) -> GuardrailFunctionOutput:
    """拦截包含邮箱或电话的输入"""
    text = input_data if isinstance(input_data, str) else str(input_data)
    has_email = bool(re.search(r'[\w.-]+@[\w.-]+\.\w+', text))
    has_phone = bool(re.search(r'\b\d{3}[-.]?\d{3}[-.]?\d{4}\b', text))
    return GuardrailFunctionOutput(
        output_info={"has_pii": has_email or has_phone},
        tripwire_triggered=has_email or has_phone,
    )

agent = Agent(
    name="Safe Agent",
    instructions="You are a helpful assistant.",
    input_guardrails=[InputGuardrail(guardrail_function=check_for_pii)],
)

try:
    result = Runner.run_sync(agent, "My email is user@example.com, help me reset my password")
except Exception as e:
    print(f"Blocked: {e}")

使用沙箱智能体（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)

Windows 用户请使用 DockerSandboxClient（需安装 openai-agents[docker] 额外依赖）代替 UnixLocalSandboxClient。

使用 100+ LLM（通过 LiteLLM）：

pip install 'openai-agents[litellm]'

Python：

from agents import Agent, Runner
from openai import AsyncOpenAI

# 通过 LiteLLM 适配任意支持的模型
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
    # 配置对应的模型客户端
)

使用 Ollama 本地模型

参考社区 LiteLLM 适配方案，将 Ollama 端点作为 OpenAI 兼容接口接入 Agents SDK 即可。