agno v2.5.17 更新：文件引用可关闭、GitHub 配置支持按请求指定、流式与组件加载全面修复，稳定性再升级

一、版本概览

agno v2.5.17 已正式发布，这一版本虽然看起来是一个常规小版本更新，但从实际变更内容来看，覆盖面相当广，涉及能力增强、行为优化以及多个关键 bug 修复。整体上，这次更新更偏向于“稳定性增强 + 开发体验优化 + 关键细节修正”，特别适合正在使用 agno 构建工作流、模型调用、知识库、MCP 集成以及流式输出相关功能的开发者关注。

从这次更新内容来看，主要可以分为以下几个方向：

1. 新增能力

   • 支持关闭 Claude 文件引用
   • 支持 GitHubConfig 仓库按请求指定

2. 核心修复

   • 组件加载时保留自定义数据库表名
   • MCP 初始化时正确应用 header_provider 的请求头
   • 保留内部工作流事件身份，并为 agent/team 事件增加 nested_depth
   • 让知识库数据库在 config API 中实时构建
   • 停止向所有模型 provider 注入共享 HTTP/2 client
   • 在所有 router 流式生成器中显式捕获 CancelledError
   • 在清理 JSON 前先尝试原始 JSON 解析，以保留字符串中的代码块
   • 排除框架注入参数，避免出现在 user_input_schema 中
   • memory pipeline gate check 中补充 extra_messages 判断

3. 其他说明

   • 本版本同步了相关维护和发布流程更新，整体属于一次较全面的稳定性迭代。

接下来，我们按照更新内容逐项展开说明，帮助你完整了解 agno v2.5.17 到底改了什么、适合哪些场景、以及这些变化意味着什么。

二、Improvement：新增改进项

1. 支持关闭 Claude 文件引用

这是本次更新中非常值得关注的一个能力增强。
在 v2.5.17 中，新增了一个选项，可以禁用 Claude 的文件引用。

对于部分场景而言，文件引用并不是必须展示的内容，尤其是在你希望输出更简洁、或者不希望返回内容中带有额外引用信息时，这个能力会非常有用。通过该选项，开发者可以更灵活地控制 Claude 输出行为，让最终结果更贴近自己的产品需求。

这一改进的意义在于：

• 可以减少输出中的附加引用信息
• 有助于控制响应内容的呈现形式
• 在某些对展示格式要求更严格的场景中更实用

如果你的应用中会处理 Claude 相关输出，那么这个新选项可以直接提升可配置性和可控性。

2. GitHubConfig 的 repo 支持按请求指定

另一个新增能力是：GitHubConfig 中的 repo 可以按请求单独指定。

这意味着仓库配置不再完全依赖全局固定值，而是允许在每次请求时灵活传入不同的仓库配置。对于需要动态切换仓库、按用户、按任务、按项目去访问不同 GitHub 仓库的场景，这个能力会非常实用。

它带来的直接好处包括：

• 请求级别的仓库切换更加灵活
• 更适合多仓库、多项目的统一接入
• 降低全局配置固定化带来的限制
• 让 GitHub 相关能力在实际应用中更具适配性

这一改进对于构建面向多个代码仓库的自动化能力、知识集成能力、或者与 GitHub 数据交互的智能体应用，都很有帮助。

三、Bug Fixes：核心修复逐项说明

接下来是本次更新的重点，v2.5.17 一共包含多项修复，而且很多都属于会影响开发、运行稳定性或输出准确性的关键问题。

1. 加载组件时保留自定义数据库表名

此前在加载组件时，自定义数据库表名可能无法被正确保留。
在这次版本中，已经修复这一问题，确保加载组件后，自定义表名仍然保持原样。

这个修复的重要性很高，因为数据库表名往往是项目结构的一部分。如果加载组件时表名被覆盖或丢失，可能导致：

• 数据库映射异常
• 已有表结构无法正确识别
• 组件与数据库之间的对应关系出现偏差
• 在多环境部署中产生不一致问题

现在这个问题被修复后，组件加载流程会更稳定，也更适合有自定义数据库设计的项目。

2. MCP 初始化时正确应用 header_provider 的 headers

在 MCP 初始化过程中，之前可能存在一个问题：header_provider 提供的 headers 没有被正确应用。
v2.5.17 里已经修复这一点，保证在 MCP 初始化阶段，header_provider 返回的请求头能够被正确使用。

这类修复非常重要，因为请求头常常用于：

• 鉴权
• 身份标识
• 环境区分
• 路由控制
• 上下文传递

如果初始化时没有正确带上这些 headers，后续连接、调用或者权限校验都可能受到影响。
修复之后，MCP 初始化过程会更加可靠，减少由于 header 丢失导致的异常情况。

3. 保留内部工作流事件身份，并为 agent/team 事件增加 nested_depth

这次更新还修复了一个与事件结构有关的问题：
内部工作流事件的身份得以保留，同时 agent/team 事件新增了 nested_depth。

这意味着事件在传递和处理过程中，会保留更完整的身份信息；而 agent/team 类事件则可以通过 nested_depth 更清晰地表达嵌套层级。

这个修复的价值体现在：

• 更好地表示嵌套工作流结构
• 便于追踪 agent 和 team 事件的层级关系
• 有助于事件分析、调试和日志处理
• 提高复杂工作流中的事件可读性

对于涉及多层嵌套、内部工作流、团队协作型 agent 运行的场景，这类修复非常关键，因为它直接关系到事件链路是否清晰、是否能准确定位上下文。

4. 在 config API 中实时构建知识库数据库

本次版本修复了一个与知识库数据库有关的问题：
在 config API 中构建 knowledge dbs 时改为实时进行。

这意味着知识库数据库的构建不再依赖旧的延迟或不及时行为，而是在 config API 的相关流程中实时构建，从而提升配置阶段的准确性和即时性。

这个变化有几个明显好处：

• 配置与数据库状态更同步
• 减少因延迟构建导致的配置不一致
• 更适合动态更新知识库的场景
• 有利于提升整体配置流程的可靠性

对于依赖知识库进行检索、问答、上下文增强等能力的项目，这个修复会带来更稳定的实际体验。

5. 停止向所有模型 provider 注入共享 HTTP/2 client

这是一个非常值得关注的底层修复。
在此前版本中，系统可能会向所有 model provider 注入一个共享的 HTTP/2 client。v2.5.17 中已经调整为：不再将共享 HTTP/2 client 注入到所有模型提供方中。

这类变更通常意味着更合理的资源隔离和更清晰的 provider 行为边界。
共享 client 在某些情况下可能带来耦合、连接复用或兼容性问题，而现在改为不再统一注入，能让不同 provider 的连接行为更加独立。

这一修复可能带来的改善包括：

• 降低不同 provider 之间的相互影响
• 避免共享连接引发的兼容性问题
• 提升 provider 行为的一致性和可控性
• 有助于减少某些难以排查的运行异常

如果你的项目涉及多个模型 provider，这一修复尤其值得重视。

6. 在所有 router 流式生成器中显式捕获 CancelledError

流式输出场景中，取消异常的处理非常关键。
v2.5.17 修复了一个问题：在所有 router streaming generators 中显式捕获 CancelledError。

这意味着当流式任务被取消时，系统能够更明确地处理该异常，而不是让它以不透明的方式传播。
对于长期运行、可中断、实时输出的场景来说，这项修复能显著提升稳定性。

其价值主要在于：

• 改善取消请求时的异常处理
• 避免流式生成器因异常处理不明确而报错
• 提升 router 流式输出的健壮性
• 更适合交互式应用和实时响应场景

对于前端不断接收流式结果、用户可能随时终止请求的环境，这项修复非常重要。

7. 先尝试原始 JSON 解析，再进行清理，以保留字符串中的代码块

这一项修复非常细致，但对实际使用体验影响不小。
在 v2.5.17 中，系统在处理 JSON 时，改为先尝试原始 JSON 解析，如果失败后再进行清理处理。这样做的目的，是为了尽可能保留字符串中的代码块内容，避免在清理过程中误伤原始文本。

这个问题的核心在于：有些 JSON 内容中可能包含代码块、特殊字符串或带格式文本，如果直接进入清理流程，可能会导致内容结构发生变化，甚至丢失原本想保留的信息。现在先尝试原始解析，可以更好地保持原始数据完整性。

这一修复的优点包括：

• 更好地保留原始字符串内容
• 减少代码块被误清理的风险
• 提升 JSON 解析的准确性
• 让复杂文本内容在处理后仍保持原貌

对于包含代码、文档片段、格式化内容的 JSON 输入，这项修复非常实用。

8. 排除框架注入参数，避免出现在 user_input_schema 中

在用户输入 schema 的生成过程中，之前可能会把一些框架注入参数错误地包含进去。
v2.5.17 已经修复这个问题，确保这些参数会被排除，不再出现在user_input_schema中。

这项修复非常重要，因为user_input_schema的本意是描述用户实际需要提供的输入参数。如果把框架内部自动注入的参数也放进去，会带来以下问题：

• schema 不够纯粹，用户难以理解
• 前端表单生成可能出现冗余字段
• 验证逻辑可能受到干扰
• 用户输入与系统内部参数边界混淆

现在通过排除框架注入参数，schema 会更加干净、准确，也更符合用户输入的真实语义。

9. memory pipeline gate check 中包含 extra_messages

本次更新还修复了 memory pipeline 中 gate check 的一个遗漏：
现在会将 extra_messages 纳入判断。

这个修复看似简单，但实际意义很明确。
如果在 gate check 时忽略了 extra_messages，就可能导致内存管道对当前消息上下文判断不完整，进而影响后续处理结果。加入这个字段后，gate check 会更全面，判断依据也更充分。

这一修复能够带来的改善包括：

• 提高 memory pipeline 判断的完整性
• 让额外消息被正确纳入上下文检查
• 减少因为消息遗漏导致的流程偏差
• 提升内存相关逻辑的准确性

对于依赖消息上下文、记忆管理、额外补充消息的场景，这个修复非常必要。

四、What’s Changed：合并说明与发布相关更新

除了上面列出的主要功能与修复，本次版本在变更记录中还同步了多个维护类提交。虽然这些内容大多属于实现层面的整理，但从版本发布角度来看，它们共同组成了 v2.5.17 的完整更新集合。

对应的变更包括：

• 在 memory pipeline gate check 中包含 extra_messages
• 主验证工作流新增每周定时运行
• 排除框架注入参数，避免出现在 user_input_schema 中
• 先尝试原始 JSON 解析，再进行清理，以保留字符串中的代码块
• 在所有 router 流式生成器中显式捕获 CancelledError
• 停止向所有模型 provider 注入共享 HTTP/2 client
• 在 config API 中实时构建知识库数据库
• 保留内部工作流事件身份，并为 agent/team 事件增加 nested_depth
• 在 MCP 初始化时正确应用 header_provider 的 headers
• 加载组件时保留自定义数据库表名
• 允许 GitHubConfig 的 repo 按请求指定
• 支持关闭 Claude 文件引用
• 完成 2.5.17 版本发布

这些变更共同说明，agno v2.5.17 不是单纯增加一个新能力的小补丁，而是一次围绕可控性、稳定性、数据一致性和输出准确性的集中优化。

五、版本价值总结

如果把 agno v2.5.17 的变化做一个总结，可以看到它主要解决了几个关键方向的问题：

1. 更强的配置灵活性

• Claude 文件引用可关闭
• GitHubConfig repo 可按请求指定

2. 更好的运行稳定性

• 流式生成器显式捕获取消异常
• 停止向所有 provider 注入共享 HTTP/2 client

3. 更准确的结构保留

• 保留自定义数据库表名
• 保留内部工作流事件身份
• 增加 nested_depth

4. 更可靠的数据和输入处理

• 原始 JSON 优先解析
• 排除框架注入参数
• memory pipeline 纳入 extra_messages

5. 更完善的集成体验

• MCP 初始化正确应用 headers
• config API 中实时构建知识库数据库

可以说，这一版本非常适合正在构建复杂工作流、知识库系统、流式交互服务以及多 provider 集成项目的开发者升级和关注。

六、结语

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

agno v2.5.17 这次更新虽然没有堆砌大量全新功能，但从实际开发角度看，每一项变更都很“实用”。
它没有追求表面上的大而全，而是围绕开发者最容易遇到的问题进行了精准修复：
配置更灵活、流式更稳定、结构更完整、解析更准确、集成更可靠。