2026年9月2日agno 正式发布 v3.0.5。这次更新的核心集中在知识库导入流程与 Embedding 失败处理机制上。过去一些实际未能完整完成向量化的内容可能仍会被系统标记为成功而在 v3.0.5 中这类失败将不再被掩盖。系统会明确暴露 Embedding 错误并通过新增的partial状态让开发者能够区分“完全成功”“部分成功”和“完全失败”。对于依赖知识库、向量数据库、模型提供商以及 MCP 工具接入的开发者来说v3.0.5 不只是一次功能补充也包含了多项需要重点关注的兼容性变化。尤其是已有的异常处理逻辑、内容状态判断逻辑以及重新导入内容时的行为都需要根据新版本进行调整。一、最重要的变化Embedding 失败不再被系统“掩盖”在过去的行为中知识库内容导入期间如果发生 Embedding 失败系统可能会掩盖这类错误并返回成功结果。这会带来一个非常容易被忽略的问题内容看起来已经完成导入但实际可能没有完成全部向量化。换句话说用户看到的“completed”并不一定代表所有内容都已经可以被正常检索。agno v3.0.5 针对这一问题进行了调整。现在导入流程会明确报告 Embedding 失败而不是继续返回成功状态。此前显示为已完成的部分内容在升级后可能会显示为失败或者显示为部分完成。需要特别理解的是这并不是升级后才出现了新的导入问题而是此前这些导入本身就并不完整只是系统以前将它们报告成了成功。因此当升级到 v3.0.5 后开发者可能会看到一些原本显示完成的内容变成了failed或partial。这是状态报告准确性提升所带来的直接变化。二、ContentStatus 新增 partial内容状态从三种扩展为四种v3.0.5 为内容状态增加了一个新的枚举值partial。此前API 中的ContentStatus状态包括processing completed failed升级后状态范围扩展为processing completed partial failed也就是说内容导入不再只有“处理中、完成、失败”三种结果而是多了“部分完成”这一中间状态。partial用于描述这样一种情况文件中的部分 Chunk 已经完成 Embedding另一些 Chunk 未能完成 Embedding已成功向量化的内容仍然可以被搜索到但整个文件并不完整因此不能被视为completed同时由于并非所有 Chunk 都失败也不能简单归类为failed。这种状态设计能够更准确地反映真实的导入结果。例如一个文档被拆分为多个 Chunk其中一部分 Chunk 成功写入向量数据库另一部分由于 Embedding 失败未能写入。在旧逻辑下这类内容可能被错误地标记为完成在新逻辑下则会被标记为partial。对于依赖内容状态来决定后续业务流程的系统需要注意适配新的枚举值。此前如果代码只处理了processing、completed和failed升级后应当加入对partial的判断。值得注意的是这项变更不需要进行数据库 Schema 迁移。原因是内容状态字段本身已经是varchar类型因此数据库层面无需修改字段定义。开发者需要关注的重点是 API 响应、前端展示、状态机逻辑以及业务代码中对内容状态的处理。三、EmbeddingError 成为关键异常不再以空向量表示失败v3.0.5 还改变了 Embedder 失败时的行为。此前当 Embedder 发生失败时可能会返回一个空向量。这样的行为存在明显风险调用方如果没有额外判断空向量就可能将错误当作正常结果继续处理。在新版本中Embedder 遇到失败时将抛出EmbeddingError而不是返回空向量。这意味着Embedding 失败将以明确的异常形式暴露给调用方。这种调整让错误行为更可见也让开发者能够通过标准异常处理逻辑进行捕获、记录和恢复。相比返回空向量抛出异常能够避免后续流程在错误数据基础上继续执行。对于已有代码而言需要特别检查以下场景是否依赖空向量来判断 Embedding 是否失败是否没有处理 Embedding 相关异常是否假设 Embedder 调用总能返回向量结果是否在错误发生后仍将内容标记为导入成功。升级后这些逻辑都应当适配EmbeddingError的抛出行为。四、直接调用向量数据库 search() 的行为改变除了 Embedder 的异常行为外直接调用向量数据库search()的行为也发生了变化。此前如果直接调用向量数据库的search()在某些失败情况下可能会返回一个空列表[]这种返回方式容易让调用方误以为“没有检索结果”而不是“检索过程发生了异常”。在 v3.0.5 中直接调用向量数据库的search()时如果发生相关失败将会抛出异常而不再返回空列表。这意味着空检索结果与检索失败之间的边界变得更加明确没有匹配内容时属于正常的无结果情况调用失败时应通过异常体现调用方不能再把空列表简单视为所有失败场景的统一结果。不过这项变化有一个重要例外。Knowledge.search()的行为不受影响。Knowledge.search()仍然会在相关情况下返回无结果而不会将这一变化直接暴露为异常行为。也就是说直接操作向量数据库的开发者需要关注异常处理变化而通过Knowledge.search()进行检索的使用方式保持原有的无结果返回行为。这也意味着在升级后开发者需要清楚区分自己使用的是哪一层接口直接调用 vector DB 的search()调用Knowledge.search()。两者在失败场景下的表现不再完全一致。五、AWS Bedrock Embedding 异常类型调整对于使用 AWS Bedrock 进行 Embedding 的场景v3.0.5 也调整了异常类型。此前AWS Bedrock 的 Embedding 失败可能会抛出ModelProviderError在新版本中AWS Bedrock 的 Embedding 失败将抛出EmbeddingError这一变化非常关键因为它会直接影响已有的except处理逻辑。如果现有代码中围绕 Bedrock Embedding 编写了类似以下逻辑exceptModelProviderError:...那么升级到 v3.0.5 后这段代码将不再捕获 Bedrock 的 Embedding 失败。开发者需要将异常处理改为捕获exceptEmbeddingError:...这不是单纯的异常名称变化而是异常分类逻辑的调整。由于失败发生在 Embedding 环节因此新版本将其归入EmbeddingError而不是ModelProviderError。对于已有的错误监控、重试策略、日志分类和告警规则也应当同步检查是否依赖ModelProviderError来识别 Bedrock Embedding 问题。六、内容状态接口更严格不存在或无权限内容将返回 404v3.0.5 对内容状态查询接口的行为进行了修正。接口如下GET /knowledge/content/{id}/status此前当请求的内容不存在或者该内容不属于当前访问者时接口可能会返回{status:failed}也就是说一个不存在的内容或者一个无权访问的内容会被伪装成失败状态。在 v3.0.5 中这一行为发生改变。现在如果内容不存在或者内容不属于当前访问者该接口将返回404而不再返回状态为failed的成功响应。这一变化使接口语义更加准确内容存在且导入失败才应返回failed内容不存在应返回 404内容不属于当前用户或当前访问范围也应返回 404不应再用failed混淆“内容处理失败”与“内容不存在或无权访问”。对于调用该接口的前端和后端代码需要注意 HTTP 状态码处理。此前如果调用方只读取响应体中的status字段而没有处理 404那么升级后可能需要补充对 404 的分支逻辑。尤其是在轮询内容导入状态、判断内容是否已被删除、或者判断当前用户是否具备访问权限时应当将 404 视为与failed不同的情况。七、skip_if_existsTrue 行为升级失败与部分完成内容将重新向量化在知识库导入中skip_if_existsTrue常用于避免重复处理已经存在的内容。但是在此前的行为下如果某个内容已经被记录为failed或partial它也可能被跳过。结果就是内容虽然没有完整完成向量化却被当作已存在内容忽略最终可能继续以不完整状态存在。v3.0.5 修复了这一问题。现在当启用skip_if_existsTrue时系统不再跳过已经被记录为failed或partial的内容。换句话说已成功完成的内容仍可按存在逻辑进行跳过已失败的内容不会被静默标记为完成部分完成的内容也不会被直接跳过不完整内容会重新执行 Embedding。这一变化的目标非常明确避免导入不完整的内容被错误地视为已完成。对于曾经出现过部分向量化失败、或者历史记录中存在失败内容的知识库来说v3.0.5 能够让后续导入更有机会重新补全这些内容而不是继续保留一个看似存在、实际不可完整检索的状态。八、新能力支持部分完成状态 partialpartial是 v3.0.5 最重要的新能力之一。在文件导入过程中内容通常会被拆分为多个 Chunk再分别进行 Embedding 和写入。如果其中部分 Chunk 成功而其他 Chunk 失败过去很难用单一状态准确描述这种结果。现在ContentStatus.PARTIAL专门用于表示这种部分完成的情况。该状态意味着文件并非完全失败文件也并非完全完成部分 Chunk 已经可被搜索整个文件的检索能力仍然是不完整的因此不能将它归为completed同时也不应将它简单归为failed。这种状态对于知识库运维和内容质量判断非常重要。如果内容处于partial状态开发者可以知道当前文件并不是完全不可用而是“可搜索但不完整”。这能够帮助业务系统在展示内容导入结果时提供更真实的反馈也能够帮助开发者决定是否进行重新导入。九、新能力导入期间可选的 Embedding 重试机制v3.0.5 新增了一个可选的 Embedding 重试能力。该能力默认关闭。如果希望在知识库导入期间启用重试可以在创建Knowledge时配置Knowledge(max_embedding_retries3,embedding_retry_backoff1.0)其中max_embedding_retries3表示最大 Embedding 重试次数为 3embedding_retry_backoff1.0表示重试之间的退避参数为 1.0该能力默认不开启只有显式配置后才会生效。需要特别注意认证失败的处理规则。当 Embedding 失败的原因是认证问题时系统不会使用上述重试设置而是会在第一次尝试后直接失败。原因是认证凭据如果被拒绝使用同一份凭据进行多次重试并不能解决问题。因此认证失败会忽略max_embedding_retries和embedding_retry_backoff的配置。此外这项重试机制还有一个重要行为每次重试都会重新对整个文档执行 Embedding。也就是说重试不是只针对单个失败 Chunk 进行补偿而是会重新嵌入整个文档。使用该能力时需要清楚理解这一行为。对于偶发性 Embedding 失败重试机制可以提供额外的恢复机会但对于认证失败系统会立即停止而不会进行无意义的重复尝试。十、新工具包GandrTools 文本转语音能力v3.0.5 新增了GandrTools工具包。该工具包面向 Gandr TTS API提供文本转语音能力。这意味着agno 在本次版本中加入了新的 TTS 工具接入支持使开发者可以通过对应工具包使用 Gandr 的文本转语音 API。该更新属于新增功能不涉及此前知识库导入和 Embedding 失败处理的兼容性调整但与其他新增能力一起构成了 v3.0.5 的功能扩展内容。十一、新模型提供商llmman在模型提供商支持方面v3.0.5 新增了llmman模型提供商。这项更新扩展了 agno 的模型提供商范围为使用该模型提供商的开发者提供了新的接入选择。十二、重新导入更安全失败时不再破坏已有可搜索 Chunkv3.0.5 对重新导入内容时的数据保护行为进行了重要改进。过去如果对一个已存在文档执行重新导入或重新 Embedding而新的 Embedding 过程失败可能会出现一个严重后果原有的 Chunk 已经被删除但新的 Chunk 又没有成功生成。最终这个文档可能从原本“可搜索”变成“零 Chunk”即完全无法检索。v3.0.5 通过embed_before_replace保护机制改善了这一行为。这一保护机制会先对文档进行 Embedding再替换原有内容。也就是说系统会在删除已有内容之前优先完成新的 Embedding 流程。如果重新 Embedding 失败重新导入会在删除旧内容之前中止。这样一来已有的可搜索 Chunk 不会因为一次失败的重新导入而被销毁。该改进对于生产环境尤其重要。它避免了“更新失败导致原有检索内容全部消失”的问题使重新导入过程更加安全。可以将新行为理解为旧行为先删除旧 Chunk再生成新 Chunk如果生成失败文档可能变成零 Chunk新行为先生成新 Embedding再替换旧 Chunk如果生成失败旧 Chunk 仍然保留。因此v3.0.5 在重新导入失败场景下能够更好地保护已有的可检索数据。十三、错误信息更可操作Embedding 失败不再只有模糊提示在错误提示方面v3.0.5 也进行了改进。此前当 Embedding 写入失败时开发者可能只会看到类似下面的模糊信息Could not insert embedding这种提示无法帮助开发者快速判断问题发生在哪个阶段也无法明确知道失败影响了多少内容、使用了哪个 Embedder或者下一步应该如何处理。在新版本中Embedding 失败消息变得更具可操作性。失败信息将包含以下内容发生失败的 Chunk 数量使用的 Embedder失败原因恢复步骤。相比“无法插入 Embedding”这样的笼统提示新错误信息能够让开发者更快定位问题并根据提示采取对应的恢复措施。这也是 v3.0.5 的整体设计方向之一不仅要让失败被暴露出来还要让失败信息更容易被理解和处理。十四、MCPTools 支持静态 headers 参数v3.0.5 对MCPTools进行了扩展新增支持静态headers参数。现在对于 Streamable HTTP 和 SSE 连接方式开发者可以直接在url路径中传递连接时认证所需的请求头而无需构造StreamableHTTPClientParams。这意味着连接时的认证 Header 可以更直接地通过headers提供。适用范围包括Streamable HTTPSSE。这一改进简化了 MCPTools 的连接配置尤其适用于需要在连接阶段携带静态认证请求头的场景。开发者不再必须通过额外的客户端参数对象来配置连接认证信息而可以使用更直接的方式进行传递。十五、其他变更汇总除了上述主要功能和兼容性调整外v3.0.5 还包含以下变更重新启用了litellm和crawl4aiextras修复了 cookbook 中损坏的模型、导入以及图片 URL增加了 Gandr 文本转语音工具包增加了 llmman 模型提供商增加了 MCPTools 的连接时静态 Header 支持修复知识库导入时 Embedding 失败被掩盖的问题发布 v3.0.5。十六、升级到 agno v3.0.5 后需要重点检查什么从本次更新内容来看升级后最需要关注的是 Embedding 失败处理相关逻辑。首先业务系统需要接受一个事实部分此前显示为completed的内容在新版本中可能会显示为failed或partial。这不是系统变得更容易失败而是系统开始如实报告原本就不完整的导入结果。其次需要适配新的内容状态processing completed partial failed尤其是前端状态展示、后端状态判断、自动化任务以及内容轮询逻辑都不应再假设状态只有三种。再次需要检查异常捕获逻辑。如果使用 AWS Bedrock Embedding并且此前通过ModelProviderError捕获异常那么需要调整为捕获EmbeddingError。如果直接调用向量数据库search()也需要适配从“返回空列表”到“抛出异常”的行为变化。同时对于调用内容状态接口的逻辑需要正确处理 404GET /knowledge/content/{id}/status当内容不存在或不属于当前访问者时系统不再返回failed而是返回 404。最后如果使用了skip_if_existsTrue需要了解失败和部分完成内容现在会被重新进行 Embedding而不会被简单跳过。这一变化能够避免不完整内容被继续静默保留。十七、结语代码地址github.com/agno-agi/agnoagno v3.0.5 的重点不是简单增加几个功能而是对知识库导入可靠性、Embedding 错误可见性和内容状态准确性进行了一次系统性强化。本次升级后的核心变化可以概括为Embedding 失败将被明确报告不再被掩盖内容状态新增partial用于表示可搜索但不完整的内容Embedder 失败抛出EmbeddingError不再返回空向量直接调用向量数据库search()时失败将抛出异常Knowledge.search()保持返回无结果的行为AWS Bedrock Embedding 失败改为抛出EmbeddingError内容状态接口对不存在或无权限内容返回 404skip_if_existsTrue不再跳过失败或部分完成内容支持可选的 Embedding 重试但认证失败不会重试每次重试会重新 Embedding 整个文档重新导入失败时已有可搜索 Chunk 将得到保护错误信息包含 Chunk 数量、Embedder、失败原因与恢复步骤MCPTools 支持静态headers新增 GandrTools 文本转语音工具包新增 llmman 模型提供商重新启用litellm与crawl4aiextras修复 cookbook 中的模型、导入和图片 URL 问题。对于使用 agno 构建知识库、RAG、向量检索和模型工具调用能力的开发者来说v3.0.5 的最大价值在于让“看起来导入成功”变成“真正能够确认导入结果”让失败不再隐藏让部分完成有明确状态让重新导入不再轻易破坏已有可检索内容。