OpenAI Agents SDK 实战指南：Handoff、Guardrails、Tracing 与 MCP 集成

OpenAI 在停止 Swarm 维护后推出 Agents SDK，作为官方 Agent 抽象。这套 SDK 在 2026 年已经成为绑定 OpenAI 模型生态（GPT-5、o 系列）的最佳入口。本文从核心抽象、代码实战、生产部署到选型对比，系统讲清楚它。

核心抽象速览

Agents SDK 只有五个核心原语：

原语	作用	类比
Agent	一个有 system prompt + 工具集的 LLM 实体	类似 CrewAI 的 Role
Handoff	Agent 之间转交控制权	类似函数调用的"转接"
Tool	函数调用	类似 OpenAI function calling
Guardrail	输入/输出校验	类似 API 中间件
Tracing	自动埋点观察	类似 OpenTelemetry，但内置

一、Agent：最小构建单元

from agents import Agent

customer_support = Agent(
    name="Customer Support",
    instructions="""You handle customer inquiries.
    For refunds, hand off to the refund agent.
    For technical issues, hand off to tech support.""",
    tools=[lookup_order, search_kb],
    handoffs=[refund_agent, tech_support_agent],
)

Agent 的核心就是 instructions + tools + handoffs。比 LangChain 的 Agent 抽象更轻——没有复杂的 chain / runnable 概念。

二、Handoff：Agent 之间的"接力"

Handoff 是 Agents SDK 的灵魂特性。当当前 Agent 判断需要切换时，控制权平滑转交：

refund_agent = Agent(
    name="Refund Specialist",
    instructions="You process refunds. Always confirm the order ID and amount.",
    tools=[process_refund],
)

customer_support.handoffs.append(refund_agent)

用户说"我要退款"时，customer_support 自动判断意图，handoff 给 refund_agent。整个切换过程对用户透明。

Handoff vs LangGraph state graph： Handoff 更适合线性流程（用户问题 → 分类 → 处理），LangGraph 更适合复杂状态机（多步骤循环、条件分支、人工介入）。如果你的业务能用流程图描述，Agents SDK 更直接；如果需要状态图，用 LangGraph。

三、Guardrails：生产护栏

Guardrails 是 Agents SDK 区别于其他框架的另一个亮点——输入输出校验内建：

from agents import GuardrailFunctionOutput, input_guardrail

@input_guardrail
async def check_jailbreak(ctx, agent, input):
    # 检测 prompt injection
    is_safe = await safety_model.check(input)
    return GuardrailFunctionOutput(
        output_info={"reason": "unsafe input"},
        tripwire_triggered=not is_safe,
    )

配置后，每次用户输入都会先过 guardrail，触发 tripwire 时直接拒绝。不需要自己写中间件或装饰器。

四、Tracing：开箱即用的可观测性

这是对生产团队最有价值的功能——Tracing 与 OpenAI dashboard 深度集成：

from agents import Runner

result = await Runner.run(customer_support, "我想退款订单 12345")
# 自动在 OpenAI dashboard 生成 trace

Trace 里包含：

• 每次 LLM 调用的 prompt / completion / token 用量
• 每次 tool 调用的参数和返回
• Handoff 链路
• 延迟、成本

对自建可观测性的影响： 小团队可以完全跳过 LangSmith / Langfuse 的搭建，直接用 OpenAI dashboard。中大型团队仍建议自己搭一套（避免厂商锁定），但 Tracing 是 zero-config 的最低门槛方案。

五、MCP 集成

Agents SDK 原生支持 MCP（Model Context Protocol），可以直接连接任何 MCP server：

from agents.mcp import MCPServerStdio

filesystem_mcp = MCPServerStdio(
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "/data"]
)

agent = Agent(
    name="File Agent",
    mcp_servers=[filesystem_mcp],
    instructions="Use filesystem tools to help users."
)

MCP server 暴露的工具会自动成为 agent 的 tools，无需手动声明。这让 agent 的能力扩展变得模块化、可复用。

六、生产部署要点

1. 模型选择策略： 不要所有 agent 都用最贵的模型。路由 agent 用 GPT-5 mini，深度推理 agent 用 GPT-5。Agents SDK 的 model 参数支持每个 agent 单独配置。

2. 成本控制： Tracing 提供的 token 数据是成本优化的基础。监控每个 agent 的 token/请求，识别浪费。

3. 降级方案： OpenAI API 偶尔会故障。生产环境务必配置 fallback——可以用 LiteLLM 之类的网关，在 OpenAI 故障时切到 Anthropic。

4. Handoff 深度限制： 多个 agent 接力时，避免无限 handoff 循环。建议设置 max_turns 上限。

七、与同类框架对比

维度	OpenAI Agents SDK	LangGraph	CrewAI	Claude Agent SDK
模型支持	OpenAI 专属	多模型	多模型	Claude 专属
核心抽象	Handoff	StateGraph	Role + Task	Sub-agent
可观测性	OpenAI dashboard 内建	需自建	需自建	Anthropic console
MCP 支持	原生一等公民	通过 adapter	良好	原生一等公民
学习曲线	低	中	低	中
适合场景	OpenAI 生态、线性流程	复杂状态机	多 Agent 协作	Claude 深度使用

八、什么时候不该用 Agents SDK

诚实说出它的局限：

• 你需要多模型： 如果你计划未来切换或混用 Claude/Gemini，重度使用 Agents SDK 会让迁移成本极高
• 你需要复杂状态机： Agents SDK 的 Handoff 是线性接力，复杂状态机还是 LangGraph 更合适
• 你不希望被厂商锁定： OpenAI 在模型定价、API 变更上有完全控制权，深度依赖意味着失去谈判筹码

九、选型建议

适合用 Agents SDK 的场景：

• 团队已经重度使用 OpenAI 模型，且没有切换计划
• 业务流程偏线性（客服、审批、数据处理）
• 希望最小化自建可观测性的成本
• 需要 MCP 集成但不想自己写 adapter

不适合的场景：

• 需要跨多个模型厂商
• 业务逻辑是复杂状态机
• 团队对厂商锁定高度敏感

---

本文由 AgentList 团队整理。更多 Agent 框架、工具、应用项目，请浏览 AgentList 项目目录。

本文涉及的相关项目

• OpenAI Agents Python — OpenAI 官方 Agent SDK 本文主角，提供 Handoff、Guardrails、Tracing、MCP 一体化能力
• OpenAI Swarm — OpenAI 早期实验性多 Agent 框架；Agents SDK 是它的正式继任者
• LangGraph — 状态图编排框架，适合复杂的多 Agent 工作流
• CrewAI — 角色化多 Agent 协作框架
• Model Context Protocol Servers — 官方 MCP 参考实现集合（filesystem / git / fetch 等），Agents SDK 通过 MCP 直接调用其工具