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 和 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

之前这些 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 侧的指令提供了。
这就导致：

• • 指令层重复

• • 角色边界不清

• • 维护成本偏高

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

整理后的原则是：

• •Provider 负责角色与安全

• •Toolkit 负责技术参考

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

3）实际价值

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

• • 指令冲突

• • 重复提示

• • 行为不稳定

• • 文档和实际逻辑不一致

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

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

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

• •datetime.now(timezone.utc)

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

2）这次改动的意义

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

• • 更好兼容 Python 3.12

• • 消除弃用警告

• • 提升代码现代化程度

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

八、Chonkie 升级到 >=1.6.7

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

1）升级原因

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

2）这意味着什么

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

3）总结

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

• • 解决语言自动检测问题

• • 减少临时测试补丁

• • 让依赖链更干净

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

1）旧问题是什么

在 agent 路径下，比如：

• • Antigravity

• • Deep Research

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

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

• •Function 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

• • 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 兼容优化

• •依赖升级带来的语言识别改善

我们相信人工智能为普通人提供了一种“增强工具”，并致力于分享全方位的AI知识。在这里，您可以找到最新的AI科普文章、工具评测、提升效率的秘籍以及行业洞察。 欢迎关注“福大大架构师每日一题”，发消息可获得面试资料，让AI助力您的未来发展。