2026年9月26日，agno v3.0.11 正式发布。本次版本围绕知识库检索、重排序策略、页面数据源迁移、MCP 工具、模型提供商、取消状态、工作流 WebSocket、结构化输出解析以及多类文件读取工具进行了集中升级。
如果说此前的版本更关注 Agent、模型、工具和工作流能力的基础整合，那么 v3.0.11 的重点则非常清晰：让知识检索更灵活，让结果更可控，让工具调用更可靠，让服务端接口更适合生产环境接入。
本次更新中，知识库能力是最大的亮点之一。新的知识级检索流水线、MMR 重排序器、时效性重排序器、页面源迁移 API、类型化页面工具结果等功能，直接提升了 RAG 场景下的检索质量、数据维护能力和结果可用性。
与此同时，MCP、AG-UI、WebSocket 工作流、OpenAI Responses、DeepSeek 推理模型识别、CSV 与 JSON 读取、UTF-8 文件处理等模块也获得了大量修复和改进。下面将完整拆解 agno v3.0.11 的全部更新内容。
一、知识检索迎来核心升级：Knowledge.search() 新增知识级检索流水线
在 v3.0.11 中，Knowledge.search()现在会运行一个知识级别的检索流水线。
这一变化的核心价值在于：检索流程可以先扩大候选结果池，再交给重排序器重新排序。这样一来，重排序器不再需要分别针对每一种向量数据库单独实现。
对于知识库检索来说，候选集大小往往会显著影响最终答案质量。如果初始召回结果过少，即使后续重排序能力很强，也无法从未被召回的内容中发现更合适的片段。新的知识级检索流水线允许先扩大候选范围，再通过 reranker 对结果进行重新排列。
这项升级带来了两个重要变化：
• 重排序能力从向量数据库层上移到 Knowledge 层。
• 向量数据库不再需要分别实现自己的 reranker 逻辑。
• 同一套知识库级重排序策略可以面向不同向量数据库生效。
• 异步场景也能够得到支持。
这也与本版本中的弃用项直接相关：向量数据库上的reranker参数已被弃用，推荐将 reranker 配置在Knowledge上。
也就是说，未来更推荐的方式是让Knowledge统一管理重排序流程，而不是将重排序逻辑绑定在某个具体向量数据库实现中。这样的设计使检索能力更加统一，也让不同向量数据库之间的切换和扩展更顺畅。
二、MMR 重排序器上线：解决近重复内容挤占结果集的问题
v3.0.11 新增了MMRReranker，即最大边际相关性重排序器。
MMR 的核心目标是平衡两个维度：
• 结果与查询的相关性。
• 结果之间的多样性。
在传统向量检索中，一个常见问题是：如果文档中存在大量语义相近、内容近似甚至几乎重复的分块，这些片段可能会同时出现在 Top 结果中。虽然它们都与问题高度相关，但对于最终回答而言，重复内容会挤占有限的上下文空间。
例如，一个知识库中同一份文档的多个相邻段落都在描述同一个概念，普通检索可能返回多个高度相似的片段。模型拿到这些近重复内容后，并不会因此得到更多真正有价值的信息，反而可能遗漏其他同样相关但角度不同的内容。
MMRReranker的作用，就是在保留相关性的前提下，让检索结果具有更好的覆盖度和多样性。
它不会让近重复的内容持续占据结果集，而是尝试在相关候选中选择更具差异化的内容。这样可以减少重复 chunk 对检索结果的干扰，使最终送入模型上下文的知识更加丰富。
需要注意的是，MMR 重排序器是基于新的知识级检索流水线实现的。这意味着它并不依赖于某一个特定向量数据库的专属能力，而是作为知识层检索策略发挥作用。
对于文档重复较多、分块重叠较明显、同类内容存在多个版本或多个表达方式的知识库场景，MMR 重排序器尤其值得关注。
三、RecencyReranker：让新版本内容优先于过时内容
除了 MMR 重排序器，v3.0.11 还新增了RecencyReranker，即时效性重排序器。
这一重排序器会将搜索分数与时间戳的指数衰减结合起来，使更新较新的内容排在已经被替代的旧版本内容之前。
在很多知识库场景中，纯语义相似度并不足以保证结果的正确性。特别是在以下类型的数据中，发布时间、更新时间和版本时间往往极其重要：
• 产品文档的不同版本。
• API 文档的更新记录。
• 技术规范的修订内容。
• 经常更新的项目说明。
• 存在旧方案和新方案并行的内部文档。
• 已经被新版本替代的操作指南。
如果只依赖向量相似度，旧内容可能因为语义上更接近用户问题而排在前面。但在实际使用中，用户更需要的是最新且仍然有效的内容。
RecencyReranker正是为这一需求而设计。它会在原始搜索分数的基础上，引入基于时间戳的指数衰减因素，让越新的内容获得更有利的排序表现。
该功能同样构建在知识级检索流水线之上，并且重点面向 pgvector。
通过这一能力，agno 的知识库检索不再只关注“内容像不像”，还可以在一定程度上关注“内容是不是足够新”。
四、页面源迁移能力：支持将已索引文档源迁移到新主机名
知识库中的文档来源地址并不是一成不变的。
在实际维护中，文档站点可能更换域名、调整主机名，或者发生站点迁移。如果已经完成索引的文档源地址发生变化，如何在不丢失既有索引维护能力的前提下完成迁移，是一个非常现实的问题。
v3.0.11 为此新增了页面源迁移相关能力：
•
Knowledge.inspect_page_source•
Knowledge.ainspect_page_source•
migrate_page_source•
amigrate_page_source
其中，inspect_page_source和ainspect_page_source用于检查页面源。
而migrate_page_source与amigrate_page_source则用于将已索引的文档源迁移到新的主机名。
值得注意的是，这项迁移功能采用了受保护的设计，并且默认以 dry run，也就是试运行模式执行。
这意味着迁移默认不会直接进行实际修改，而是先以演练方式检查和展示迁移情况。对于已经建立索引的知识库来说，这种默认行为能够降低误操作带来的风险。
页面源迁移能力的加入，提升了知识库的长期可维护性。对于需要长期运营文档索引、文档站点可能发生迁移的场景，这一能力能够减少后续维护成本。
五、类型化页面工具结果：命令执行与检索结果拥有更明确的元数据
v3.0.11 新增了类型化页面工具结果，涉及两个关键能力：
•
PageCommandResult•
PageFileSystem.run_command_result•
PageFileSystem.arun_command_result
其中，PageCommandResult用于提供具备明确结构的页面命令结果。
PageFileSystem.run_command_result和异步版本PageFileSystem.arun_command_result则会返回带有明确错误信息、完整性信息和截断信息的结果。
本次增加的元数据包括：
• error
• completeness
• truncation
这意味着工具调用结果不再只是简单的文本或非结构化返回，而是能够明确表达命令是否出错、结果是否完整、输出是否被截断。
对于工具调用链路来说，这类信息非常重要。因为调用方需要知道：当前结果是否可靠、是否完整、是否需要进一步处理，或者是否应该调整后续操作。
与此同时，Knowledge.get_tools(page_results=True)也得到了增强。
启用page_results=True后，返回的是经过排序的SearchResult对象，而不仅仅是普通的简单结果。这项能力同样会体现在 MCP 的结构化输出中。
也就是说，知识库工具在 MCP 场景下可以提供更加清晰、类型化、带排序信息的搜索结果。对于需要在客户端、Agent、MCP 工具调用链中处理检索结果的场景，这会带来更稳定的数据交互方式。
六、新增 Y-API：支持 OpenAI 兼容模型提供商
v3.0.11 新增了 YAPI，作为一个 OpenAI 兼容的模型提供商。
OpenAI 兼容接口在模型集成场景中具有很高的实用价值。对于已经采用 OpenAI 风格接口的模型服务，统一的兼容层可以降低接入成本。
本次增加 YAPI 后，agno 的模型提供商生态得到进一步扩展。对于需要通过 OpenAI 兼容方式接入模型服务的用户而言，这提供了新的可选项。
七、取消状态更可读：新增 cancellation_stage 机器可读字段
在任务执行、团队执行和工作流执行过程中，取消操作是一个重要状态。
此前，客户端如果想判断一个任务取消发生在什么阶段，可能需要根据取消消息文本进行匹配。这种方式不够稳定，也不适合程序化处理。
v3.0.11 为以下输出对象和运行 API schema 增加了机器可读的cancellation_stage字段：
•
RunOutput•
TeamRunOutput•
WorkflowRunOutput• run API schemas
该字段可以返回以下状态：
•
PENDING•
EXECUTING•
INTERRUPTED•
unknown
这项更新意味着客户端不再需要根据取消消息的文本内容进行判断，而可以直接读取标准化的取消阶段字段。
不同状态表达的含义如下：
•
PENDING：取消发生在待执行阶段。•
EXECUTING：取消发生在执行阶段。•
INTERRUPTED：执行过程被中断。•
unknown：取消阶段未知。
对于前端界面、任务调度系统、运行记录系统和自动化处理逻辑来说，机器可读状态远比匹配自然语言消息更可靠。
八、OpenAIResponses 优化：store=True 不再强制自动串联 previous_response_id
本版本对OpenAIResponses增加了use_previous_response_id。
这一参数解决了一个行为上的耦合问题：此前，当设置store=True时，会强制自动进行previous_response_id链接。
v3.0.11 之后，通过use_previous_response_id，存储响应与是否自动串联上一个响应 ID 可以被区分开来。
也就是说，store=True不再意味着一定会自动使用前一次响应的previous_response_id。
这一调整让响应存储和响应链路控制更加独立。对于需要保留响应记录、但不希望自动延续 previous response 关系的使用方式来说，这项改动提供了更明确的控制能力。
九、MCP 工具 Schema 改进：参数描述更完整，分页参数边界更严格
MCP 工具在 v3.0.11 中获得了多项增强。
首先，AgentOS MCP 工具中的每一个参数，现在都会在inputSchema中携带描述信息。
这意味着 MCP 客户端在读取工具定义时，可以获得更加完整的参数语义说明。相比只有参数名和类型的 schema，带有 description 的输入 schema 更容易被工具调用方理解和使用。
其次，get_sessions的limit和page参数新增了最小值限制，最小值为 1。
也就是说：
•
limit不允许小于 1。•
page不允许小于 1。
这一改动使分页参数的边界更加明确，避免不合理的分页输入带来不一致行为。
此外，MCP 工具发现也修复了一个重要问题。
当通过原始ClientSession进行工具发现时，此前可能只会收集tools/list的第一页结果。v3.0.11 修复后，会收集tools/list的全部分页结果。
对于工具数量较多的 MCP 服务端而言，这项修复能够确保客户端发现全部可用工具，而不是只拿到第一页。
十、MCP Server Card 修复：裸 mcp=True 与 MCPConfig 行为保持一致
v3.0.11 修复了 MCP Server Card 中mcp=True的路由行为。
此前，直接使用裸配置mcp=True时，可能没有安装与MCPConfig相同的路由层。
修复后，裸mcp=True会与MCPConfig使用相同的路由层，因此以下能力会同时生效：
• Host 检查。
• 挂载前缀应用。
这意味着无论采用裸mcp=True还是MCPConfig，相关路由和安全行为将更加一致。
此外，本版本还移除了未实现的 ETag 和 If-None-Match CORS headers。
这一调整避免暴露未实际实现的相关 CORS 头部能力，使 MCP Server Card 的行为更加准确。
十一、AG-UI 支持 ag-ui-protocol 1.0
v3.0.11 增加了对 ag-ui-protocol 1.0 的支持。
同时，在 resume 场景下，也支持列表形式的工具结果内容。
这意味着当工具结果内容采用 list-valued，也就是列表值形式时，AG-UI 的恢复流程能够正确处理。
对于使用 AG-UI 协议进行交互和恢复执行的场景，这项更新提升了协议兼容性与工具结果处理能力。
十二、WebSocket 工作流修复：版本固定、会话归属与会话创建行为对齐 HTTP
工作流通过 WebSocket 提交时，本版本修复了多个与 HTTP 准入规则不一致的问题。
第一，带版本固定的提交不会再在缺少对应版本固定信息的情况下被排队。
第二，会话所有权现在会在写入路径上进行检查。
第三，如果缺少 session id，则会像 HTTP 一样创建一个新的 session。
这些调整让 WebSocket 工作流提交行为与 HTTP 的准入规则保持一致。
对于同时支持 HTTP 和 WebSocket 调用的工作流系统而言，协议间行为一致性非常关键。否则，同一个工作流请求在不同传输方式下可能出现不同的会话处理、版本处理或排队行为。
v3.0.11 通过修复这些问题，使工作流 WebSocket 提交更加符合 HTTP 侧既有规则。
十三、DeepSeek 推理模型识别增强：OpenAILike 提供商也能正确识别 thinking 模式
本版本改进了 reasoning detection，也就是推理模型识别能力。
现在，当 DeepSeek 的 thinking-mode 模型 ID 通过任意 OpenAILike provider 提供服务时，agno 也能够将其识别为推理模型。
此前，模型是否被识别为 reasoning model 可能依赖于特定提供商路径。此次修复后，OpenAILike 方式下的 DeepSeek thinking 模式模型 ID 也能够得到正确识别。
对于通过兼容接口部署或接入 DeepSeek 推理模型的场景，这项改进能够提升模型能力识别的一致性。
十四、工具调用修复：同步 Hook 在异步执行链路中可正确运行
v3.0.11 修复了一个工具 Hook 相关问题。
问题发生在异步执行路径中：当同步 Hook 返回function_call(**arguments)时，调用链可能会将未 await 的 coroutine 当成工具结果，从而导致工具函数体根本没有执行。
修复后，同步 Hook 返回的这类调用可以在异步执行链中正常处理，工具主体能够真正运行。
这是一个非常关键的可靠性修复。因为从表面看，调用链可能已经获得了一个结果对象，但实际上工具本体并没有执行。修复之后，异步工具执行路径中的 Hook continuation 行为更加正确。
十五、工具文档与流式参数文档修正
本版本还对工具和模型类的文档字符串进行了修复。
主要包括：
• 移除了工具 docstrings 中多余的 phantom Args 条目。
• 修正了两个模型类中流式相关 docstring 参数名称。
这些改动虽然不直接改变核心运行逻辑，但对于开发者阅读 API 文档、理解工具参数和使用流式能力具有实际价值。
当文档字符串中存在不存在的 Args 条目或参数名错误时，会给调用者带来误导。此次修正有助于提升开发体验。
十六、JSONReader 修复：保留标量 JSON 根节点
v3.0.11 修复了JSONReader对标量 JSON 根节点的处理。
此前，JSON 文档的根节点如果是标量值，可能无法被正确保留。修复后，JSONReader能够保留 scalar JSON roots。
JSON 根节点不一定只能是对象或数组，也可能是字符串、数字、布尔值或空值。此次修复确保这些标量根节点不会在读取过程中丢失。
十七、CSVReader 改进：支持文本流，并提前校验 page_size
CSV 读取相关能力在本版本中进行了多项完善。
首先，CSVReader现在可以读取文本流，而不仅限于字节流。
这意味着 CSV 输入不再只能以 byte stream 形式处理，text stream 同样可以被正常读取。
其次，CSVReader和FieldLabeledCSVReader都增加了page_size的前置校验。
此前，如果page_size设置为 0 或负数，可能会静默返回空文档，而不会抛出明确错误。
修复后，如果page_size为 0 或负数，将在读取前直接抛出ValueError。
这一变化让参数错误更容易被发现，也避免“没有读到任何文档”被误认为是正常结果。
相关改进包括：
•
CSVReader在读取前验证 page_size。•
FieldLabeledCSVReader在读取前验证 page_size。• page_size 为零或负数时抛出
ValueError。•
CSVReader支持读取文本流。
十八、结构化输出解析修复：忽略文本中不匹配的右花括号
模型输出中经常会混合自然语言和 JSON 结构化内容。
在提取 JSON 对象时，如果普通文本中出现不匹配的右花括号，解析流程可能受到干扰。
v3.0.11 修复后，在从模型输出中提取 JSON 对象时，会忽略自然语言内容中不匹配的 closing braces，也就是不匹配的右花括号。
这项修复提高了结构化输出解析在真实模型文本中的鲁棒性。
当模型在解释文字、代码片段或其他普通文本中包含额外右花括号时，系统不会因此错误地破坏 JSON 对象提取流程。
十九、GoogleDriveTools 改进：PPTX 可读取组合形状中的文本与换行
GoogleDriveTools 在读取.pptx文件文本时得到了增强。
本版本支持：
• 读取 grouped shapes，即组合形状中的文本。
• 在提取文本时保留换行。
演示文稿中的文本并不一定只存在于普通单独形状中。很多 PPTX 文件会使用组合形状组织图形与文字，如果无法读取组合形状内部文本，就可能造成内容遗漏。
此外，换行信息对于保留幻灯片原始文本结构也很重要。
修复后，GoogleDriveTools 对 PPTX 文本内容的提取更加完整。
二十、UTF-8 文件处理统一：YAML、AntigravityTools 与 AirflowTools 不再受本地语言环境影响
v3.0.11 对文件编码处理进行了统一修复。
以下能力现在会始终使用 UTF-8 读写文件，而不再依赖系统 locale：
•
read_yaml_file•
write_yaml_file•
AntigravityTools•
AirflowTools
在不同机器、不同部署环境、不同系统语言设置下，默认 locale 可能不同。如果读写文件依赖本地环境编码，可能导致中文、特殊字符或跨平台文件内容出现乱码、读取失败或写入不一致等问题。
此次改动明确使用 UTF-8，可以减少由 locale 引起的编码不确定性。
二十一、DuckDbTools 修复：转义 CSV 分隔符
v3.0.11 修复了DuckDbTools中 CSV 分隔符的转义问题。
CSV 文件的分隔符需要被正确处理，特别是在构造或解析相关操作中，未正确转义可能导致格式解析异常。
本次更新通过对 CSV delimiters 进行转义，提升了 DuckDbTools 处理 CSV 数据时的可靠性。
二十二、TavilyTools 改进：转发 extract 选项
本版本修复了 TavilyTools 中 extract options 没有被正确转发的问题。
修复后，调用相关功能时，extract 选项可以被正常传递。
这一改动确保调用方提供的 extract 配置不会在工具调用链中丢失。
二十三、知识源、文档与示例更新
除了功能和修复之外，v3.0.11 还更新了文档、知识源与示例内容。
本版本包括以下改动：
• 替换了知识源和文档引用中的失效链接。
• 修复了 V3 迁移指南中的重复词。
• 新增了 Inspeximus memory 集成示例。
• 新增了 Confident AI observability 示例。
• 从知识 URL 测试中移除了 IMDB CSV，以避免 CI 超时。
其中，失效链接替换可以提升文档与 Cookbook 内容的可用性；迁移指南中的文字修复可以避免阅读歧义；新增的 memory 和 observability 示例则扩展了相关集成参考。
而移除知识 URL 测试中的 IMDB CSV，则是为了避免持续集成流程出现超时问题。
二十四、弃用说明：向量数据库级 reranker 正式弃用
本版本唯一明确提到的弃用项，是向量数据库级别的 reranker 参数。
也就是说，向量数据库上的reranker参数被标记为弃用，推荐迁移到Knowledge级别的 reranker 配置。
新的方向是：
• 重排序器配置在
Knowledge上。• 重排序逻辑可以应用于所有向量数据库。
• 支持异步使用方式。
• 依托新的知识级检索流水线执行。
对于已经在向量数据库层配置 reranker 的项目，需要关注这一弃用变化，并逐步将相关配置迁移到 Knowledge 层。
这一变化并不是简单的参数位置调整，而是与 v3.0.11 新增的知识级检索流水线、MMR 重排序器和时效性重排序器共同构成了新的知识库检索架构方向。
二十五、agno v3.0.11 更新总结
代码地址：github.com/agno-agi/agno
agno v3.0.11 是一次覆盖面非常广的版本更新。
从知识库能力来看，本次版本新增了知识级检索流水线，并引入 MMRReranker 与 RecencyReranker，分别解决检索结果重复和内容时效性问题。页面源检查与迁移 API，则进一步补齐了已索引文档源发生主机名变化时的维护能力。类型化页面命令结果和类型化搜索结果，也让工具输出更加适合自动化链路和 MCP 结构化交互。
从平台能力来看，YAPI 的加入扩展了 OpenAI 兼容模型提供商支持；cancellation_stage让取消状态能够以机器可读的方式被客户端消费；use_previous_response_id让 OpenAIResponses 的响应存储与响应链路控制更加独立。
从协议和服务端能力来看，MCP 工具 schema 的参数描述更完整，分页参数边界更严格，工具发现支持完整分页结果；裸mcp=True与MCPConfig的路由行为实现一致；AG-UI 支持 ag-ui-protocol 1.0；WebSocket 工作流提交规则与 HTTP 进一步对齐。
从稳定性来看，同步 Hook 在异步链路中的执行问题得到修复，JSON 结构化输出提取更加稳健，CSV、JSON、YAML、PPTX、DuckDB、Tavily 等工具与读取器也获得了针对性的增强和修复。
整体来看，agno v3.0.11 并不只是增加几个独立功能，而是在知识检索质量、工具调用结果结构化、协议兼容性、文件处理稳定性和运行状态可观测性等方向进行了系统完善。
对于正在构建知识库问答、RAG 应用、MCP 工具服务、Agent 工作流和多模型接入系统的开发者而言，v3.0.11 中的知识级检索流水线、MMR 重排序、时效性重排序、页面源迁移、MCP 改进以及取消阶段状态，都是值得重点关注的更新。
我们相信人工智能为普通人提供了一种“增强工具”，并致力于分享全方位的AI知识。在这里，您可以找到最新的AI科普文章、工具评测、提升效率的秘籍以及行业洞察。 欢迎关注“福大大架构师每日一题”，发消息可获得面试资料，让AI助力您的未来发展。
热门跟贴