2026年5月22日Agno 发布了v2.6.9。这一次更新虽然版本号不大但内容非常扎实属于典型的“看起来是小版本实际上修了不少关键问题”的升级。从审批流后 Hooks 的可观测性增强到PgVector 前缀匹配真正可用再到Claude 系列模型 temperature/top_p/top_k0 终于不再被静默丢弃以及GeminiInteractions 在 agent 路径上的工具调用修复都直接影响到开发者在真实项目中的稳定性和可控性。如果你正在使用 Agno 构建 Agent、Workflow、知识库检索、审批流、或者接入 Claude / Gemini / PgVector那么这次版本更新值得认真看完。下面我会按照新特性、优化、Bug 修复、变更清单的顺序结合本次官方发布内容做一篇适合 CSDN 发布的技术文章整理帮助你快速理解 v2.6.9 到底升级了什么、修了什么、为什么重要。一、v2.6.9 发布概览本次版本发布的核心关键词可以概括为审批信息更完整PgVector 前缀搜索真正可用Claude 的 0 参数不再失效Calendar / Gmail 指令层更清晰决策日志兼容 Python 3.12Gemini agent 路径工具调用错误修复Chonkie 升级带来语言自动识别修复这些内容并不是简单的“功能堆砌”而是围绕几个实际开发痛点进行修正可观测性更强后 hooks 和 observability integration 现在可以拿到完整的审批解析记录。检索能力更准PgVector 的 prefix_match 不再是无效参数。模型参数更可靠Claude 相关参数为 0 时终于能按预期传递。Agent 执行更稳定GeminiInteractions 不再把 server-side tool calls 错误暴露为本地 tool_calls。配置和兼容性更干净一些废弃写法和冗余文案被清理减少维护成本。二、新特性审批记录在 Post-Hooks 中可完整读取本次最值得关注的新特性之一是审批记录在 post-hooks 和 observability integrations 中可完整读取。1更新前的问题在之前的版本里运行结果中的审批信息暴露得比较有限。开发者在后置 hook、观测集成中通常只能看到statusresolution_data这意味着很多关键审批上下文并没有直接暴露出来例如resolved_byresolved_at对于需要做审计、记录审批链路、或者在 observability 系统中还原完整审批状态的场景来说这显然不够。2本次更新的变化现在完整的 resolved approval record 可以通过run_response.metadata[approval]来读取。这条信息的意义非常大因为它被放在 metadata 中所以具备统一性对RunOutput生效对TeamRunOutput生效未来也能自然适配WorkflowRunOutput也就是说Agno 不再把审批信息限制在某个特定输出对象的某个局部字段而是统一放进 metadata 里方便不同运行类型以一致方式读取。3这对实际开发意味着什么这项改进主要带来三类收益更完整的审计信息更方便的后处理逻辑更统一的数据结构设计如果你在做审批流、风控流程、运维审批、AI 辅助决策记录那么这次更新之后你可以更自然地在 post-hook 中拿到完整审批结果减少二次拼装和字段缺失带来的问题。三、PgVector 优化prefix_matchTrue 终于真正生效这是本次更新中非常关键的一项改进尤其适合做知识库、FAQ 检索、站内搜索、类型联想等场景。1之前的问题prefix_match 名义存在实际上无效在旧版本里PgVector(prefix_matchTrue)表面上看支持前缀匹配但实际上这是一个静默无效的参数。原因在于它先拼接了*然后走的是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_k0 终于不再被吞掉这是本次更新中对模型调用影响很大的修复之一涉及Anthropic ClaudeAWS ClaudeVertexAI Claude1旧版本的隐患之前这些 Claude 变体会因为使用了“裸 truthiness 检查”导致当参数值为0.0时被误判为 False于是直接被丢弃。这就带来一个非常严重的问题开发者明明显式设置了temperature0结果请求发出去时这个参数根本没真正生效API 最终回落到默认值大约是1.0也就是说原本想要确定性输出最后却变成了随机性输出。2本次修复方式现在代码统一改成了is not None这样一来只要你显式传了0它就会被正确保留并传递。3这为什么重要对于大模型应用来说temperature0常用于需要稳定复现结果需要严格 JSON 输出需要确定性工具调用需要降低随机性如果这个参数被静默吞掉实际影响会非常大。因此这次修复可以说是修正了一个非常隐蔽但非常关键的问题。同样地top_p0、top_k0也会按照预期生效不再被误判为“没传值”。六、Calendar 和 Gmail context providers指令层更清晰本次更新还对Calendar 和 Gmail context providers的默认指令进行了整理。1之前的问题原先的默认读写指令非常长DEFAULT_READ_INSTRUCTIONSDEFAULT_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 路径下比如AntigravityDeep ResearchFunctionCallSteps 描述的是工具在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_matchTrue终于真正执行前缀匹配PgVector 的空 tsquery fallback 更稳健Claude 系列模型的temperature/top_p/top_k0现在会正确生效Calendar 和 Gmail context provider 的默认指令大幅精简decision_log从datetime.utcnow()改为datetime.now(timezone.utc)Chonkie 升级到1.6.7Bug 修复GeminiInteractions agent 路径修复 server-side tool calls 错误暴露问题Claude 系列模型temperature0之前被静默丢弃的问题已修复其他变更README 中增加 UTM 参数发布版本相关内容更新多个 cookbook 示例同步调整与新增十一、从开发者视角看这次升级最值得关注的点如果你问这次 v2.6.9 哪些地方最值得立刻关注我会优先看下面这几个1如果你有审批流你会很需要run_response.metadata[approval]因为它让后 hooks、审计、观测系统能拿到完整审批记录。2如果你做搜索 / 知识库PgVector 的prefix_matchTrue修复非常重要。以前“看起来支持实际上没生效”的问题现在终于解决了。3如果你依赖 Claude务必注意temperature0、top_p0、top_k0这类参数现在才真正可控。这对输出稳定性影响极大。4如果你用 GeminiInteractions一定要检查你是否处于 agent 路径。这次修复会直接影响工具调用是否被错误暴露。5如果你在 Python 3.12 上运行decision_log的弃用问题已经被处理可以减少警告。十二、总结v2.6.9 是一次“修细节但影响很大”的版本代码地址github.com/agno-agi/agnoAgno v2.6.9 表面上是一个常规小版本实际上修复和优化的内容都非常贴近真实使用场景。这次更新的关键词可以概括为审批可观测性增强PgVector 前缀搜索修复Claude 0 参数生效Gemini agent 工具调用修复指令层清理Python 3.12 兼容优化依赖升级带来的语言识别改善