OpenAI Agents SDK Skill 技能

# OpenAI Agents SDK（C 线 Skill） ## 技能简介 OpenAI Agents SDK 是

AI Agent

查看 Skill ↗

OpenAI Agents SDK（C 线 Skill）

技能简介

OpenAI Agents SDK 是 OpenAI 官方开源的多智能体工作流开发框架，使用 Python 构建，Apache-2.0 许可证（MIT）。GitHub 仓库现有 29,779 颗星、4,835 个 Fork，是 2025 年至今最受关注的 AI Agent 开发框架之一。该 SDK 于 2025 年 3 月正式发布，2026 年 9 月底仍有活跃更新（最近提交 2026-09-30），由 OpenAI 官方维护与支持。

与 LangChain、LlamaIndex 等重量级框架不同，OpenAI Agents SDK 以"最小原语集"为核心设计原则：仅提供 Agent、Tool、Handoff、Guardrail 四类原语，开发者无需学习陡峭的抽象层，即可在几分钟内完成多智能体应用的原型搭建与生产部署。SDK 支持 OpenAI 全系列模型（GPT-4o、GPT-4o-mini、o1、o1-mini、o3 等），同时兼容 100 余种第三方大语言模型（Anthropic、Google、Meta、DeepSeek 等），真正实现模型无关（Provider-agnostic）的开发体验。

核心能力

1. Agent（智能体）

Agent 是 SDK 的核心原语，本质上是配置了指令、工具、护栏和交接逻辑的 LLM 实例。每个 Agent 内置运行循环（Run Loop），自动处理多轮对话、工具调用和任务完成判定，开发者只需描述 Agent 的角色定位即可，无需手动管理循环状态。

核心配置参数包括：

instructions：以自然语言定义 Agent 角色与行为规范
tools：Agent 可调用的工具列表（函数工具、MCP 工具、托管工具）
guardrails：输入输出安全校验规则
handoffs：向其他 Agent 转交任务的路由规则
model：所使用的大语言模型（默认为 gpt-4o）

from agents import Agent, Runner

agent = Agent(name="Researcher", instructions="你是一名专业的研究助手，擅长信息检索与摘要整理")
result = Runner.run_sync(agent, "帮我总结一下 2026 年 AI Agent 的发展趋势")
print(result.final_output)

2. Sandbox Agents（沙箱智能体）

Sandbox Agents 是为长时任务设计的专用 Agent 类型，内部运行在隔离的容器环境中。每个 Sandbox Agent 支持：

Manifest 定义的文件：通过 manifest.json 声明所需文件和依赖
可恢复会话：Sandbox 执行可随时暂停并恢复，适合需要数小时甚至数天完成的长程任务（如代码重构、批量数据处理）
多沙箱客户端：可对接 Docker、本地进程或云端容器作为执行后端

这使得 Agent 不仅能回答问题，还能真正执行文件操作、运行脚本、调用外部 API 等生产级任务。

3. Realtime Agents（实时语音智能体）

基于 OpenAI 最新 gpt-realtime-2.1 模型构建的语音 Agent，支持：

自动打断检测：用户可在 Agent 说话时随时打断
上下文管理：跨轮次保持对话状态
Guardrails 集成：实时内容安全校验
低延迟语音交互：端到端延迟显著低于传统 STT→LLM→TTS 串行方案

适合构建电话客服、语音助手、实时翻译等对延迟敏感的应用场景。

4. Voice Agents（语音管线智能体）

将语音识别（STT）、Agent 工作流、语音合成（TTS）三个环节串联的完整语音解决方案。开发者可自由替换各环节供应商（如使用 Whisper 做 STT、Cartesia 做 TTS），同时保留 Agent 的工具调用和多步推理能力。

5. Handoffs（智能体交接）

Handoffs 是协调多 Agent 协作的核心机制，允许一个 Agent 将任务或对话上下文完整移交给另一个 Agent。例如：

客服场景中，从"问题分类 Agent"交接至"技术支持 Agent"或"退换货 Agent"
研究场景中，从"信息检索 Agent"交接至"数据分析 Agent"
交接时可附加上下文注释（transfer_metadata），帮助下一个 Agent 快速理解任务背景

from agents import Agent, handoff

technical_agent = Agent(name="技术支持", instructions="...")
billing_agent = Agent(name="账单处理", instructions="...")

triage = Agent(
    name="分诊员",
    instructions="判断用户问题类型并转接至对应专员",
    handoffs=[technical_agent, billing_agent]
)

6. Guardrails（护栏）

Guardrails 在 Agent 执行前后并行运行输入/输出校验规则，支持：

输入校验：拒绝不合规的用户查询（如涉及敏感词、恶意指令）
输出校验：过滤 Agent 返回内容中的不当信息
极速失败：校验与 Agent 执行并行，大幅降低无效推理开销

7. Tools（工具生态）

SDK 提供三层工具集成：

函数工具（Function Tools）：将任意 Python 函数自动转换为带 Pydantic 类型校验的 Agent 工具
MCP 工具：原生集成 Model Context Protocol，连接远程 MCP 服务器，将 100+ MCP 工具直接暴露给 Agent
托管工具：OpenAI 官方的浏览器操作、代码执行等预置工具

8. Sessions（会话管理）

Sessions 提供持久化记忆层，在 Agent 运行期间自动维护对话历史上下文。开发者可接入 Redis 将会话状态持久化至外部存储，支持多实例共享同一会话，适用于需要跨进程或跨服务共享 Agent 状态的场景。

9. Tracing（链路追踪）

内置全链路追踪能力，可视化 Agent 的思考路径、工具调用顺序、Token 消耗等关键指标。与 OpenAI 平台的评估（Evaluation）、微调（Fine-tuning）、蒸馏（Distillation）工具链打通，支持基于真实运行数据优化 Agent 提示词和模型选择。

安装配置

环境要求

Python 版本：3.10 及以上
依赖管理工具：pip 或 uv
可选依赖组：voice（语音支持）、redis（Redis 会话存储）

安装步骤

方式一：pip 安装（推荐）

# 基础安装
pip install openai-agents

# 语音支持（含 Realtime Agent 和 Voice Agent）
pip install 'openai-agents[voice]'

# Redis 会话支持（多实例共享会话）
pip install 'openai-agents[redis]'

方式二：uv 安装

uv pip install openai-agents

环境变量配置

# OpenAI API Key（必须）
export OPENAI_API_KEY=sk-...

# 第三方模型（如使用 Anthropic、Google 等）
export ANTHROPIC_API_KEY=sk-ant-...
export GOOGLE_API_KEY=AIza...

# Redis 连接（使用 Redis Sessions 时）
export REDIS_URL=redis://localhost:6379

快速验证安装

python -c "from agents import Agent, Runner; print('SDK 导入成功')"

使用步骤

第一步：初始化项目

mkdir my-agent-project &amp;&amp; cd my-agent-project
python -m venv .venv &amp;&amp; source .venv/bin/activate
pip install openai-agents

第二步：创建你的第一个 Agent

在 app.py 中写入以下代码：

from agents import Agent, Runner
import os
os.environ["OPENAI_API_KEY"] = "sk-..."  # 或通过环境变量设置

agent = Agent(
    name="助手",
    instructions="你是一名专业、友好的 AI 助手，擅长回答各类问题。"
)

result = Runner.run_sync(agent, "你好，请自我介绍一下。")
print(result.final_output)

运行 python app.py，即可看到 Agent 的回复。

第三步：给 Agent 添加工具

from agents import Agent, Runner, function_tool

@function_tool
def get_weather(city: str) -&gt; str:
    """获取指定城市的当前天气"""
    # 这里可接入真实天气 API
    return f"{city} 今日天气晴，气温 22°C"

agent = Agent(
    name="旅行助手",
    instructions="你是一名旅行助手，可回答天气相关问题。",
    tools=[get_weather]
)

result = Runner.run_sync(agent, "北京今天天气怎么样？")
print(result.final_output)

第四步：构建多 Agent 协作

from agents import Agent, Runner

specialist = Agent(
    name="专家",
    instructions="你是金融分析专家，擅长解读公司财报。"
)

coordinator = Agent(
    name="协调员",
    instructions="你是协调员，将任务分配给对应专家并整合结果。",
    handoffs=[specialist]
)

result = Runner.run_sync(coordinator, "帮我分析一下苹果公司 2026 年 Q2 的财务表现")
print(result.final_output)

第五步：添加 Guardrails 和 Tracing

from agents import Agent, Runner, GuardrailOutput
from agents.guards import ValMatch

# 定义输入护栏：拒绝涉及政治的查询
political_check = ValMatch(
    name="political_check",
    condition=lambda x: "政治" not in x,
    failure_message="抱歉，我不处理政治相关话题。"
)

agent = Agent(
    name="新闻助手",
    instructions="你是一名新闻助手，",
    guards=[political_check]  # 挂载护栏
)

# 启用追踪（自动记录到 OpenAI 平台）
result = Runner.run_sync(agent, "请介绍一下美国的政治制度")

适用场景

1. 企业客服与支持

通过 Handoffs 将不同类型问题分流至对应专员 Agent（技术问题→技术支持 Agent、退换货→售后 Agent、账单→财务 Agent），配合 Guardrails 实现输入内容安全过滤，显著降低人工客服负担。

2. 语音与电话应用

Realtime Agents 和 Voice Agents 适用于智能电话客服、语音助手、实时翻译等场景。相比传统的 STT→LLM→TTS 串行架构，OpenAI Agents SDK 的实时语音管线延迟更低、打断响应更快。

3. 长时自动化任务

Sandbox Agents 适合需要数小时甚至数天执行的长程任务，如大型代码库重构、批量文档处理、自动化测试套件运行等，容器化执行环境保证隔离性与可恢复性。

4. 多 Agent 协调系统

Handoffs 机制天然适合复杂的多 Agent 协作场景，例如：研究工作流（信息采集→分析→报告生成）、销售流程（线索评分→需求挖掘→方案生成→报价）等。

5. AI 应用开发与研究

SDK 的 Tracing 模块与 OpenAI 评估/微调工具链打通，适合 AI 应用研究团队快速迭代 Agent 提示词、对比不同模型表现，并通过真实运行数据持续优化系统。

适用人群

AI 应用开发者：需要快速构建多 Agent 应用的 Python 工程师
企业 IT 团队：计划搭建智能客服、流程自动化系统的企业
AI 研究人员：研究 Agent 协作、工具调用、记忆管理等方向
独立开发者与创业者：用最小代码量构建 AI 原生产品
语音应用开发者：构建实时语音 Agent 或电话机器人的开发者

工作原理

OpenAI Agents SDK 的核心是运行循环（Run Loop）：当用户输入到达时，Runner 将输入与 Agent 指令组装为消息历史，调用底层 LLM 生成回复；若 LLM 触发工具调用，Runner 负责注入工具结果并重新调用 LLM，直到 Agent 判定任务完成或达到最大轮次上限。

用户输入 → Runner → 组装消息历史 → LLM 推理
                                         ↓
                                   工具调用？
                        是 → 执行工具 → 注入结果 → 重新推理
                        否 → 返回 final_output

关键组件的协作关系：

Runner：应用入口，管理整个运行循环的生命周期
Agent：包含提示词模板、工具列表、护栏规则和交接路由配置
Handoffs：在 Agent 层之上构建状态转移图，决定何时将控制权移交给哪个子 Agent
Sessions：在 Runner 之外维护持久化上下文，支持跨请求恢复会话状态
Tracing：在每个推理步骤插入钩子，记录输入、输出、Token 消耗和工具调用序列

整体架构追求简洁性与可扩展性的平衡：上手时只需理解 Agent 和 Runner 两个概念，进阶时可逐步引入 Handoffs、Sandbox、Guardrails 等高级特性。

官方链接

GitHub 仓库：https://github.com/openai/openai-agents-python
官方文档：https://openai.github.io/openai-agents-python/
PyPI 包：https://pypi.org/project/openai-agents/
JavaScript/TypeScript 版：https://github.com/openai/openai-agents-js

团队信息

AI产品库官方

由 AI 猎手自动发现

评论与建议

0 条评论