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_sourceKnowledge.ainspect_page_sourcemigrate_page_sourceamigrate_page_source其中inspect_page_source和ainspect_page_source用于检查页面源。而migrate_page_source与amigrate_page_source则用于将已索引的文档源迁移到新的主机名。值得注意的是这项迁移功能采用了受保护的设计并且默认以 dry run也就是试运行模式执行。这意味着迁移默认不会直接进行实际修改而是先以演练方式检查和展示迁移情况。对于已经建立索引的知识库来说这种默认行为能够降低误操作带来的风险。页面源迁移能力的加入提升了知识库的长期可维护性。对于需要长期运营文档索引、文档站点可能发生迁移的场景这一能力能够减少后续维护成本。五、类型化页面工具结果命令执行与检索结果拥有更明确的元数据v3.0.11 新增了类型化页面工具结果涉及两个关键能力PageCommandResultPageFileSystem.run_command_resultPageFileSystem.arun_command_result其中PageCommandResult用于提供具备明确结构的页面命令结果。PageFileSystem.run_command_result和异步版本PageFileSystem.arun_command_result则会返回带有明确错误信息、完整性信息和截断信息的结果。本次增加的元数据包括errorcompletenesstruncation这意味着工具调用结果不再只是简单的文本或非结构化返回而是能够明确表达命令是否出错、结果是否完整、输出是否被截断。对于工具调用链路来说这类信息非常重要。因为调用方需要知道当前结果是否可靠、是否完整、是否需要进一步处理或者是否应该调整后续操作。与此同时Knowledge.get_tools(page_resultsTrue)也得到了增强。启用page_resultsTrue后返回的是经过排序的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字段RunOutputTeamRunOutputWorkflowRunOutputrun API schemas该字段可以返回以下状态PENDINGEXECUTINGINTERRUPTEDunknown这项更新意味着客户端不再需要根据取消消息的文本内容进行判断而可以直接读取标准化的取消阶段字段。不同状态表达的含义如下PENDING取消发生在待执行阶段。EXECUTING取消发生在执行阶段。INTERRUPTED执行过程被中断。unknown取消阶段未知。对于前端界面、任务调度系统、运行记录系统和自动化处理逻辑来说机器可读状态远比匹配自然语言消息更可靠。八、OpenAIResponses 优化storeTrue 不再强制自动串联 previous_response_id本版本对OpenAIResponses增加了use_previous_response_id。这一参数解决了一个行为上的耦合问题此前当设置storeTrue时会强制自动进行previous_response_id链接。v3.0.11 之后通过use_previous_response_id存储响应与是否自动串联上一个响应 ID 可以被区分开来。也就是说storeTrue不再意味着一定会自动使用前一次响应的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 修复裸 mcpTrue 与 MCPConfig 行为保持一致v3.0.11 修复了 MCP Server Card 中mcpTrue的路由行为。此前直接使用裸配置mcpTrue时可能没有安装与MCPConfig相同的路由层。修复后裸mcpTrue会与MCPConfig使用相同的路由层因此以下能力会同时生效Host 检查。挂载前缀应用。这意味着无论采用裸mcpTrue还是MCPConfig相关路由和安全行为将更加一致。此外本版本还移除了未实现的 ETag 和 If-None-Match CORS headers。这一调整避免暴露未实际实现的相关 CORS 头部能力使 MCP Server Card 的行为更加准确。十一、AG-UI 支持 ag-ui-protocol 1.0v3.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_sizeCSV 读取相关能力在本版本中进行了多项完善。首先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 读写文件而不再依赖系统 localeread_yaml_filewrite_yaml_fileAntigravityToolsAirflowTools在不同机器、不同部署环境、不同系统语言设置下默认 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/agnoagno v3.0.11 是一次覆盖面非常广的版本更新。从知识库能力来看本次版本新增了知识级检索流水线并引入 MMRReranker 与 RecencyReranker分别解决检索结果重复和内容时效性问题。页面源检查与迁移 API则进一步补齐了已索引文档源发生主机名变化时的维护能力。类型化页面命令结果和类型化搜索结果也让工具输出更加适合自动化链路和 MCP 结构化交互。从平台能力来看YAPI 的加入扩展了 OpenAI 兼容模型提供商支持cancellation_stage让取消状态能够以机器可读的方式被客户端消费use_previous_response_id让 OpenAIResponses 的响应存储与响应链路控制更加独立。从协议和服务端能力来看MCP 工具 schema 的参数描述更完整分页参数边界更严格工具发现支持完整分页结果裸mcpTrue与MCPConfig的路由行为实现一致AG-UI 支持 ag-ui-protocol 1.0WebSocket 工作流提交规则与 HTTP 进一步对齐。从稳定性来看同步 Hook 在异步链路中的执行问题得到修复JSON 结构化输出提取更加稳健CSV、JSON、YAML、PPTX、DuckDB、Tavily 等工具与读取器也获得了针对性的增强和修复。整体来看agno v3.0.11 并不只是增加几个独立功能而是在知识检索质量、工具调用结果结构化、协议兼容性、文件处理稳定性和运行状态可观测性等方向进行了系统完善。对于正在构建知识库问答、RAG 应用、MCP 工具服务、Agent 工作流和多模型接入系统的开发者而言v3.0.11 中的知识级检索流水线、MMR 重排序、时效性重排序、页面源迁移、MCP 改进以及取消阶段状态都是值得重点关注的更新。