OpenAI Agents SDK 实战指南（2026）

来源：OpenAI Agents SDK Python 文档 · OpenAI Agents SDK JS/TS 文档 · OpenAI Agents SDK 沙箱文档 | 整理时间：2026-05-11

概述

OpenAI Agents SDK 是面向生产环境的 Agent 开发框架。2026 年 4-5 月的更新把它从"轻量编排工具"推进到"沙箱原生的 Agent 运行时"：

• SandboxAgent：隔离的文件系统和命令执行环境，支持快照和断点恢复
• MCP 一等公民：工具注册、schema 自动生成、tracing 内建
• AGENTS.md：项目级自定义指令，类似 Claude Code 的 CLAUDE.md
• Voice / RealtimeAgent：语音打断、轮次管理、guardrails（TS SDK）

当前最新版本：Python 0.3.3，TypeScript 生产就绪。

为什么 2026 年值得关注

安装

# Python
pip install openai-agents

# 带语音支持
pip install 'openai-agents[voice]'

# TypeScript
npm install @openai/agents zod

核心概念

架构视角：从单 Agent 到多 Agent

Agents SDK 的核心结构是"先分责，再协作"：请求进入有职责边界的 Agent，分发到工具或 handoff 给另一个 Agent，最后由 guardrails 做输出约束。

用户请求
   |
   v
协调 Agent (Router)
   |-- 工具调用：Function Tools / MCP Tools
   |-- Handoff --> 研究 Agent
   |-- Handoff --> 执行 Agent
   v
结果汇总 + Guardrails 校验
   |
   v
最终输出

不要把所有能力堆进一个超大 Agent。先拆成单一职责的 Agent，再通过 handoff 串联，后期更容易维护和扩展。

最小可运行示例（Python）

from agents import Agent, Runner

assistant = Agent(
    name="Assistant",
    instructions="你是一个技术助手，优先给出可执行步骤。",
)

result = Runner.run_sync(assistant, "给我一个 Python 项目接入 MCP 的最小步骤")
print(result.final_output)

带工具调用的实战示例

from agents import Agent, Runner, function_tool

@function_tool
def query_kb(keyword: str) -> str:
    """查询知识库并返回摘要。"""
    fake_db = {
        "mcp": "MCP 用于让模型调用外部工具和资源。",
        "a2a": "A2A 用于 Agent 间互操作。",
    }
    return fake_db.get(keyword.lower(), "未找到相关内容")

research_agent = Agent(
    name="ResearchAgent",
    instructions="先调用 query_kb，再给出 3 条实践建议。",
    tools=[query_kb],
)

result = Runner.run_sync(research_agent, "请解释 MCP")
print(result.final_output)

实践建议：

1. 工具函数签名尽量稳定，避免频繁改参数导致提示词与调用失配
2. 为每个工具定义失败返回格式，便于 Agent 做重试或降级
3. 在关键工具调用前后打 trace 标记，后续排障成本显著降低

SandboxAgent：隔离环境执行

SandboxAgent 是 0.14.0 引入的核心能力，让 Agent 在隔离环境里执行命令和修改文件。

from agents import Agent, Runner
from agents.sandbox import SandboxAgent

code_agent = SandboxAgent(
    name="CodeAgent",
    instructions="你是代码助手。根据需求修改文件，然后运行测试验证。",
    sandbox={"backend": "local"},  # local / containerized / hosted
)

result = Runner.run_sync(
    code_agent,
    "在 /workspace 里创建一个 hello.py，写一个 add 函数和测试"
)
print(result.final_output)

SandboxAgent 内建 shell（命令执行）和 apply_patch（文件编辑）工具，不需要你手写这些。

断点恢复

from agents import Runner

# 第一次运行 → 保存状态
result = Runner.run_sync(agent, "开始分析数据", max_turns=5)

# 从快照恢复继续
result2 = Runner.run_sync(
    agent,
    "继续",
    previous_run_state=result.state,  # 从上次断点恢复
)

MCP 工具集成

SDK 现在把 MCP 工具当作一等公民：

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

mcp_server = MCPServerStdio(
    "python",
    args=["my_mcp_server.py"],
)

agent = Agent(
    name="MCPAgent",
    instructions="你可以调用 MCP 工具完成任务。",
    mcp_servers=[mcp_server],
)

result = Runner.run_sync(agent, "查询数据库中的用户列表")

MCP 工具和函数工具共享同一个 tools 命名空间，Agent 会自动决定调哪个。Tracing 里会标注 MCP 工具调用，敏感数据在 trace 里自动脱敏。

AGENTS.md：项目级指令

类似 Claude Code 的 CLAUDE.md，OpenAI Agents SDK 支持 AGENTS.md：

# AGENTS.md

## 项目结构
- src/api/ — REST API 路由
- src/models/ — 数据模型
- tests/ — 测试（pytest）

## 编码规范
- 使用 Python 3.11+ 类型注解
- 函数必须有 docstring
- 测试覆盖率不低于 80%

Agent 读取 repo 中的 AGENTS.md 来理解项目上下文。这让同一个 Agent 在不同项目中自动适应不同的编码规范和结构约定。

JS/TS 快速起步

import { Agent, run } from '@openai/agents';
import { z } from 'zod';

const agent = new Agent({
  name: 'Assistant',
  instructions: 'You are a practical software architect.',
});

const result = await run(agent, 'Design a bug triage workflow');
console.log(result.finalOutput);

TS SDK 完整支持 SandboxAgent、MCP 工具、guardrails 和 RealtimeAgent（语音）。

常见坑位与规避

上线路线图

1. 第 1 周：单 Agent + 2 个工具完成闭环
2. 第 2 周：拆为 Router + Specialist（handoffs）
3. 第 3 周：补齐 guardrails、人工审批、失败重试
4. 第 4 周：引入 tracing 指标，做延迟与成功率优化

与其他 SDK 的选择建议

→ 详见 主流 SDK 对比