OpenAI Agents SDK 每日技术拆解

Public

No additional description for this channel yet.

OpenAI Agents SDK 每日技术拆解05/15/2026, 09:40:35

OpenAI Agents SDK #24：两种护栏写法，一个不让 LLM 裸奔的理由

精读 `agent_patterns/` 目录下 `input_guardrails.py`（122 行）和 `output_guardrails.py`（80 行）两个官方护栏示例。前者展示 Agent-based 写法：用独立的 `guardrail_agent`（`MathHomeworkOutput` 结构化输出 + `Runner.run` 嵌套调用）做 LLM 语义判断，捕获 `InputGuardrailTripwireTriggered` 后手动追加拒绝消息保持多轮对话不断链；后者展示 Rule-based 写法：纯 Python 字符串匹配检查输出内容，零延迟零 Token。配 6 维对比矩阵（判断方式/延迟/Token/适用场景/误判风险/扩展方式），说明两种写法与 #8 API 层的层次关系，并给出 `run_in_parallel` 权衡、异常捕获连续性三条实践建议。当前版本 v0.17.2，v0.17.1 含三项 guardrail 运行时 bug 修复。

OpenAI Agents SDK 每日技术拆解05/14/2026, 09:30:58

OpenAI Agents SDK #23：把路由逻辑写进 instructions，然后什么都不用写了

精读 `routing.py`（77 行）的完整实现：4 个 Agent 的定义逻辑（triage_agent + 3 语言专家）、`Runner.run_streamed` + `stream_events` 流式对话循环、`result.current_agent` 的多轮保持机制。深入 handoff 内部原理——LLM 如何通过 `transfer_to_<agent_name>` tool call 实现路由、agent loop 如何在同一 run 内切换 Agent。附 `handoff()` 函数 6 个关键进阶参数详解，以及 Routing / Deterministic / Parallelization / LLM-as-Judge 四模式 7 维度横向对比矩阵，结尾三条生产落地建议覆盖路由粒度设计、误路由防护（`is_enabled` + `input_filter`）和 fallback 策略（`on_handoff` 日志 + 兜底 Agent）。

OpenAI Agents SDK 每日技术拆解05/13/2026, 09:33:56

OpenAI Agents SDK #22：同一个 Agent 跑三遍，然后选最好的那个

精读 `parallelization.py`（65行）的完整实现：`asyncio.gather × 3` 并发模型、`ItemHelpers.text_message_outputs()` 提取纯文本、`translation_picker` 择优（fan-in）、`trace` 上下文包裹。拆解 Parallelization 的两大使用场景（延迟优化 fan-out 分工 vs 同任务多跑 best-pick），对比 `asyncio.gather` 与 `Agent.as_tool() + parallel_tool_calls` 两条实现路径，并附 Parallelization / Deterministic / LLM-as-Judge 三模式横向对比矩阵。结尾三条实践建议覆盖路径选择、picker 结构化输出、温度设置对 best-pick 质量的影响。

OpenAI Agents SDK 每日技术拆解05/12/2026, 09:36:37

OpenAI Agents SDK #21：让 LLM 当裁判，但别让它审无限轮

精读 `llm_as_a_judge.py` 89 行源码，拆解双 Agent 循环架构（`story_outline_generator` + `evaluator`）、`EvaluationFeedback` dataclass 三值评分设计、`to_input_list()` 全量上下文链 + `auto_mode` 双层安全阀，并与上期 Deterministic Flows 对比（迭代改进 vs 门控硬停），最后给出三条生产级落地建议：结构化输出是循环终止前提、while 必须有代码出口 + 语义出口双保险、Judge Prompt 校准流程。

OpenAI Agents SDK 每日技术拆解05/11/2026, 09:31:55

OpenAI Agents SDK #20：别让 LLM 做它不该做的决定

精读 OpenAI Agents SDK 的 `deterministic.py` 示例源码（84 行），讲清「代码驱动」与「LLM 驱动」两种编排哲学的本质区别——前者用 Python 原生控制流（`if/else`、`asyncio`）决定 Agent 执行顺序，后者让 LLM 自主规划。重点拆解三段式流水线（`story_outline_agent → outline_checker_agent → story_agent`）、Pydantic 结构化输出配合 gate 机制、`trace()` 上下文管理器，以及 Runner 的 Agent Loop 工作原理，附三条可落地实践建议。

OpenAI Agents SDK 每日技术拆解05/10/2026, 09:10:18

OpenAI Agents SDK #19：拆开 RealtimeSession，那 20 种事件你只处理了 3 种

深度拆解 Realtime Agents 内部实现：RealtimeAgent 与普通 Agent 的 4 个关键差异、Runner 与 Session 的工厂/连接分工、Session 7 个核心 API、近 20 种 event.type 按音频/历史/生命周期/工具/底层分组解读、RealtimeRunConfig 6 字段与 VAD 两种模式、Transport 层两条路径，以及 voice 锁定、exception 重抛等 6 个生产坑。

OpenAI Agents SDK 每日技术拆解05/09/2026, 12:16:05

OpenAI Agents SDK #18：拆掉黑盒，「三段流水线」里究竟跑着什么？

从「复制 quickstart 就以为会了」的真实踩坑切入，系统拆解 VoicePipeline 内部实现。覆盖三步流水线全景（AudioInput vs StreamedAudioInput 分发逻辑）、STT/TTS 模型替换两条路径（直接传实例 vs VoiceModelProvider 依赖注入）、TTSModelSettings 7 个字段深度拆解（含 instructions 默认值设计哲学与 text_splitter 中文场景调优）、VoiceWorkflowBase 与 SingleAgentVoiceWorkflow 适用场景对比、StreamedAudioResult 三种 VoiceStreamEvent 消费完整代码与两大生产坑、VoicePipelineConfig 10 个字段三组分类记法，以及 StreamedTranscriptionSession 与 StreamedAudioResult 的类名澄清（SDK 中不存在 VoiceStreamingSession）。附生产环境最佳实践代码与 3 条落地建议。

OpenAI Agents SDK 每日技术拆解05/08/2026, 10:40:03

OpenAI Agents SDK #17：两套语音子系统，你选对了吗？GPT-Realtime-2 今日上线

本期系统拆解 OpenAI Agents Python SDK 中两套完全独立的语音子系统——Realtime Agents（WebSocket 音频直通流，Beta）与 Voice Pipeline（STT→Agent→TTS 三段流水线，正式版），通过架构对比、核心 API 详解、VAD 踩坑经验和延迟预算模型帮助开发者做出正确选型。以当日上线的 GPT-Realtime-2（GPT-5 级推理语音模型）为开篇钩子，结合国内四大厂商横评和打断逻辑实践建议收尾。

OpenAI Agents SDK 每日技术拆解05/07/2026, 09:56:06

OpenAI Agents SDK #16：Runner 跑完之后，你真的知道手里拿着什么吗？

从「`print(result.final_output)` 输出 None」和「直接把 result 传给下一轮导致对话污染」两个高频坑切入，系统拆解 `RunResultBase` → `RunResult` → `RunResultStreaming` 的三层继承结构、`final_output` 三态逻辑、`new_items` 13 种 RunItem 子类型、`to_input_list()` 两种模式、`last_agent` 动态路由、Guardrail 结果数组，以及流式场景的必消费约定与 `cancel()` 两种模式，附 3 条可落地实践建议。

OpenAI Agents SDK 每日技术拆解05/06/2026, 09:14:40

OpenAI Agents SDK #15：一个 Agent 搞不定——加一个真的够吗？

从「加三个 Agent 并发就能解决问题吗？」这个真实痛点切入，系统拆解 OpenAI Agents SDK 的两种多 Agent 编排范式——LLM 驱动（Orchestrator 自主决策）与代码驱动（确定性流水线）。深入讲解 `as_tool()` 与 Handoff 的本质区别、`asyncio.gather` 并发的适用边界与代码示例、多 Agent 间 Context 的流转机制，并结合中文社区的三个高频踩坑（上下文丢失、依赖并发错误、max_turns 失控），给出 3 条立即可落地的实践建议。

OpenAI Agents SDK 每日技术拆解05/05/2026, 09:16:37

OpenAI Agents SDK #14：Agent 刚要删库，你却毫无感知——Human in the Loop 全解析

从「Agent 自动调用删库接口却无法阻止」的危险场景切入，系统拆解 OpenAI Agents SDK 的 Human in the Loop 机制。覆盖 needs_approval 静态/动态标注、RunState 序列化跨进程持久化、state.approve()/reject() 审批操作、Runner.run() 与 run_streamed() 的中断工作流，附完整基础示例与生产级持久化审批代码，兑现上期预告的 Sessions + HITL 结合用法，并澄清「InterruptedError」常见误解，结尾对比 Guardrails 边界，给出 3 条落地建议。

OpenAI Agents SDK 每日技术拆解05/04/2026, 09:18:22

OpenAI Agents SDK #13：每次多轮对话都要手写 `.to_input_list()`？Sessions 帮你彻底告别这个坑

从「每轮对话都要手写 .to_input_list() 拼接历史」这个高频痛点切入，系统拆解 OpenAI Agents SDK Sessions 机制。覆盖 Sessions 工作原理（Runner 运行前自动注入历史、运行后自动追加）、SQLiteSession 快速上手、10 种 Session 后端全景对比（SQLite / AsyncSQLite / Redis / SQLAlchemy / MongoDB / Dapr / OpenAI Conversations / OpenAI Responses 压缩 / AdvancedSQLite / EncryptedSession）、session_input_callback 自定义历史合并逻辑、SessionSettings(limit=N) 控制历史长度、pop_item() 修正对话技巧、SessionABC 自定义后端实现，以及 Sessions + RunState 结合 Human in the Loop 中断恢复的核心用法。结尾给出 3 条生产建议，预告 #14 Human in the Loop。