Pydantic AI v2.54.0 发布：实时会话掉线可自动恢复，默认连接池对齐 OpenAI SDK

Pydantic AI 于 2026 年 10 月 3 日发布 v2.54.0。可用可看的改动有三处：OpenAI 实时（realtime）会话掉线后可以自动重连并重放上下文、框架自建的 HTTP 客户端默认沿用 OpenAI SDK 的连接池参数、以及给 Exa 与 You 两家搜索加了走模型原生搜索的开关。同时有一批面向可靠性与沙箱边界的修复。

这次发布的是什么

Pydantic AI —— 由 Pydantic 团队维护的 Python 智能体框架 —— 于 2026 年 10 月 3 日发布 v2.54.0（release 标题标注为 2026-10-02 的变更集合）。这一版不是大改 API，但落在三个开发者天天会碰的地方：连接能不能撑住、报错能不能定位、搜索走哪条路。

第一处是实时会话的断线恢复。官方条目写明：OpenAI 实时模型（OpenAILiveModel）的会话掉线之后，可以从已保存的会话 fork 出来继续，或者重放历史记录重建上下文——语音类应用最怕的就是网络抖动一次整通对话重来。

第二处是连接池口径统一。框架自己创建的 HTTP 客户端现在默认沿用 OpenAI SDK 的连接池限制，并把 create_async_httpx2_client 变成公开接口；以往自己配连接池时容易和 SDK 的默认行为对不上，现在两边不再打架。

第三处是搜索路径的选择权。ExaSearch 与 YouSearch 新增 native 选项，让开发者明确选择走模型自带的原生搜索；配套的 web_search_tool() 也支持 WebSearch(local=...) 这种写法。此外 OpenAI 的实时接口侧还有两条更新：默认的输入转录模型改为 gpt-live-transcribe（同时列出 gpt-transcribe），以及 WebSearchTool 可以通过委派后端跑到 GPT-Live 上。

影响谁：用 Python 写语音助手或长会话智能体的团队；在服务端同时用多个模型 SDK、被连接池参数困扰的工程团队；以及把「搜索」当成核心能力的智能体项目。

可用性与限制

• 分支与版本：本次是 2.x 线上的版本号为 2.54.0 的常规更新，Python 包从 PyPI 安装；是否提供其他分发包以官方说明为准。
• 实时模型侧：新提到的模型名（如用于转录的 gpt-live-transcribe 与 gpt-transcribe）属于 OpenAI 侧的具体模型与后端配置，可用范围与计费口径以 OpenAI 官方说明为准。
• 沙箱能力：本次有一批与执行环境相关的修复，涉及远端 workspace 的命令执行路径与符号链接判定；用到沙箱执行的团队建议单独回归（详见「常见问题」）。
• 破坏性提示：本版带若干兼容性条目，例如 hook 的包裹范围改为覆盖完整的阶段生命周期、同一 agent 在绑定前拒绝第二个持久化执行引擎、后台工具抛出预期外异常时结束整轮运行。升级前建议先在测试环境跑一遍既有流程。
• 网络与区域：模型提供商本身在境内的可达性因供应商而异，以各自官方说明与你的实际网络环境为准。

主要功能

• 掉线的实时会话可从保存的会话继续
• 显必要时可重放历史重建上下文
• 默认连接池对齐 OpenAI SDK 的参数
• 给搜索工具加上走原生搜索的开关
• 让 Web 搜索工具可跑到 GPT-Live
• 未声明返回结构的告警单独成类

技术原理

按官方说明，这一版的改动有一条清晰的隐线：把「不确定性」变成「可预测」。

先看连接。异步 HTTP 客户端的连接池参数决定了并发请求如何复用 TCP 连接；当框架自身的池限制与某个 SDK 内置的限制不一致时，两边会各自维护一套资源，表面上都在跑，实际可能一边在排队、一边在等超时。把默认池改成对齐 OpenAI SDK 的限制，并把 create_async_httpx2_client 公开出来，等于是把这件事从「碰运气」变成「有一条明确的基线」。

再看实时会话。realtime 类接口的会话状态由服务端持有，客户端手里的是一串历史事件。掉线之后能不能接着聊，取决于能不能把上下文还回去——所以官方给了两条路：从已保存的会话 fork（服务端还有状态可直接续），或者重放本地历史（服务端状态已丢，靠客户端重放重建）。同一批里还有一条：OpenAI 实时模式的 barge-in 截断按 profile 的音频输出采样率取值，属于把音频侧的边界对齐。

最后是搜索。所谓「模型原生搜索」，指的是不让第三方工具包办检索，而是让模型自带的内建检索走完整个流程；Exa 与 You 两家加了 native 选项，就是把这条岔路口的选择权交给调用方。OpenAI 侧的 WebSearchTool 通过委派后端上到 GPT-Live，是同一类思路：同一个工具，可以有不同承载。

实际体验

不写主观实测，给一套可复现的验证顺序。

第一步，升级并记录版本号。在虚拟环境里装到 2.54.0，把确定装上的版本号写进变更记录，而不是依赖允许自动取次版本的范围写法。

第二步，测实时会话恢复。手动把网络断开几秒再恢复，观察会话是重新一轮还是接着上一句；如果预期是「接着聊」，确认你的配置走的是「从保存的会话 fork」这条路径还是「重放历史」这条。两者对服务端状态的依赖不同，选错会表现成上下文丢失。

第三步，观测连接行为。把并发压上去，记录升级前后超时与错误率的变化；若此前为了绕开池参数写过自定义配置，试着去掉，看默认的新行为是否已经够用。

第四步，验证告警是否可定位。故意写一个没有声明返回结构的 CodeMode 场景，确认抛出的告警类别是本次拆出来的那个类别，便于在日志里单独过滤。

第五步，单独回归沙箱相关场景。本次有一批修复围绕沙箱与执行路径（例如某些 workspace 的 PATH 处理与符号链接判定），用到沙箱执行的团队建议针对性跑一次。

项目地址与获取方式

官方仓库是 github.com/pydantic/pydantic-ai，本次发布在该仓库 releases 的 tag v2.54.0（同一份 release 说明里也列出了 v2.53.0 到 v2.54.0 之间的完整变更清单，排查问题时可以直接对照）。Python 包从 PyPI 安装，包名 pydantic-ai；命令行工具与额外可选依赖以官方文档为准。请通过官方渠道获取，避免安装被篡改的版本。

适合谁用

• 用 Python 写语音助手、实时对话或多轮长会话智能体的团队：实时会话恢复是本版最容易见效的一条。
• 同时接多家模型 SDK、被并发与超时问题缠住的服务端项目：连接池口径统一能省掉一轮调参。
• 把检索当成核心能力、需要在「模型原生搜索」与「第三方检索」之间做取舍的项目：native 开关正是为此设计的。
• 已经在用本框架、且升级窗口灵活的团队：本版带兼容性条目，建议留出回归时间。
• 不必急着动的：只用基本文本生成、既不用实时通道也不碰搜索的项目，这一版的收益有限，按自己的节奏安排即可。

常见问题

这次更新会不会改动我现有的调用方式？

常规用法基本不用改。需要留意的是本版列了几条兼容性条目：hook 的包裹范围改为覆盖完整的阶段生命周期、同一 agent 尚未绑定时拒绝挂第二个持久化执行引擎、后台工具抛出预期外异常时会结束整轮运行。如果你在这些机制上做过定制，建议先通读 release 里的兼容性一段再升级。

实时会话掉线后，恢复路径该怎么选？

看服务端还认不认这个会话。会话状态还在时，从已保存的会话 fork 是最省事的做法；会话彻底失效时，只能靠客户端重放历史重建上下文。两条路都在本版里可用，选错的表现通常是上下文忽然「断片」。真机上建议把网络抖动做成回归用例跑一遍。

为什么要把连接池参数对齐 OpenAI SDK 的默认限制？

因为两边的池参数不一致时，资源会各管各的：一边在复用连接，另一边可能已经在排队或超时。把框架的默认池改成对齐 OpenAI SDK 的限制，相当于给了一个明确的基线，省掉重复调参；如果你的场景有明确的高并发需求，再用本次公开出来的 create_async_httpx2_client 单独配。

沙箱执行相关的修复对我有影响吗？

如果你用到了沙箱（包括远端或容器化的执行环境），建议专门回归一次。本版有一批修复围绕这类边界：例如避免某些 workspace 通过 PATH 或启动脚本在宿主机上执行代码、以及在符号链接读不出来时按失败处理。这些改动通常不改变正常路径的行为，只在异常路径上收紧。

和同类工具相比该怎么选？

本站不做工具间的高低判定，只给一条实用建议：按你已经在用的语言栈与托管形态来选。偏好 Python、希望模型调用层类型严格、又要拿住会话状态的团队，本框架是顺手的；如果你更依赖可视化编排，可以先看Dify一类方案，或者从AI 智能体分类下按场景横向对照。想了解开源模型侧近期的动静，可以参考OLMo-core 3 发布。

相关工具与内容

如果你正在选 Python 侧的框架，这份更新值得一读：本机多数 PyPI 与 GitHub 源的访问速度以各自网络环境为准。落地时可以沿着AI 编程分类找配套工具，例如把Claude Code接到同一套仓库工作流里，或对照CodeBuddy看 IDE 侧的同类形态。模型层一侧，OLMo-core 3 发布记录了近期开源模型训练栈的进展；把流程编排摆在明面上的Dify则是另一条路径。