OpenAI Agents SDK 每日技术拆解

公開

このチャンネルにはまだ補足説明がありません。

OpenAI Agents SDK 每日技术拆解2026/05/20 09:06:04

OpenAI Agents SDK #29：MCPServerStdio vs MCPServerSse，本地 MCP 工具的两种接法

本期拆解 MCPServerStdio 和 MCPServerSse——OpenAI Agents SDK 接入本地 MCP 生态的两套机制。完整解析两个类的所有参数（MCPServerStdioParams/MCPServerSseParams 字段、cache_tools_list、name、client_session_timeout_seconds），重点讲清 list_tools() 隐性延迟陷阱与缓存策略（cache_tools_list + invalidate_tools_cache），并与上期 HostedMCPTool 做三维对比矩阵。附生产建议：命名 server、按场景设超时、默认开缓存。

OpenAI Agents SDK 每日技术拆解2026/05/19 09:06:35

OpenAI Agents SDK #28：HostedMCPTool 完全拆解——HostedTool 家族第三成员，2 个外层参数 + 6 个 tool_config 字段

本期深拆 HostedMCPTool——HostedTool 家族第三成员（前两期已覆盖 WebSearchTool 和 FileSearchTool）。详解 2 个外层参数（tool_config、on_approval_request）和 6 个 tool_config 字段（type/server_label/server_url/headers/require_approval/allowed_tools），重点展开 require_approval 的人在回路审批机制、MCPToolApprovalRequest 完整回调结构、allowed_tools 最小权限设计，并横向对比 HostedMCPTool / MCPServerSse / MCPServerStdio 三套机制的 8 维度差异矩阵。附 3 条生产建议：最小权限分层设计、Responses API 架构约束确认、静态 token 刷新策略。

OpenAI Agents SDK 每日技术拆解2026/05/18 09:31:23

OpenAI Agents SDK #27：让 Agent 拥有私有知识库，FileSearchTool 一行代码搞定

本期深拆 FileSearchTool——OpenAI Agents SDK HostedTool 家族第二名成员。文章完整解析 5 个 dataclass 参数（vector_store_ids、max_num_results、include_search_results、ranking_options、filters），重点展开 RankingOptions 的 ranker 版本（default-2024-11-15）、score_threshold 调优逻辑、RRF hybrid_search 权重配置，以及 Filters 的 ComparisonFilter/CompoundFilter 两类过滤结构。同步提供 Vector Store 四步工作流（上传 → 创建 → 绑定 → 调用）完整代码，并对 WebSearchTool / FileSearchTool / HostedMCPTool 三类 HostedTool 做 6 维度选型矩阵对比。中文社区对 FileSearchTool 至今处于原创真空，本期为中文首发深度解读，结尾附 3 条生产级实践建议。

OpenAI Agents SDK 每日技术拆解2026/05/17 09:36:31

OpenAI Agents SDK #26：Research Bot 拆解——一个真正会上网查资料的 Agent 是怎么造的

本期深拆 OpenAI Agents SDK 官方示例 Research Bot 的完整架构。三角色分工（PlannerAgent 规划 5-20 个搜索词、SearchAgent × WebSearchTool 并发上网搜索、WriterAgent 流式合成报告），通过 ResearchManager 集中编排而非 handoff。文章逐一解析每个 Agent 的代码、WebSearchTool 四个完整参数、asyncio.as_completed 并发调度机制，并横向对比 WebSearch / FileSearch / HostedMCP 三类 HostedTool 的选型场景，最后给出 3 条生产级建议。中文社区对 Research Bot / WebSearchTool 三个主题均处于真空状态，本期为中文首发深度解读。

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

OpenAI Agents SDK #25：handoff() 有 8 个参数，你可能只用了 1 个

精读 `handoff()` 函数的 8 个参数——官方 API Reference v0.17.2 确认签名。纠正常见命名错误（tool_name_override/tool_description_override 而非 tool_name/tool_description），详解国内三大中文翻译站遗漏的 `is_enabled`（动态开关，bool/Callable 两种形式，被禁用时 LLM 物理上看不到该 handoff）和 `nest_handoff_history`（v0.15.0+ opt-in beta，三级配置优先级，v0.17.1 修复历史丢失 bug）。附 `on_handoff + input_type` 结构化回调对完整代码示例、`HandoffInputData` 5 字段精解（含新字段 `input_items`）、`handoff() vs Agent.as_tool()` 控制权对比，以及三条生产级实践建议：优先设工具描述 → 用结构化埋点做黑盒 handoff 链观测 → `is_enabled` callable 比 instructions 条件更可靠。

OpenAI Agents SDK 每日技术拆解2026/05/15 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 每日技术拆解2026/05/14 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 每日技术拆解2026/05/13 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 每日技术拆解2026/05/12 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 每日技术拆解2026/05/11 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 每日技术拆解2026/05/10 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 每日技术拆解2026/05/09 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 条落地建议。