OpenAI Agents SDK：handoffs、guardrails 与 Responses API 时代的 Agent 栈

设计哲学：三个原语的极简主义

OpenAI 的 Agents SDK（2025 年 3 月发布，前身是实验性的 Swarm）的产品哲学与重量级框架相反：用最少的概念覆盖最多的场景。三个原语。Agent：一个「带配置的模型实例」——指令（system prompt）、工具集、可选的子 Agent。Handoff（移交）：Agent 之间转移控制权的机制——当前 Agent 判断「这事该同事管」，把对话上下文整体移交给子 Agent（接手的 Agent 以自己的指令与工具继续）——多智能体协作被简化成「调用工具般的移交」。Guardrails（护栏）：输入与输出的并行校验器（独立的轻量模型或规则）——用户输入先过护栏（注入检测、话题限定）、模型输出后过护栏（格式与安全）——护栏与主逻辑并行跑，不合格直接拦截。

这套极简主义的判断：大多数 Agent 应用的核心是「一个主 Agent + 几个专业子 Agent + 每边一道护栏」——不需要图、不需要显式状态机，把 handoff 做成语言原语就够了。SDK 的 Python 实现极薄（几百行核心），TypeScript 版同构。

Handoffs 深拆：移交即工具调用

handoffs 的实现机制聪明：每个子 Agent 被包装成一个特殊工具（transfer_to_xxx），主 Agent 按需「调用」这个工具——调用的效果是把对话控制权整体移交给子 Agent（上下文延续，子 Agent 以自己的 system prompt 继续）。这带来三个工程特性。移交是模型自主决策的（模型看到可移交的同事列表与职责描述，自己判断何时移交——与 function calling 的心智完全一致，零新概念）。移交可以链式（A → B → C，支持循环保护）。上下文策略可定制（默认全量移交，也可以过滤——只移交相关的历史，避免长上下文的稀释与成本）。

与「supervisor 编排」（中央调度员分派任务）的对比：handoffs 是横向移交（控制权转移），supervisor 是纵向分派（中央收集与分发）——前者适合「专业分工的流程」（客服分流：账单问题 → 账单专家），后者适合「并行任务」（研究拆成三份同时查）。SDK 两种都支持，但 handoffs 是它的灵魂。

Responses API 与内建工具：把常用能力下沉进平台

与 Agents SDK 配套的是 Responses API（取代 Completions 的下一代接口），它的方向是把常用 Agent 能力下沉为平台内建：内建工具（web_search 网页搜索、file_search 向量检索、code_interpreter 代码执行——不用自建基础设施，参数开启即用）、推理模型的深度集成（o 系/推理模型的思考过程作为一等公民返回）、多轮状态的服务端管理（previous_response_id 引用上一轮——服务端替你管理对话状态，客户端不必回传全部历史，与本库 Prefix Caching 的思路互补）。这是平台化路线的宣言：Agent 的「脏活」（搜索基础设施、代码沙箱、状态管理）由平台承担，开发者只写业务指令——代价是深度绑定 OpenAI 生态（SDK 本身开源且支持其他模型提供商，但内建工具是平台专属）。

Tracing 与生产化：开箱即用的可观测

Agents SDK 的第三张牌是开箱即用的 tracing：每次 Agent 运行自动生成完整的执行轨迹（LLM 调用、工具调用、handoff、guardrail 判定——层级化的 trace 视图），默认上传到 OpenAI 的 Trace 面板，也可对接第三方（导出为 OTel 兼容）。这解决了自建 Agent 最容易被忽略的运维盲区（本库可观测性篇的轨迹追踪需求，在这里是默认行为）。生产化的其他拼图：会话管理（自动维护对话历史）、流式输出（增量事件）、human-in-the-loop（工具执行的确认钩子——比 LangGraph 的 interrupt 轻量，是「工具级的确认」而非「流程级的中断」）。

与 LangGraph 类框架的哲学分歧与选型

两个流派的分歧值得点透。OpenAI 路线：模型即编排——把智能交给模型的自主决策（handoff 靠模型判断、工具靠模型选择），框架只提供最小脚手架；优势是开发快、概念少、跟模型能力升级水涨船高；劣势是控制流的确定性弱（复杂流程的可靠性依赖模型）。LangGraph 路线：代码即编排——控制流显式写进图（哪些步骤、什么顺序、何时人工），模型只在节点内被调用；优势是确定性与可审计，代价是开发量与灵活性。选型的判断式：流程简单且依赖模型智能 → OpenAI Agents SDK 的极简路线；流程复杂、有合规审计要求、需要精确控制每一步 → LangGraph 的图路线；两者也可以共存——外层用图管流程、节点内用极简 SDK 跑单体 Agent。Agent 框架的终局大概率是「两个流派都活着」：抽象的争夺不会终结，因为「控制与智能的平衡点」随模型能力每年移动。

OpenAI Agents SDK 实战：一个客服分流系统的最小实现

把三原语落到一个最小实现，客服分流系统是最佳教学案例。系统的分工设计：主 Agent（接线员：理解诉求、判断类别）+ 三个专家 Agent（账单专家、技术支持、退货专员）+ 两条护栏（输入护栏：话题与注入检测；输出护栏：回复的格式与合规检查）。代码骨架的形态（伪代码级）：定义专家 Agent（各自的 instructions 写明职责与「什么情况移交出去」）、主 Agent 挂上三个 handoff、guardrail 函数挂在输入输出——整个系统的骨架代码在百行以内——极简主义的直观展示。运行时的关键行为：主 Agent 收到「我要退款」→ 判断该移交 → 调 transfer_to_returns 工具 → 退货专员以自己的指令接管 → 专家调订单查询工具、给出处理 → 输出过护栏 → 返回用户。工程细节四条：guardrail 的判定用轻量模型（省成本——护栏是高频调用）、handoff 的「移交说明」写进专家的 description（模型据此判断何时移交——移交质量取决于职责描述的清晰度）、上下文过滤（移交时裁剪无关历史——本库上下文工程）、tracing 的复盘（每次会话的轨迹检查移交决策是否合理——tracing 不是摆设，是调移交策略的主要工具）。这个案例的元启示：三原语的组合已经覆盖「分流 + 专家 + 护栏」的完整场景——在冲向复杂框架之前，先问问三原语够不够。

与竞品的对照表：五个维度的框架速查

OpenAI Agents SDK 与主要竞品的五维对照，选型的速查表。维度一：控制流的确定性——LangGraph（图写死，最确定）> ADK（Workflow Agent 分层）> Agents SDK（模型自主，最灵活）。维度二：多智能体的形态——Agents SDK 的 handoffs（横向移交）、LangGraph 的 supervisor/网络（图结构）、CrewAI 的团队（角色团队）、AutoGen 的对话（群聊）——形态没有高下，匹配任务即可（本库多智能体形态篇）。维度三：持久化与恢复——LangGraph 的 checkpoint（最强：时间旅行）> ADK 的 Agent Engine（托管会话）> Agents SDK 的会话（轻量）——长任务的选型权重。维度四：人机协同——LangGraph 的 interrupt（流程级，最完备）> Agents SDK 的工具确认（工具级，轻量）——HITL 深度需求的权重。维度五：生态与厂商绑定——Agents SDK 绑 OpenAI（内建工具是平台专属）、ADK 绑 Google、LangGraph/CrewAI 相对中立（模型自由）。速查的使用法：先按「确定性与 HITL 需求」筛掉一半，再按「厂商生态」定终局——框架选型的本质是「你的任务需要多少确定性、你的数据能接受多少绑定」，五个维度把这两个问题拆成了可打分的项。

OpenAI Agents SDK 的局限与应对

OpenAI Agents SDK（正文哲学）的局限与应对，诚实的另一半。局限一：控制流的确定性弱。handoff 的决策交给模型——复杂流程的可靠性依赖模型（模型的「走神」让流程走偏）——应对：关键路径用确定性代码写死（handoff 之外的流程控制）、把 SDK 的灵活性留给真正的「智能决策点」（本库正文 ADK 篇的代码管流程原则同样适用）。局限二：会话与持久化的轻量。会话管理是轻量的（对话历史），长任务的 checkpoint 级持久化要自建（LangGraph 的强项区）——应对：长任务场景配外置状态（文件/数据库）或换 LangGraph。局限三：guardrails 的深度有限。内建的护栏模式简单（输入输出的分类校验），复杂的安全策略（细粒度权限、执行隔离）要自建——应对：配合 MCP 的权限体系与外部的沙箱（本库安全篇的组合）。局限四：生态的厂商引力。内建工具是 OpenAI 专属（用了就绑定）、多模型支持的深度不如中立框架——应对：SDK 本身开源支持多模型、内建工具的替代自建（trade-off 是工程量）。局限的总结：Agents SDK 的极简是把双刃剑——概念少意味着「框架不管的你得自己管」；它的正确用法是「简单场景直接用、复杂场景当积木与其他组件混搭」——框架选型的成熟标志，是知道每个框架的「不管区」。

OpenAI Agents SDK 的适用画像与学习建议

OpenAI Agents SDK（正文局限）的适用画像与学习建议。适用画像：产品以 OpenAI 模型为主（内建工具的收益最大）、需要快速上线的对话与分流类 Agent（handoffs 的主场）、团队偏好极简概念（三原语的低学习成本）、以及对 tracing 有即时需求（开箱即用的轨迹是调试刚需的解药）。不适合的画像：需要图编排的复杂流程（LangGraph 的领地）、重度多模型中立（内建工具的绑定）、以及需要深度 HITL 流程的（interrupt 级别的中断要自建）。学习建议：SDK 本身的学习成本极低（一天上手）——真正要学的是「handoff 的设计」（移交的边界与职责描述）与「guardrail 的设计」（护栏的判定逻辑）——这两个设计问题在哪个框架都存在；官方的 examples 是最好的教材（覆盖客服、研究、自动化等典型形态）。以及一个策略建议：Agents SDK 与 Responses API 的联动是它的独特资产——「平台内建工具 + 极简框架」的组合在原型期无敌——原型用 SDK 跑通、生产期评估要不要迁移到中立框架——「先跑起来再优化」在 Agent 领域通常是对的。

小结

OpenAI Agents SDK 用三原语（Agent、handoffs、guardrails）实现极简主义：handoff 把多智能体协作做成工具调用式的移交（模型自主决策、上下文延续）、guardrails 把输入输出护栏做成并行校验、tracing 开箱即用补齐可观测。Responses API 把搜索/检索/代码执行下沉为平台内建工具，previous_response_id 把对话状态管理上收服务端。它与 LangGraph 的分歧是「模型即编排 vs 代码即编排」——前者快而灵活，后者确定可审计，选型看流程复杂度与合规要求。两个流派都会长期存在，因为控制与智能的平衡点随模型能力持续移动。