agno v2.6.9 最新版发布：审批记录可直读、PgVector 前缀检索修复、Claude 0 参数终于生效，全面升级实战体验

在这里插入图片描述

在这里插入图片描述

在这里插入图片描述

2026年5月22日，Agno 发布了 v2.6.9。 这一次更新虽然版本号不大，但内容非常扎实，属于典型的“看起来是小版本，实际上修了不少关键问题”的升级。 从 审批流后 Hooks 的可观测性增强，到 PgVector 前缀匹配真正可用，再到 Claude 系列模型 temperature/top_p/top_k=0 终于不再被静默丢弃，以及 GeminiInteractions 在 agent 路径上的工具调用修复，都直接影响到开发者在真实项目中的稳定性和可控性。

如果你正在使用 Agno 构建 Agent、Workflow、知识库检索、审批流、或者接入 Claude / Gemini / PgVector，那么这次版本更新值得认真看完。 下面我会按照 新特性、优化、Bug 修复、变更清单 的顺序，结合本次官方发布内容，做一篇适合 CSDN 发布的技术文章整理，帮助你快速理解 v2.6.9 到底升级了什么、修了什么、为什么重要。

一、v2.6.9 发布概览

本次版本发布的核心关键词可以概括为：

• • 审批信息更完整
• • PgVector 前缀搜索真正可用
• • Claude 的 0 参数不再失效
• • Calendar / Gmail 指令层更清晰
• • 决策日志兼容 Python 3.12
• • Gemini agent 路径工具调用错误修复
• • Chonkie 升级带来语言自动识别修复

这些内容并不是简单的“功能堆砌”，而是围绕几个实际开发痛点进行修正：

1. 1. 可观测性更强：后 hooks 和 observability integration 现在可以拿到完整的审批解析记录。
2. 2. 检索能力更准：PgVector 的 prefix_match 不再是无效参数。
3. 3. 模型参数更可靠：Claude 相关参数为 0 时终于能按预期传递。
4. 4. Agent 执行更稳定：GeminiInteractions 不再把 server-side tool calls 错误暴露为本地 tool_calls。
5. 5. 配置和兼容性更干净：一些废弃写法和冗余文案被清理，减少维护成本。

二、新特性：审批记录在 Post-Hooks 中可完整读取

本次最值得关注的新特性之一，是 审批记录在 post-hooks 和 observability integrations 中可完整读取。

1）更新前的问题

在之前的版本里，运行结果中的审批信息暴露得比较有限。 开发者在后置 hook、观测集成中，通常只能看到：

• • status
• • resolution_data

这意味着很多关键审批上下文并没有直接暴露出来，例如：

• • resolved_by
• • resolved_at

对于需要做审计、记录审批链路、或者在 observability 系统中还原完整审批状态的场景来说，这显然不够。

2）本次更新的变化

现在，完整的 resolved approval record 可以通过：

• • run_response.metadata["approval"]

来读取。

这条信息的意义非常大，因为它被放在 metadata 中，所以具备统一性：

• • 对 RunOutput 生效
• • 对 TeamRunOutput 生效
• • 未来也能自然适配 WorkflowRunOutput

也就是说，Agno 不再把审批信息限制在某个特定输出对象的某个局部字段，而是统一放进 metadata 里，方便不同运行类型以一致方式读取。

3）这对实际开发意味着什么

这项改进主要带来三类收益：

• • 更完整的审计信息
• • 更方便的后处理逻辑
• • 更统一的数据结构设计

如果你在做审批流、风控流程、运维审批、AI 辅助决策记录，那么这次更新之后，你可以更自然地在 post-hook 中拿到完整审批结果，减少二次拼装和字段缺失带来的问题。

三、PgVector 优化：prefix_match=True 终于真正生效

这是本次更新中非常关键的一项改进，尤其适合做知识库、FAQ 检索、站内搜索、类型联想等场景。

1）之前的问题：prefix_match 名义存在，实际上无效

在旧版本里，PgVector(prefix_match=True) 表面上看支持前缀匹配，但实际上这是一个静默无效的参数。

原因在于：

• • 它先拼接了 *
• • 然后走的是 websearch_to_tsquery
• • 而 websearch_to_tsquery 会忽略通配符

所以最终结果就是：你以为开了 prefix_match，实际上并没有真正做前缀搜索。

2）这次修复后的行为

现在它会正确地路由到：

• • to_tsquery('tok:*')

并且做了正确的 tokenization。

这意味着像下面这样的部分查询：

• • ani

现在能够在 FTS 中匹配到：

• • animal

这和文档中的预期表现一致了。

3）适用场景

这项修复非常适合以下应用：

• • 帮助中心自动补全
• • FAQ 联想搜索
• • 商品名/标签名前缀搜索
• • 知识库模糊前缀检索
• • 内容标题检索

官方还配套提供了新的 cookbook 示例，演示帮助中心 typeahead 的使用方式。对于依赖 PgVector 做检索增强的项目来说，这个修复非常实用。

四、PgVector 另一个修复：空 tsquery fallback 更稳了

除了 prefix_match，这次还修了另一个和 PgVector 相关的边界问题。

1）旧版本的问题

原来在 hybrid_search 的 fallback 逻辑里，会使用：

• • to_tsquery(language, '')

作为空查询兜底。

这个写法的问题在于，它依赖解析器对空输入的容忍程度。 换句话说，不同环境下可能会表现不一致，稳定性不够理想。

2）本次优化后的做法

现在改成了：

• • 直接使用字面量 ''::tsquery

这种方式更明确，也更稳健，不再依赖解析器如何处理空字符串。

3）实际意义

对于检索系统来说，空查询兜底是非常常见的边界条件。 这项修复提升的是：

• • 一致性
• • 鲁棒性
• • 跨环境稳定性

虽然这类修复不如新特性那么“显眼”，但在生产环境里往往更重要。

五、Claude 系列模型：temperature/top_p/top_k=0 终于不再被吞掉

这是本次更新中对模型调用影响很大的修复之一，涉及：

• • Anthropic Claude
• • AWS Claude
• • VertexAI Claude

1）旧版本的隐患

之前这些 Claude 变体会因为使用了“裸 truthiness 检查”，导致当参数值为 0.0 时被误判为 False，于是直接被丢弃。

这就带来一个非常严重的问题：

• • 开发者明明显式设置了 temperature=0
• • 结果请求发出去时，这个参数根本没真正生效
• • API 最终回落到默认值，大约是 1.0

也就是说，原本想要确定性输出，最后却变成了随机性输出。

2）本次修复方式

现在代码统一改成了：

• • is not None

这样一来，只要你显式传了 0，它就会被正确保留并传递。

3）这为什么重要

对于大模型应用来说，temperature=0 常用于：

• • 需要稳定复现结果
• • 需要严格 JSON 输出
• • 需要确定性工具调用
• • 需要降低随机性

如果这个参数被静默吞掉，实际影响会非常大。 因此，这次修复可以说是修正了一个非常隐蔽但非常关键的问题。

同样地，top_p=0、top_k=0 也会按照预期生效，不再被误判为“没传值”。

六、Calendar 和 Gmail context providers：指令层更清晰

本次更新还对 Calendar 和 Gmail context providers 的默认指令进行了整理。

1）之前的问题

原先的默认读写指令非常长：

• • DEFAULT_READ_INSTRUCTIONS
• • DEFAULT_WRITE_INSTRUCTIONS

长度达到 157 行。

但其中有不少内容，其实已经由 toolkit 侧的指令提供了。 这就导致：

• • 指令层重复
• • 角色边界不清
• • 维护成本偏高

2）本次调整后的变化

现在这些默认指令被大幅压缩到了 27 行。

整理后的原则是：

• • Provider 负责角色与安全
• • Toolkit 负责技术参考

也就是说，职责划分更加清晰了。

3）实际价值

这种调整看起来偏“内部治理”，但实际上很重要。 因为大模型应用里，提示词层的混乱往往会导致：

• • 指令冲突
• • 重复提示
• • 行为不稳定
• • 文档和实际逻辑不一致

这次清理后，Calendar 和 Gmail 的 context provider 在结构上会更加简洁，也更容易维护。

七、decision_log 修复：告别 datetime.utcnow() 的弃用警告

Python 3.12 对 datetime.utcnow() 相关用法提出了弃用提示。 本次更新中，decision_log 模块已经改成：

• • datetime.now(timezone.utc)

1）为什么要改

因为 datetime.utcnow() 已经不再是推荐写法。 继续使用的话，在 Python 3.12 环境下会出现弃用警告。

2）这次改动的意义

虽然这不是功能性大改，但它能帮助项目：

• • 更好兼容 Python 3.12
• • 消除弃用警告
• • 提升代码现代化程度

这是一次典型的“清理技术债”式修复。

八、Chonkie 升级到 >=1.6.7

本次版本将 Chonkie 升级到了 >=1.6.7。

1）升级原因

这是为了获取上游的 语言自动检测修复。

2）这意味着什么

对于文本处理、分块、语言识别相关流程来说，语言自动检测的准确性非常关键。 升级后，Agno 可以直接享受到上游修复带来的收益，并且移除了之前为相关测试准备的临时 workaround。

3）总结

这是一次比较标准但必要的依赖升级，目标是：

• • 解决语言自动检测问题
• • 减少临时测试补丁
• • 让依赖链更干净

九、Bug 修复：GeminiInteractions 的 server-side tool calls 不再误入 agent 路径

这是本次另一个非常关键的修复点，涉及 GeminiInteractions 在 agent 模式下的行为。

1）旧问题是什么

在 agent 路径下，比如：

• • Antigravity
• • Deep Research

FunctionCallSteps 描述的是工具在 server-managed sandbox 中运行，而不是本地 agent 自己发起的 tool call。

但此前系统会把这些内容错误地暴露为本地的 tool_calls，于是会导致：

• • Function <name> not found
• • 随后的 400 invalid_request 错误

也就是说，系统把服务端执行的工具调用，误当成了客户端本地工具调用。

2）修复方式

现在已经对这个分支进行了门控：

• • 只有在 self.agent is None 时才会处理 FunctionCallStep 分支

并且 streaming 和 non-streaming 两种模式都做了同样的修复。

3）修复后的效果

这会避免：

• • 错误暴露 tool_calls
• • 工具名找不到
• • 请求被错误判定为无效

对于使用 GeminiInteractions 的 agent 场景来说，这是一次非常重要的稳定性修复。 模型路径上、且带有用户声明工具的情况则保持不变。

十、变更清单整理：本次 v2.6.9 都改了什么

下面把官方变更内容按照更易读的方式梳理一遍，方便你快速过目。

新特性

• • 审批记录在 post-hooks 中可读取完整 resolved approval record
• • 审批解析信息通过 metadata 统一暴露，适用于不同输出类型

优化项

• • PgVector 的 prefix_match=True 终于真正执行前缀匹配
• • PgVector 的空 tsquery fallback 更稳健
• • Claude 系列模型的 temperature/top_p/top_k=0 现在会正确生效
• • Calendar 和 Gmail context provider 的默认指令大幅精简
• • decision_log 从 datetime.utcnow() 改为 datetime.now(timezone.utc)
• • Chonkie 升级到 >=1.6.7

Bug 修复

• • GeminiInteractions agent 路径修复 server-side tool calls 错误暴露问题
• • Claude 系列模型 temperature=0 之前被静默丢弃的问题已修复

其他变更

• • README 中增加 UTM 参数
• • 发布版本相关内容更新
• • 多个 cookbook 示例同步调整与新增

十一、从开发者视角看，这次升级最值得关注的点

如果你问这次 v2.6.9 哪些地方最值得立刻关注，我会优先看下面这几个：

1）如果你有审批流

你会很需要 run_response.metadata["approval"]，因为它让后 hooks、审计、观测系统能拿到完整审批记录。

2）如果你做搜索 / 知识库

PgVector 的 prefix_match=True 修复非常重要。 以前“看起来支持，实际上没生效”的问题，现在终于解决了。

3）如果你依赖 Claude

务必注意 temperature=0、top_p=0、top_k=0 这类参数现在才真正可控。 这对输出稳定性影响极大。

4）如果你用 GeminiInteractions

一定要检查你是否处于 agent 路径。 这次修复会直接影响工具调用是否被错误暴露。

5）如果你在 Python 3.12 上运行

decision_log 的弃用问题已经被处理，可以减少警告。

十二、总结：v2.6.9 是一次“修细节，但影响很大”的版本

代码地址：github.com/agno-agi/agno

Agno v2.6.9 表面上是一个常规小版本，实际上修复和优化的内容都非常贴近真实使用场景。

这次更新的关键词可以概括为：

• • 审批可观测性增强
• • PgVector 前缀搜索修复
• • Claude 0 参数生效
• • Gemini agent 工具调用修复
• • 指令层清理
• • Python 3.12 兼容优化
• • 依赖升级带来的语言识别改善