agno v3.0.5发布：Embedding失败不再被掩盖，知识库状态、重试机制与检索行为全面升级

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 编写了类似以下逻辑：

except ModelProviderError:
    ...

那么升级到 v3.0.5 后，这段代码将不再捕获 Bedrock 的 Embedding 失败。

开发者需要将异常处理改为捕获：

except EmbeddingError:
    ...

这不是单纯的异常名称变化，而是异常分类逻辑的调整。由于失败发生在 Embedding 环节，因此新版本将其归入EmbeddingError，而不是ModelProviderError。

对于已有的错误监控、重试策略、日志分类和告警规则，也应当同步检查是否依赖ModelProviderError来识别 Bedrock Embedding 问题。

六、内容状态接口更严格：不存在或无权限内容将返回 404

v3.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_exists=True 行为升级：失败与部分完成内容将重新向量化

在知识库导入中，skip_if_exists=True常用于避免重复处理已经存在的内容。

但是，在此前的行为下，如果某个内容已经被记录为failed或partial，它也可能被跳过。结果就是：内容虽然没有完整完成向量化，却被当作已存在内容忽略，最终可能继续以不完整状态存在。

v3.0.5 修复了这一问题。

现在，当启用：

skip_if_exists=True

时，系统不再跳过已经被记录为failed或partial的内容。

换句话说：

• • 已成功完成的内容，仍可按存在逻辑进行跳过；

• • 已失败的内容，不会被静默标记为完成；

• • 部分完成的内容，也不会被直接跳过；

• • 不完整内容会重新执行 Embedding。

这一变化的目标非常明确：避免导入不完整的内容被错误地视为已完成。

对于曾经出现过部分向量化失败、或者历史记录中存在失败内容的知识库来说，v3.0.5 能够让后续导入更有机会重新补全这些内容，而不是继续保留一个看似存在、实际不可完整检索的状态。

八、新能力：支持部分完成状态 partial

partial是 v3.0.5 最重要的新能力之一。

在文件导入过程中，内容通常会被拆分为多个 Chunk，再分别进行 Embedding 和写入。如果其中部分 Chunk 成功，而其他 Chunk 失败，过去很难用单一状态准确描述这种结果。

现在，ContentStatus.PARTIAL专门用于表示这种部分完成的情况。

该状态意味着：

1. 1. 文件并非完全失败；

2. 2. 文件也并非完全完成；

3. 3. 部分 Chunk 已经可被搜索；

4. 4. 整个文件的检索能力仍然是不完整的；

5. 5. 因此不能将它归为completed；

6. 6. 同时也不应将它简单归为failed。

这种状态对于知识库运维和内容质量判断非常重要。

如果内容处于partial状态，开发者可以知道当前文件并不是完全不可用，而是“可搜索但不完整”。这能够帮助业务系统在展示内容导入结果时提供更真实的反馈，也能够帮助开发者决定是否进行重新导入。

九、新能力：导入期间可选的 Embedding 重试机制

v3.0.5 新增了一个可选的 Embedding 重试能力。

该能力默认关闭。

如果希望在知识库导入期间启用重试，可以在创建Knowledge时配置：

Knowledge(
    max_embedding_retries=3,
    embedding_retry_backoff=1.0
)

其中：

• •max_embedding_retries=3表示最大 Embedding 重试次数为 3；

• •embedding_retry_backoff=1.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 的模型提供商范围，为使用该模型提供商的开发者提供了新的接入选择。

十二、重新导入更安全：失败时不再破坏已有可搜索 Chunk

v3.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 HTTP；

• • SSE。

这一改进简化了 MCPTools 的连接配置，尤其适用于需要在连接阶段携带静态认证请求头的场景。

开发者不再必须通过额外的客户端参数对象来配置连接认证信息，而可以使用更直接的方式进行传递。

十五、其他变更汇总

除了上述主要功能和兼容性调整外，v3.0.5 还包含以下变更：

• • 重新启用了litellm和crawl4aiextras；

• • 修复了 cookbook 中损坏的模型、导入以及图片 URL；

• • 增加了 Gandr 文本转语音工具包；

• • 增加了 llmman 模型提供商；

• • 增加了 MCPTools 的连接时静态 Header 支持；

• • 修复知识库导入时 Embedding 失败被掩盖的问题；

• • 发布 v3.0.5。

从本次更新内容来看，升级后最需要关注的是 Embedding 失败处理相关逻辑。

首先，业务系统需要接受一个事实：部分此前显示为completed的内容，在新版本中可能会显示为failed或partial。这不是系统变得更容易失败，而是系统开始如实报告原本就不完整的导入结果。

其次，需要适配新的内容状态：

processing
completed
partial
failed

尤其是前端状态展示、后端状态判断、自动化任务以及内容轮询逻辑，都不应再假设状态只有三种。

再次，需要检查异常捕获逻辑。

如果使用 AWS Bedrock Embedding，并且此前通过ModelProviderError捕获异常，那么需要调整为捕获EmbeddingError。如果直接调用向量数据库search()，也需要适配从“返回空列表”到“抛出异常”的行为变化。

同时，对于调用内容状态接口的逻辑，需要正确处理 404：

GET /knowledge/content/{id}/status

当内容不存在或不属于当前访问者时，系统不再返回failed，而是返回 404。

最后，如果使用了skip_if_exists=True，需要了解失败和部分完成内容现在会被重新进行 Embedding，而不会被简单跳过。这一变化能够避免不完整内容被继续静默保留。

十七、结语

代码地址：github.com/agno-agi/agno

agno v3.0.5 的重点，不是简单增加几个功能，而是对知识库导入可靠性、Embedding 错误可见性和内容状态准确性进行了一次系统性强化。

本次升级后的核心变化可以概括为：

• • Embedding 失败将被明确报告，不再被掩盖；

• • 内容状态新增partial，用于表示可搜索但不完整的内容；

• • Embedder 失败抛出EmbeddingError，不再返回空向量；

• • 直接调用向量数据库search()时，失败将抛出异常；

• •Knowledge.search()保持返回无结果的行为；

• • AWS Bedrock Embedding 失败改为抛出EmbeddingError；

• • 内容状态接口对不存在或无权限内容返回 404；

• •skip_if_exists=True不再跳过失败或部分完成内容；

• • 支持可选的 Embedding 重试，但认证失败不会重试；

• • 每次重试会重新 Embedding 整个文档；

• • 重新导入失败时，已有可搜索 Chunk 将得到保护；

• • 错误信息包含 Chunk 数量、Embedder、失败原因与恢复步骤；

• • MCPTools 支持静态headers=；

• • 新增 GandrTools 文本转语音工具包；

• • 新增 llmman 模型提供商；

• • 重新启用litellm与crawl4aiextras；

• • 修复 cookbook 中的模型、导入和图片 URL 问题。

对于使用 agno 构建知识库、RAG、向量检索和模型工具调用能力的开发者来说，v3.0.5 的最大价值在于：让“看起来导入成功”变成“真正能够确认导入结果”，让失败不再隐藏，让部分完成有明确状态，让重新导入不再轻易破坏已有可检索内容。

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