OpenAI Python SDK v3.20.0发布：Agents凭证与WebSocket增强

OpenAI 官方 Python SDK 迎来 v3.20.0 版本更新。这次发布聚焦于 Agents 能力扩展、Responses API 的实时 WebSocket 优化，以及一系列针对实时（Realtime/Live）场景的连接稳定性修复。对于正在用该 SDK 构建 AI 应用的开发者来说，这是一次偏向工程稳定性与实时交互体验的迭代。

新增功能：Agents 与 Responses 能力扩展

本次版本在 API 层面带来了几项值得关注的新能力。SDK 为 Agents 增加了凭证（credential）与会话（session）配置选项（#3967），这意味着开发者在构建基于 Agent 的工作流时，能够更灵活地管理鉴权与会话状态，为多轮、多工具调用的复杂场景提供更细粒度的控制。

另一边，Responses API 新增了 Cyber access programs 支持（#3956），进一步丰富了该接口的功能覆盖面。

在实时交互方面，Responses 引入了两项 WebSocket 相关的改进：一是支持按需（opt in）接收增量的 WebSocket 文本与工具调用快照（#3973），二是保留更详细的 WebSocket accumulator 快照（#3981）。这两项改进共同指向一个目标——让流式输出的中间状态更完整、更可观测，便于开发者实现更精细的实时渲染与调试。

WebSocket accumulator 快照是实时流式场景中的一个关键机制。在流式传输过程中，服务器会将响应拆分成多个增量片段（delta）逐步推送，accumulator 负责将这些片段累积拼合成完整的中间状态。保留更详细的快照意味着开发者在任意时刻都能读取到当前已接收内容的完整视图，而不仅仅是最新的增量片段。这对于需要在流式输出中途做渲染、解析或条件判断的场景尤为重要——例如在工具调用参数尚未完整到达时提前检测调用意图，或在语音合成场景中以句子为单位触发播报。

Bug 修复：实时连接稳定性成为重点

如果说新功能是锦上添花，那么这一版的 Bug 修复才是真正解决开发者痛点的部分。修复列表高度集中在实时（Live）与实时（Realtime）WebSocket 连接的可靠性上。

客户端层面，SDK 现在会对未映射的 TLS 传输错误进行重试（#3982），降低了因底层网络抖动导致请求直接失败的概率。

实时（Live）场景修复了多个棘手问题：在分数级（fractional）转录分组截止时间附近避免出现挂起（#3970）；将查询参数从 WebSocket 端点路径中剥离出来（#3972），避免路径拼接错误；以及保留调用方队列、防止不确定的 WebSocket 重放（#3980）。

Realtime 场景同样得到加固，包括在 WebSocket 升级过程中保留基础 URL 的查询参数（#3971），以及保留已配置队列而不重放尝试过的发送请求（#3978）。这几项修复的共同主题是——在连接升级、重连与重放过程中，保证消息队列状态的确定性，避免数据重复发送或丢失。

WebSocket 升级（WebSocket Upgrade）是指客户端通过标准 HTTP 请求发起协议切换，将连接从 HTTP/HTTPS 升级为持久的 WebSocket 双向通道的过程。这一握手阶段相对脆弱：若升级请求携带的查询参数在路径拼接时被错误处理，或升级失败后重连时未能正确恢复队列中尚未发送的消息，就会产生数据丢失或重复发送的问题。此次修复针对的正是这类边界情况——确保升级过程中基础 URL 的查询参数被完整保留，以及重连后消息队列的状态是确定性的，从根本上避免了偶发的消息乱序与重放异常，这类问题在高并发或网络质量不稳定的生产环境中往往极难复现和定位。

文档完善：错误响应说明更系统

本次的 Chores（杂项）部分几乎全是关于 API 错误响应文档的梳理工作。SDK 对多个接口的错误响应进行了明确和补充，覆盖了批处理（batch）错误（#3961）、文件与上传错误（#3960）、微调与模型错误（#3964）、Responses 的 not-found 错误（#3959）、已存储聊天补全（stored chat completion）错误（#3963），以及整体 API 错误响应的澄清（#3965）。

这类改动虽然不涉及代码行为变化，但对开发者的实际价值不容低估——清晰的错误文档意味着更快的问题定位和更少的调试成本。

对开发者意味着什么

综合来看，v3.20.0 是一次典型的"打磨型"版本。它没有颠覆性的大功能，但在两个方向上做得扎实：一方面通过 Agents 凭证/会话选项和 Responses 的新特性，扩展了高阶应用的构建能力；另一方面，大量集中于 WebSocket 与实时连接的修复，直接提升了语音、流式交互等场景下的稳定性。

对于已经在生产环境使用该 SDK 的团队，尤其是依赖 Realtime 或 Live 接口构建实时语音/对话应用的开发者，建议评估升级——队列状态与重放相关的修复，往往能解决一些偶发且难以复现的线上问题。

升级方式依旧简单，通过 pip 更新到 3.20.0 即可获取全部改进。