pydantic-ai v2.63.0 发布：支持 ag-ui 协议 1.0 与 GPT-6.1 Terra，新增循环检测

Python 智能体框架 pydantic-ai 于 2026 年 10 月 28 日发布 v2.63.0。这一版新增对 ag-ui-protocol 1.0 的支持、加入 OpenAI 的 gpt-6.1-terra 模型、提供 DetectLoops 能力用于打断重复动作循环，并新增 IPython Code Mode 与基于 PostgreSQL 的额度存储。同时有若干兼容性变更，包括 CodeMode 默认改为 dynamic_catalog=True。

这次发布的是什么

Python 智能体框架 pydantic-ai 在 2026 年 10 月 28 日发布了 v2.63.0（GitHub 上的发布时间为 2026-10-28T00:55:47Z，PyPI 上的上传时间交叉一致）。发布正文按兼容性说明、新功能、缺陷修复三部分组织，其中最值得看的是几项新能力和几处会影响既有代码的默认值变更。

新增能力里，与前端协作相关的是对 ag-ui-protocol 1.0 的支持；与模型相关的是加入了 OpenAI 的 gpt-6.1-terra 模型支持；与运行稳定性相关的是新增 DetectLoops 能力，用来打断智能体反复执行同一动作的循环。此外还有 IPython Code Mode、以及让 Harness 的额度预算可以通过 PostgreSQL 共享的 PostgresSpendStore。

可用性与限制

• 获取方式：开源发布在 GitHub，同时可从 PyPI 安装。
• 兼容性变更一：CodeMode 默认改为 dynamic_catalog=True，新揭示的工具以追加方式加入，不再重写已缓存的提示。
• 兼容性变更二：Gemini Live 的重连回放改为以仅关键字参数 replay 传给 GoogleRealtimeConnection 的 dial 方法。
• 兼容性变更三：Harness 的 LLMReminder 默认 interval 改为 10，不再每次请求都生成。
• 依赖要求：MistralModel 现要求 mistralai>=3.1.0，并移除了旧版 httpx 的导入方式。
• 部分能力标注为能力（capability）级别，启用与组合方式以官方文档为准。

主要功能

• 支持 ag-ui-protocol 1.0，便于与前端界面协议对接
• 新增 OpenAI gpt-6.1-terra 模型支持
• 新增 DetectLoops 能力，用于打断重复动作循环
• 新增 IPython Code Mode（IPythonCodeMode），与基于 Monty 的 CodeMode 并存
• 新增 PostgresSpendStore，让 Harness 的 SpendLimits 预算可通过 PostgreSQL 共享
• 新增公开模块 pydantic_ai.framing，提供 wrap、neutralize_tags 与 register_tag

技术原理

这一版里最能说明框架走向的，是「把运行时的稳定性问题做成可插拔能力」这个思路。DetectLoops 就是一个典型：智能体在长任务里容易陷入反复调用同一工具、反复产出同一动作的循环，这类循环不会报错，只会安静地烧掉 token。把它做成一个可启用、可组合的 capability，意味着框架开始把这类运行时病理当作一等公民，而不是留给使用者自己写超时逻辑。

CodeMode 这一侧的变更是另一种性质。默认改成 dynamic_catalog=True 后，新揭示的工具以追加方式加入，而不是重写已经缓存的提示。这直接关系到提示缓存能不能命中——重写提示意味着缓存前缀失效，长会话里这笔开销不小。它同时也是一处兼容性变更：依赖旧行为的代码需要检查。

framing 模块被公开出来是第三类变化。wrap、neutralize_tags、register_tag 这三个函数被做成公开接口，作用是让扩展可以自己定义并转义自己的标签。把「如何给模型看结构化边界」这件事开放出去，等于承认框架内置的那套标签不可能覆盖所有扩展场景。同时正文里还有一批修复是在统一各处标签的转义方式，这说明此前不同模块的处理并不一致。

实际体验

升级这一版之前，建议按下面顺序做，重点是先确认兼容性变更是否影响到你。

第一步，先读发布正文里的兼容性说明那一段。这一版有三处默认值与签名变化：CodeMode 的 dynamic_catalog 默认、Gemini Live 重连回放的参数形式、Harness LLMReminder 的默认 interval。任何一处命中你的用法，都要先在测试环境验证。

第二步，如果用了 Mistral 模型，检查依赖版本。这一版要求 mistralai>=3.1.0，并移除了旧的 httpx 导入方式，fresh install 上才能正常导入 MistralModel。

第三步，再试新能力。DetectLoops 适合先在你已经观察到循环的场景上启用，观察它打断的时机是否合适——太早会误伤正常重试，太晚则省不下多少。

第四步，如果有多进程或多实例共享预算的需求，再看 PostgresSpendStore。它解决的是 SpendLimits 预算在不同实例间不通的问题，单实例场景下不必引入。

项目地址与获取方式

项目开源在 GitHub 的 pydantic/pydantic-ai 仓库，Python 包发布在 PyPI。请通过官方 PyPI 源安装并核对版本号与发布说明，不要使用第三方镜像或未署名分发的构建，以免安装到被篡改的包。具体的安装方式、可选依赖与各能力的启用方式以官方文档为准。

适合谁用

• 用 Python 写智能体、并且已经用到 CodeMode 的团队：这一版的默认值变更需要先验证。
• 需要把智能体接到前端界面的项目：ag-ui-protocol 1.0 的支持值得先读文档确认覆盖范围。
• 长任务容易跑飞、反复调用同一工具的场景：DetectLoops 是针对性的能力。
• 多实例部署、需要统一额度预算的服务：PostgresSpendStore 解决的是这一类问题。
• 暂时不必急着升：只用基础对话与结构化输出、且不触碰上述变更的项目，可等下一个补丁版。

常见问题

升级到 v2.63.0 会改掉我现有的行为吗？

有可能。发布正文的兼容性说明列了三处：CodeMode 默认改为 dynamic_catalog=True、Gemini Live 的重连回放改为仅关键字参数 replay、Harness 的 LLMReminder 默认 interval 改为 10。命中其中任何一处的项目都应先在测试环境验证。

DetectLoops 是做什么的？

按发布说明，它是一个用于打断重复动作循环的能力。智能体在长任务里可能反复执行同一动作而不报错，DetectLoops 用来识别并中断这种情况。启用方式与触发阈值以官方文档为准。

新增的 IPython Code Mode 和原来的 CodeMode 冲突吗？

不冲突。发布说明写的是「在基于 Monty 的 CodeMode 之外新增 IPythonCodeMode」，两者并存，可按场景选择。

为什么要把 framing 模块公开出来？

公开的是 wrap、neutralize_tags 与 register_tag 三个函数，作用是让扩展能够自己定义并转义标签。对只使用框架内置能力的用户没有直接影响，但写自定义扩展时会用到。

装不上或导入报错怎么办？

这一版明确要求 mistralai>=3.1.0，并移除了旧的 httpx 导入方式，使用 MistralModel 的项目需先升级依赖。其他依赖冲突请以官方发布说明与依赖清单为准。

相关工具与内容

• Pydantic AI 2.61.0：引用结构化与新模型名入库
• Pydantic AI v2.57.0：接入 Meta Muse 模型、工具调用可先由模型审批
• FastMCP 同发 4.0.11 与 3.4.8
• AI 编程
• AI Agent
• AI 办公助手