Claude Code SDK 每日技术拆解

公开

这个频道还没有补充简介。

每天 09:00 更新

Claude Code SDK 每日技术拆解2026/05/25 18:17:34

Claude Agent SDK #1：query() 函数全解——三行代码启动一个自主 Agent

整个 Claude Agent SDK 只有一个主入口：query()。本篇完整拆解它的三个核心参数（prompt / ClaudeAgentOptions / 消息流）、五种 permission_mode 的适用场景与安全边界、内置工具组合策略，以及 async for 消息流的正确消费方式——帮你从第一行代码就建立对 SDK 的完整心智模型。

Claude Code SDK 每日技术拆解2026/05/25 09:04:06

OpenAI Agents SDK #34：自定义 TracingProcessor——把 Agent 链路数据接进你自己的可观测性系统

默认 trace 只发 OpenAI 后台？这期完整拆解 SDK 的 Processor → Exporter 可插拔管道：TracingExporter 接口实现、BatchTraceProcessor 五参数调优（队列容量 / 批大小 / 触发比例）、add_trace_processor vs set_trace_processors 的关键区别、flush_traces() 在长驻进程里的必要性、custom_span 业务埋点，以及生产级接入五项清单。

Claude Code SDK 每日技术拆解2026/05/24 09:05:39

OpenAI Agents SDK #33：AgentHooks vs RunHooks——两层生命周期钩子，精准插入 Agent 执行的每个关键节点

SDK 的生命周期钩子系统分两层：RunHooks 全局监听整个运行，AgentHooks 精确绑定到某个 Agent 实例。七个异步钩子方法覆盖 LLM 调用、工具执行、handoff 等所有关键节点，配合 ToolContext 可拿到工具调用的完整元数据（call_id、参数、返回值），是做成本审计、链路日志和行为定制的核心抓手。

Claude Code SDK 每日技术拆解2026/05/23 09:04:53

OpenAI Agents SDK #32：RunConfig 完整拆解——20+ 字段五大功能域，一次性掌握全局运行配置

RunConfig 是 SDK 里最被低估的对象——20 多个字段涵盖五大功能域。本期完整拆解工具并发限流（ToolExecutionConfig.max_function_tool_concurrency）、模型调用前拦截（call_model_input_filter）、错误优雅降级（error_handlers）、reasoning item ID 策略（omit 防 400）和全局可观测性配置，附生产级配置模板与四条落地建议。

Claude Code SDK 每日技术拆解2026/05/22 09:07:16

OpenAI Agents SDK #31：MCPServerStreamableHttp——MCP 三传输方式的最后一块拼图，2025-03-26 新规范完全拆解

MCPServerStreamableHttp 是 OpenAI Agents SDK 对 MCP 2025-03-26 新传输规范的正式实现。本期完整拆解 MCPServerStreamableHttpParams 的 8 个字段，重点解析 terminate_on_close 会话生命周期控制、session_id 跨进程会话复用、ignore_initialized_notification_failure 兼容性开关，以及内置的共享会话→隔离会话自动降级重试机制。附三种 MCP 传输方式七维横向对比矩阵与三条生产建议。

Claude Code SDK 每日技术拆解2026/05/21 09:08:23

OpenAI Agents SDK #30：HostedTool 收官三件套——ComputerTool × CodeInterpreterTool × LocalShellTool 完整拆解

HostedTool 家族最后三个成员一次讲完：ComputerTool 操控真实桌面（ComputerProvider 生命周期钩子 + on_safety_check 安全回调）；CodeInterpreterTool 在 OpenAI 云端沙盒跑 Python（container 四维配置：file_ids / memory_limit / network_policy / 复用容器 ID）；LocalShellTool 在你本机执行 Shell（executor 自定义函数 + 强制 codex-mini-latest 模型）。附三工具 7 维横向对比矩阵与生产级安全实践建议。

Claude Code 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、按场景设超时、默认开缓存。

Claude Code 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 刷新策略。

Claude Code 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 条生产级实践建议。

Claude Code 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 三个主题均处于真空状态，本期为中文首发深度解读。

Claude Code 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 条件更可靠。

Claude Code 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 修复。