OpenAI Agents SDK 技术详解报告
·
调研日期：2026-07-17
调研对象：OpenAI Agents SDK for Python
参考版本：openai-agentsv0.18.3（调研时 GitHub 最新版本）
动态图：OpenAI_Agents_SDK模块动态展示_重制版.gif
目录
- 框架定位
- 整体架构
- 核心对象与模块
- Runner 执行循环
- Tools 工具体系
- 多智能体编排
- Guardrails 与人工审批
- Context、Session 与状态管理
- 结构化输出、结果与流式事件
- Tracing 与可观测性
- Realtime Agent
- Sandbox Agent
- 快速入门示例
- 企业级参考架构
- 生产落地建议
- 与其他框架对比
- 选型结论
- 官方资料
1. 框架定位
OpenAI Agents SDK 是一个面向智能体应用的轻量级运行时与编排框架。它在模型 API 之上提供一套较少但清晰的抽象，由 SDK 负责管理：
- 多轮 Agent 执行循环；
- 函数、托管工具、MCP、计算机和 Shell 工具调用；
- Agent 之间的 Handoff 或 Manager 式协作；
- 输入、输出和函数工具 Guardrail；
- 会话记忆、运行上下文与中断恢复；
- 流式事件、结果对象和生命周期 Hook；
- Trace、Span、调试与生产监控；
- Realtime 语音智能体；
- 文件、命令和代码任务所需的隔离 Sandbox。
对于 OpenAI 模型，SDK 默认使用 Responses API，但增加了更高层的运行时。二者的边界如下：
| 方式 | 适合场景 |
|---|---|
| 直接调用 Responses API | 流程短、调用次数少；开发者希望自行管理 Tool Dispatch、状态和循环 |
| 使用 Agents SDK | 多阶段任务、工具链、多 Agent、Guardrail、Session、审批、流式事件或可恢复运行 |
| Agents SDK + Sandbox | 需要真实文件系统、命令执行、代码修改、产出文件或长时间工作空间 |
核心判断：Agents SDK 更像“模型驱动的应用运行时”，而不是完整的 BPMN 工作流平台。对强确定性、跨系统事务和复杂补偿流程，仍应配合 Temporal、Celery、消息队列或企业工作流引擎。
2. 整体架构
┌──────────────────────────────────────────────────────────────┐
│ Application Layer │
│ Web / App / API / Chat UI / Voice / Enterprise Bot │
└──────────────────────────────┬───────────────────────────────┘
│
Runner.run / run_sync / run_streamed
│
┌──────────────────────────────▼───────────────────────────────┐
│ Agents Runtime │
│ Agent │ Model │ Instructions │ Output Type │ Hooks │
│ Tools │ Handoffs │ Guardrails │ Context │ Session │
└──────────────┬───────────────┬──────────────┬────────────────┘
│ │ │
┌──────▼──────┐ ┌─────▼──────┐ ┌────▼─────────────┐
│ Model Layer │ │ Tool Layer │ │ State / Control │
│ Responses │ │ Function │ │ Session / HITL │
│ Realtime │ │ Hosted/MCP │ │ RunState │
└──────┬──────┘ │ Shell/Code │ └────┬─────────────┘
│ └─────┬──────┘ │
└──────────────┼─────────────┘
│
Trace / Span / Evaluation
一条典型请求会经过：
用户输入
→ Runner 启动当前 Agent
→ 输入 Guardrail
→ 模型生成文本、Tool Call 或 Handoff
→ 执行工具或切换 Agent
→ 将观察结果写回模型上下文
→ 重复循环
→ 输出 Guardrail
→ 返回 RunResult
→ 写入 Session 与 Trace
3. 核心对象与模块
3.1 Agent
Agent 是 SDK 的核心配置对象，本质上是一个带运行行为的模型角色。
常见字段：
| 字段 | 作用 |
|---|---|
name |
Agent 名称 |
instructions |
静态或动态系统指令 |
prompt |
OpenAI 平台托管的 Prompt 模板 |
model |
模型名称或模型对象 |
model_settings |
温度、Top-P、Tool Choice 等 |
tools |
Agent 可调用的工具 |
mcp_servers |
MCP 工具来源 |
handoffs |
可移交的目标 Agent |
input_guardrails |
首次输入检查 |
output_guardrails |
最终输出检查 |
output_type |
Pydantic、dataclass、TypedDict 等结构化输出类型 |
hooks |
Agent 生命周期回调 |
tool_use_behavior |
工具结果如何进入下一轮或结束运行 |
简化定义：
from agents import Agent
agent = Agent(
name="Technical Assistant",
instructions=(
"你是企业技术助手。先核对事实，再使用工具；"
"无法确认时明确说明，不得伪造工具结果。"
),
)
3.2 Runner
Runner 负责执行 Agent 循环，提供三种常见入口：
await Runner.run(agent, input)
Runner.run_sync(agent, input)
Runner.run_streamed(agent, input)
输入可以是：
- 普通字符串；
- Responses API 格式的 Input Item 列表；
- 用于恢复中断任务的
RunState。
Runner 还负责：
- 最大轮数；
- Tool 并发；
- Session 读写；
- Guardrail；
- Handoff；
- 审批中断；
- Trace；
- Model、Tool 和错误策略覆盖。
3.3 Model
对于 OpenAI 模型，SDK 默认走 Responses API。框架也提供模型抽象，便于使用兼容提供商或自定义 Model Provider。
企业工程中建议：
- 将模型选择放入配置中心；
- 不在业务代码中硬编码模型；
- 按任务分层使用强模型和轻量模型；
- 对模型降级、超时、重试和限流进行集中治理。
3.4 RunContextWrapper
Context 是一次运行内的依赖注入对象。数据库连接、当前用户、租户、权限、业务 ID 和服务客户端都可以通过 Context 传递，而不是写入 Prompt。
from dataclasses import dataclass
from agents import Agent, RunContextWrapper, function_tool
@dataclass
class UserContext:
user_id: str
tenant_id: str
can_refund: bool
@function_tool
def query_order(ctx: RunContextWrapper[UserContext], order_id: str) -> str:
return f"tenant={ctx.context.tenant_id}, order={order_id}"
注意：Context 是本地运行时对象，模型不会自动看到其中的数据。需要由 Tool、动态 Instructions 或其他代码显式读取并决定哪些内容可以暴露给模型。
4. Runner 执行循环
Runner 的核心循环可以概括为：
1. 使用当前 Agent 和当前输入调用模型
2. 检查模型输出：
a. 有最终输出 → 结束
b. 有 Handoff → 切换当前 Agent，再执行
c. 有 Tool Call → 执行工具，把结果加入输入，再执行
3. 超过 max_turns → 抛出 MaxTurnsExceeded
伪代码：
current_agent = starting_agent
items = input_items
while turns < max_turns:
response = model(current_agent, items)
if response.has_handoff:
current_agent = response.target_agent
items += response.handoff_items
continue
if response.has_tool_calls:
observations = execute_tools(response.tool_calls)
items += response.tool_calls + observations
continue
return RunResult(final_output=response.output)
4.1 为什么需要限制轮数
模型可能出现：
- 工具选择循环；
- 无效参数反复重试；
- 多 Agent 互相转移；
- 读取大量资料后迟迟不结束。
因此生产环境应为不同任务设置：
result = await Runner.run(
agent,
user_input,
max_turns=8,
)
同时还应设置：
- Tool 超时；
- API 总超时；
- 最大 Token；
- 最大并行工具数；
- 最大预算；
- 中止与取消机制。
5. Tools 工具体系
当前 Python SDK 将工具大致分为五类。
| 类别 | 说明 | 示例 |
|---|---|---|
| OpenAI Hosted Tools | 在 OpenAI 服务端运行 | Web Search、File Search、Code Interpreter、Hosted MCP、Image Generation |
| Local/Runtime Tools | 在应用或受控环境执行 | Computer、Shell、Apply Patch |
| Function Tools | 将 Python 函数封装为工具 | 数据库查询、HTTP API、算法服务 |
| Agents as Tools | 将子 Agent 暴露成 Manager 可调用工具 | 翻译 Agent、研究 Agent、审核 Agent |
| Experimental Codex Tool | 在工作区执行 Codex 任务 | 代码分析、修改和验证 |
5.1 Function Tool
SDK 可以从函数签名、类型注解和 Docstring 自动构建 JSON Schema，并通过 Pydantic 验证输入。
from agents import Agent, Runner, function_tool
@function_tool(timeout=5.0)
async def get_inventory(sku: str, warehouse_id: str) -> dict:
"""查询库存。
Args:
sku: 商品编码。
warehouse_id: 仓库编码。
"""
return {
"sku": sku,
"warehouse_id": warehouse_id,
"available": 128,
}
agent = Agent(
name="Inventory Agent",
instructions="必须调用库存工具后再回答库存问题。",
tools=[get_inventory],
)
result = await Runner.run(
agent,
"查询 SKU-001 在 WH-SZ-01 的可用库存。",
)
print(result.final_output)
生产工具建议做到：
- 参数类型严格；
- 工具名语义明确；
- Docstring 描述准确；
- 返回稳定、可序列化的结构；
- 对业务错误与系统错误分层；
- 设置超时、幂等键和重试策略；
- 不向模型返回密钥、原始 SQL、内部堆栈或敏感字段。
5.2 Hosted Tool
Hosted Tool 适合快速获得检索、文件分析和代码执行能力，但仍需关注：
- 哪些数据会离开本地环境；
- 数据保留策略；
- 文件权限；
- 搜索来源可靠性；
- 工具费用；
- 网络和地区可用性。
5.3 MCP
Agent 可通过 mcp_servers 接入 MCP 工具。MCP 适合把企业内部能力标准化为可发现、可调用的工具接口，例如：
- Git、代码仓库；
- CRM、ERP、工单系统；
- 数据仓库；
- 文件和知识库；
- 自动化平台；
- 机器人、视觉和算法服务。
企业 MCP Gateway 应增加：
身份认证
→ 租户隔离
→ Tool 白名单
→ 参数校验
→ 最小权限
→ 审批策略
→ 限流和超时
→ 调用审计
→ 输出脱敏
MCP 只是连接协议，不等于安全边界。远程 MCP Server 的工具说明和返回内容也可能包含恶意或误导性文本。
5.4 Agent as Tool
Manager 模式下，主 Agent 保留控制权，子 Agent 只返回阶段结果。
Manager Agent
├─ research_agent.as_tool()
├─ sql_agent.as_tool()
└─ reviewer_agent.as_tool()
它适合：
- 统一生成最终答案；
- 控制子任务输入；
- 聚合多个专家结果；
- 保留集中式策略与审批。
6. 多智能体编排
SDK 支持两种主要模式。
6.1 Manager：Agents as Tools
用户
↓
Manager Agent
├─ 调用检索 Agent
├─ 调用数据 Agent
├─ 调用审核 Agent
└─ 汇总最终结果
特点：
- Manager 始终面向用户；
- 子 Agent 类似专业工具；
- 适合中心化编排、结果汇总和统一权限控制；
- 子 Agent 的上下文可以被严格裁剪。
6.2 Handoff
用户
↓
Triage Agent
├─ transfer_to_billing_agent
├─ transfer_to_refund_agent
└─ transfer_to_technical_agent
Handoff 会把当前会话控制权交给目标 Agent。对模型而言，Handoff 以工具形式呈现。
from agents import Agent, Runner
billing_agent = Agent(
name="Billing Agent",
handoff_description="处理账单、发票和扣费问题。",
instructions="只处理账单相关问题。",
)
technical_agent = Agent(
name="Technical Agent",
handoff_description="处理产品故障和技术排查。",
instructions="先收集环境、版本和错误日志。",
)
triage_agent = Agent(
name="Triage Agent",
instructions="判断问题类别并移交给正确的专家。",
handoffs=[billing_agent, technical_agent],
)
result = await Runner.run(
triage_agent,
"升级后服务启动失败，日志提示连接池初始化异常。",
)
6.3 选择原则
| 需求 | 推荐模式 |
|---|---|
| 主 Agent 统一汇总 | Manager |
| 专家直接接管后续对话 | Handoff |
| 高风险业务统一决策 | Manager |
| 客服路由、语言路由 | Handoff |
| 需要并行收集多个结果 | Manager + Agents as Tools |
| 需要确定性流程 | 外部工作流引擎控制，Agent 作为节点 |
7. Guardrails 与人工审批
7.1 Guardrail 类型
| 类型 | 执行位置 |
|---|---|
| Input Guardrail | Agent 链的首次用户输入 |
| Output Guardrail | 最终输出形成之后 |
| Tool Input Guardrail | Function Tool 执行前 |
| Tool Output Guardrail | Function Tool 执行后 |
Guardrail 可以：
- 允许继续；
- 替换工具输出；
- 跳过工具；
- 触发 Tripwire；
- 抛出异常并停止运行。
典型检查：
- 敏感信息；
- 越权指令；
- Prompt Injection；
- 高危操作；
- 数据格式；
- 业务合规；
- 输出中是否存在未验证结论。
需要注意：
- Tool Guardrail 主要适用于
function_tool； - Handoff、Hosted Tool 和部分内置执行工具不经过相同的 Tool Guardrail 管线；
- 不能只配置一个 Guardrail 就认为所有工具都被保护。
7.2 Human-in-the-loop
删除数据、支付、发送外部消息、修改权限和控制设备等操作，应使用审批门。
模型提出 Tool Call
↓
参数预检查
↓
生成审批中断
↓
人工批准 / 拒绝 / 修改
↓
恢复 RunState
↓
再次校验并执行
高风险工具设计建议：
@function_tool
async def delete_records(
table: str,
record_ids: list[str],
approval_token: str,
) -> dict:
...
真正的权限校验必须在工具服务端完成，不能仅依靠 Agent Instructions。
8. Context、Session 与状态管理
8.1 Context
Context 适合保存一次运行内的本地依赖和状态：
- 用户与租户身份；
- 权限对象；
- 数据库连接；
- 服务客户端；
- Request ID；
- 预算；
- 运行时缓存。
8.2 Session
Session 是跨多次 Agent Run 的对话记忆层。SDK 会在运行前读取历史，在运行后写入新产生的用户消息、模型输出和工具项。
内置或扩展的实现包括：
| Session | 适用场景 |
|---|---|
SQLiteSession |
本地开发、小型应用 |
AsyncSQLiteSession |
异步 SQLite |
RedisSession |
多实例、低延迟共享会话 |
SQLAlchemySession |
接入现有关系型数据库 |
| OpenAI Conversations Session | OpenAI 托管的会话历史 |
| Encrypted Session | 加密和 TTL 包装 |
| 自定义 Session | 企业自有存储和治理 |
基本示例：
from agents import Agent, Runner, SQLiteSession
agent = Agent(
name="Assistant",
instructions="回答简洁，并利用已有会话上下文。",
)
session = SQLiteSession(
"tenant-a:user-1001:conversation-42",
"agent_sessions.db",
)
result1 = await Runner.run(
agent,
"我的部署目标是 Jetson Orin NX。",
session=session,
)
result2 = await Runner.run(
agent,
"刚才说的目标设备是什么？",
session=session,
)
8.3 三种状态不要混淆
| 状态 | 生命周期 | 用途 |
|---|---|---|
| Context | 单次 Run | 依赖注入和本地业务状态 |
| Session | 多次 Run | 对话历史和短期记忆 |
| RunState | 中断到恢复 | 审批、可恢复执行、暂停任务 |
企业还需要单独建设长期记忆和业务状态，例如：
- PostgreSQL 业务表；
- Redis 缓存；
- 向量数据库；
- 用户画像；
- 知识图谱；
- 任务状态机。
不要把所有状态都塞进聊天历史。
9. 结构化输出、结果与流式事件
9.1 Structured Output
通过 output_type 可以要求最终输出满足类型约束。
from pydantic import BaseModel, Field
from agents import Agent, Runner
class IncidentReport(BaseModel):
severity: str
root_cause: str
evidence: list[str]
actions: list[str]
confidence: float = Field(ge=0, le=1)
agent = Agent(
name="Incident Analyst",
instructions="只根据输入日志生成事故分析，不确定内容必须降低置信度。",
output_type=IncidentReport,
)
result = await Runner.run(agent, "日志内容……")
report: IncidentReport = result.final_output
适用于：
- API 返回；
- 工单字段；
- 任务计划；
- 检测结果；
- 审批请求；
- 数据抽取。
结构化输出能约束形状，但不能自动保证事实正确，仍需业务校验。
9.2 RunResult
常用结果面：
| 属性/方法 | 用途 |
|---|---|
final_output |
最终文本或结构化对象 |
last_agent |
最终完成任务的 Agent |
new_items |
本次运行产生的消息、Tool、Handoff 等项 |
to_input_list() |
生成可用于下一轮的本地完整历史 |
| Guardrail Results | 查看输入/输出校验 |
| Raw Responses | 查看底层模型响应 |
| Context / Usage | 查看上下文和使用量 |
| Run State | 恢复中断任务 |
由于 Handoff 可能改变最终 Agent，final_output 的静态类型在框架层面可能是 Any，业务代码应结合最终 Agent 或约定的公共 Output Schema 处理。
9.3 Streaming
Runner.run_streamed() 和 .stream_events() 可以接收：
- 模型流式 Token；
- Tool Call 事件；
- Tool Result；
- Handoff；
- Agent 切换；
- 最终输出。
适合：
- Chat UI；
- 长任务进度；
- 实时日志；
- 语音和多媒体交互。
10. Tracing 与可观测性
Tracing 默认开启，用于记录一次工作流的完整执行轨迹。
Trace 中包含多个 Span：
Trace
└─ Task Span
├─ Turn Span
│ ├─ Agent Span
│ ├─ Generation Span
│ ├─ Function Span
│ ├─ Guardrail Span
│ └─ Handoff Span
└─ Custom Span
可观测内容包括：
- 模型输入输出；
- 每轮耗时；
- 工具参数与结果；
- Agent 切换；
- Guardrail 结果；
- 错误；
- Token 和使用量；
- 自定义业务事件。
生产环境建议把 Trace 与以下信息关联：
request_id
tenant_id
user_id
session_id
workflow_name
business_object_id
model
prompt_version
tool_version
release_version
安全注意：
- 不记录 API Key 和凭证；
- 对 Tool 参数、文件内容和客户数据脱敏；
- 配置 Trace 数据访问权限和保留周期；
- Zero Data Retention 场景需核对 Tracing 可用性；
- 将业务审计日志与调试 Trace 分开保存。
11. Realtime Agent
Realtime 模块用于低延迟语音或实时会话，主要对象包括：
RealtimeAgent：实时专家 Agent；RealtimeRunner：创建实时会话；RealtimeSession：管理连接、事件、历史与工具；RealtimeModel：传输抽象。
典型能力：
- 音频输入输出；
- 自动打断检测；
- 实时 Tool Calling；
- Handoff；
- 上下文管理；
- Guardrail；
- 使用量与事件监听。
适合：
- 实时语音客服；
- 车载助手；
- 会议助手；
- 设备操作指导；
- 低延迟多模态交互。
Realtime 的连接、音频播放和打断状态与普通文本 Runner 不同，应单独设计状态机和前端事件协议。
12. Sandbox Agent
2026 年的 Agents SDK 增强了 Sandbox 能力，用于在受控工作空间内完成真实文件和命令任务。
当任务具有以下特征时适合使用 Sandbox：
- 需要读取一个目录或代码仓库；
- 需要创建、修改和保存文件；
- 需要运行命令、依赖、脚本或测试；
- 输出 Markdown、CSV、JSONL、网页、截图等制品；
- 需要暴露本地预览服务端口；
- 人工审核后继续使用同一个工作区。
Agent Harness（编排）
│
├─ Trusted Services / Model / Policy
│
└─ Sandbox Session（执行）
├─ Filesystem
├─ Shell / Process
├─ Packages
├─ Ports
└─ Stateful Workspace
推荐将编排 Harness 与执行 Sandbox 分离：
- Harness 在可信基础设施中运行；
- Sandbox 只获得任务需要的文件、网络、命令和凭证；
- 使用 Manifest 描述初始工作区；
- 使用 Capability 声明沙箱能力；
- 对外部网络、挂载、环境变量和端口采用最小权限。
Sandbox 不等于绝对安全。仍需容器隔离、内核安全、网络策略、密钥代理、文件扫描、资源限额和销毁策略。
13. 快速入门示例
13.1 安装
python -m venv .venv
source .venv/bin/activate
pip install -U openai-agents
export OPENAI_API_KEY="YOUR_API_KEY"
13.2 单 Agent + Function Tool + 结构化输出
import asyncio
from pydantic import BaseModel, Field
from agents import Agent, Runner, function_tool
class DeploymentAdvice(BaseModel):
platform: str
recommended_runtime: str
actions: list[str]
risk_level: str
confidence: float = Field(ge=0.0, le=1.0)
@function_tool(timeout=5.0)
async def query_device_profile(device: str) -> dict:
"""查询设备的部署画像。
Args:
device: 设备型号。
"""
profiles = {
"Jetson Orin NX 16GB": {
"memory_gb": 16,
"runtime": ["TensorRT", "ONNX Runtime", "CUDA"],
"notes": "适合边缘视觉和中小型多模态模型。",
}
}
return profiles.get(device, {"error": "device_not_found"})
agent = Agent(
name="Edge Deployment Architect",
instructions=(
"根据工具返回的真实设备信息提出部署建议。"
"禁止编造不存在的硬件参数。"
),
tools=[query_device_profile],
output_type=DeploymentAdvice,
)
async def main() -> None:
result = await Runner.run(
agent,
"为 Jetson Orin NX 16GB 设计轻量视觉模型部署方案。",
max_turns=6,
)
print(result.final_output.model_dump_json(indent=2))
if __name__ == "__main__":
asyncio.run(main())
13.3 多 Agent Handoff
from agents import Agent, Runner
vision_agent = Agent(
name="Vision Deployment Agent",
handoff_description="负责 ONNX、TensorRT、MNN 和视觉模型部署。",
instructions="给出可落地的模型转换、预后处理和性能验证方案。",
)
robot_agent = Agent(
name="Robot Integration Agent",
handoff_description="负责 ROS2、传感器、控制接口和机器人系统集成。",
instructions="重点考虑 ROS2 接口、时序、坐标系和安全控制。",
)
triage_agent = Agent(
name="Engineering Triage Agent",
instructions="识别工程问题类型，并移交给最合适的专家。",
handoffs=[vision_agent, robot_agent],
)
result = await Runner.run(
triage_agent,
"如何把 PointPillars ONNX 推理接入 ROS2 点云节点？",
)
print(result.final_output)
14. 企业级参考架构
┌─────────────────────────────────────────────────────────────┐
│ Web / App / 企业微信 / API / Voice │
└──────────────────────────┬──────────────────────────────────┘
│
API Gateway / IAM / WAF
│
┌──────────────────────────▼──────────────────────────────────┐
│ Agent Application Service │
│ FastAPI / OpenAI Agents SDK / Prompt Registry │
│ Runner / Agents / Handoff / Guardrails / HITL │
└────────────┬─────────────┬─────────────┬────────────────────┘
│ │ │
┌─────▼─────┐ ┌────▼──────┐ ┌────▼─────────────┐
│Model GW │ │Tool/MCP GW│ │State & Workflow │
│Routing │ │Auth/Policy│ │Redis/PostgreSQL │
│Fallback │ │Rate Limit │ │Queue/Temporal │
└─────┬─────┘ └────┬──────┘ └────┬────────────┘
│ │ │
OpenAI Models ERP/CRM/DB Session/RunState
RAG/Vector DB
Vision/C++ SDK
ROS2/Devices
│
┌──────────────────────────▼──────────────────────────────────┐
│ Observability & Governance │
│ Trace / Eval / Audit / Cost / PII Redaction / Alert │
└─────────────────────────────────────────────────────────────┘
对于算法和机器人项目，建议将底层能力封装为确定性工具：
Agent
→ Tool Gateway
→ Python Algorithm Service
→ C++ Inference Runtime
→ ROS2 Service / Action
→ Database / Object Storage
Agent 负责理解意图、组织任务和生成解释；C++、ROS2、规则引擎负责确定性执行与安全约束。
15. 生产落地建议
15.1 Tool Contract
每个工具都应定义：
名称
用途
输入 Schema
输出 Schema
身份权限
租户范围
幂等策略
超时
重试
副作用等级
审批要求
审计字段
错误码
15.2 风险分级
| 等级 | 示例 | 策略 |
|---|---|---|
| L0 只读 | 搜索、查询、总结 | 自动执行 |
| L1 可逆写入 | 创建草稿、添加标签 | 自动或事后确认 |
| L2 外部影响 | 发邮件、更新工单 | 执行前确认 |
| L3 高风险 | 支付、删除、权限修改 | 强身份 + 人工审批 + 双重校验 |
| L4 物理控制 | 机器人运动、工业设备 | Agent 仅建议，安全控制器最终裁决 |
15.3 Prompt Injection 防护
需要组合防护：
- 不把外部文档当作系统指令；
- 工具白名单；
- 参数 Schema；
- 权限在服务端校验；
- 检索内容与控制指令分离；
- 对 URL、文件和 MCP 输出标记来源；
- 高风险工具审批；
- 限制 Agent 可访问的密钥和网络；
- 对关键决策增加规则引擎。
15.4 Evaluation
至少评测：
任务完成率
事实正确率
工具选择准确率
工具参数正确率
Handoff 路由准确率
Guardrail 召回率和误杀率
平均轮数
延迟
Token 和工具成本
中断恢复成功率
人工接管率
为 Prompt、Tool Schema、模型和代码建立版本号，使用固定数据集做回归测试。
15.5 不建议的做法
- 让模型直接拼接 SQL 并连接生产库；
- 把管理员 Token 放进 Context 后直接交给任意工具；
- 用 Prompt 代替权限控制；
- 所有工具都开放给所有 Agent；
- 不设置最大轮数和超时；
- 把 Session 当作业务数据库；
- 不记录 Agent、模型、Prompt 和 Tool 版本；
- 让 Agent 绕过设备安全控制器直接驱动执行机构。
16. 与其他框架对比
| 维度 | OpenAI Agents SDK | LangGraph | CrewAI | Dify |
|---|---|---|---|---|
| 核心定位 | 轻量 Agent Runtime | 状态图与持久化编排 | 角色式多 Agent | 低代码 AI 应用平台 |
| 开发方式 | Python/TypeScript SDK | Python/TS 图结构 | Python Role/Crew/Flow | 可视化工作流 |
| OpenAI 集成 | 最紧密 | 良好 | 良好 | 良好 |
| 确定性复杂流程 | 中 | 强 | 中 | 中 |
| Handoff | 原生 | 可实现 | 角色协作 | 节点路由 |
| Session | 原生多后端 | Checkpoint/Store | Memory | 平台会话 |
| Guardrail | 输入/输出/函数工具 | 自定义节点/中间件 | Guardrail | 平台策略与节点 |
| Tracing | 原生 | LangSmith 等 | 平台/第三方 | 平台日志 |
| Sandbox | 原生增强 | 外部组合 | 外部组合 | 代码节点/外部执行 |
| 低代码 | 弱 | 弱 | 弱 | 强 |
| 适合 | OpenAI 优先、工具型、多 Agent、实时和 Sandbox 应用 | 长流程、状态机、人工审批、恢复 | 内容、研究和角色协作 | 知识助手与快速业务应用 |
选择建议：
- OpenAI 模型优先、需要 Tool/Handoff/Realtime/Sandbox：OpenAI Agents SDK；
- 复杂状态图、长流程和强确定性：LangGraph；
- 快速角色化多智能体原型：CrewAI；
- 业务人员配置知识库和流程：Dify；
- 大型企业流程：Agents SDK + 外部工作流引擎，而不是单独依赖 Agent 循环。
17. 选型结论
OpenAI Agents SDK 的核心优势是：
- 抽象少，入门和集成成本较低；
- Runner 自动管理模型、Tool、Handoff 和 Guardrail 循环；
- Function Tool、Hosted Tool、MCP、Agent as Tool 和 Sandbox 覆盖较完整；
- 原生支持结构化输出、Session、Streaming 和 Tracing；
- 与 Responses API、Realtime 和 OpenAI 模型能力演进同步；
- 既能构建单 Agent，也能构建中心化或去中心化多 Agent。
主要限制是：
- 它不是完整的企业工作流和事务引擎；
- 权限、租户、审计、成本和工具治理仍需业务侧建设；
- 模型控制流具有概率性；
- Guardrail 的覆盖范围因 Tool 类型而异；
- 复杂长期记忆需要外部存储和检索体系；
- 高风险操作仍必须由服务端规则和人工审批控制。
推荐企业组合：
OpenAI Agents SDK
+ FastAPI
+ Pydantic
+ Tool/MCP Gateway
+ PostgreSQL / Redis
+ RAG / File Search
+ Human Approval
+ Trace / Eval / Audit
+ Temporal 或消息队列（复杂长流程）
+ Sandbox（文件、命令和代码任务）
对于视觉、C++ 推理和 ROS2 项目：
Agents SDK 负责意图理解与任务编排
Tool Gateway 负责鉴权与协议转换
Python/C++/ROS2 服务负责确定性执行
规则引擎与安全控制器负责最终约束
18. 官方资料
-
OpenAI Agents SDK Python 文档
https://openai.github.io/openai-agents-python/ -
Agents
https://openai.github.io/openai-agents-python/agents/ -
Running Agents
https://openai.github.io/openai-agents-python/running_agents/ -
Tools
https://openai.github.io/openai-agents-python/tools/ -
Handoffs
https://openai.github.io/openai-agents-python/handoffs/ -
Guardrails
https://openai.github.io/openai-agents-python/guardrails/ -
Sessions
https://openai.github.io/openai-agents-python/sessions/ -
Tracing
https://openai.github.io/openai-agents-python/tracing/ -
Sandbox Agents
https://developers.openai.com/api/docs/guides/agents/sandboxes -
OpenAI Agents SDK GitHub
https://github.com/openai/openai-agents-python -
2026 年 Agents SDK Sandbox 演进说明
https://openai.com/index/the-next-evolution-of-the-agents-sdk/
说明：SDK 更新较快。生产项目应锁定依赖版本，并在升级前检查 Release Notes、运行回归测试和验证 Tool/Session/Sandbox 兼容性。
Agent 垂直技术社区，欢迎活跃、内容共建。
更多推荐
6
0- 0
已为社区贡献6条内容
所有评论(0)