agno v3.0.6 发布：无状态 MCP、协议协商、AgentOS 文件上传与多项稳定性修复全解析

2026 年 9 月 8 日，agno 发布 v3.0.6。 本次更新围绕 MCP 服务能力、AgentOS 能力扩展、模型兼容性、文本切分稳定性以及 AG-UI 数据传输等方向展开。 其中，无状态 MCP 服务、MCP 协议模式选择、MCP Server Card、.zip 与 .eml 文件上传，是本版本最值得关注的新增能力。

一、版本概览：agno v3.0.6 更新了什么

agno v3.0.6 的更新内容可以归纳为四个方向：

1. 1. MCP 服务端与客户端能力升级

2. 2. AgentOS 服务能力增强

3. 3. Bedrock、Anthropic、Gemini 等模型适配优化

4. 4. RecursiveChunking、AG-UI、代码切分依赖等稳定性修复

本次版本并不只是新增功能，也对已有能力的兼容性与运行稳定性进行了针对性优化。尤其是 MCP 相关改动，涉及服务端状态管理、协议时代协商、客户端实现方式以及服务能力描述接口等多个层面。

二、核心新增：无状态 MCP 服务正式加入

agno v3.0.6 新增了无状态 MCP 服务能力。

通过以下配置：

MCPConfig(stateless=True)

可以让/mcp以无状态方式提供服务。

无状态模式的核心特征是：服务端不再跟踪会话状态。也就是说，任何一个服务副本都可以处理任意一次请求，不需要把同一个客户端的请求持续绑定到某一个固定实例。

对于多实例部署场景而言，这意味着部署时不再需要会话亲和性。

传统的会话型服务通常需要保证同一会话的后续请求持续路由到同一个服务实例，否则会出现会话状态无法找到、上下文不连续等问题。agno v3.0.6 的无状态 MCP 服务则移除了这类会话跟踪要求，因此在多副本环境中，任意副本都能够响应任意请求。

这一能力使/mcp的服务方式更加适合无需会话跟踪的场景。

不过，无状态模式也并非默认启用。该模式会带来明确的能力取舍：

• • 不支持服务端主动发起通知

• • 不支持 SSE 的可恢复能力

• • 不保留会话跟踪能力

因此，agno 仍然默认关闭无状态模式。

换句话说，v3.0.6 并没有直接替换现有的会话型 MCP 行为，而是提供了一个可选配置。对于仍然依赖服务端通知、SSE 恢复或者既有会话行为的使用方式，默认配置不会发生改变。

这一设计兼顾了新能力引入与已有行为稳定性。需要无状态部署能力时，可以显式开启；需要保留传统会话能力时，则继续使用默认配置。

三、MCPTools 新增协议模式选择：兼顾旧行为与新协议时代

除了无状态 MCP 服务，agno v3.0.6 还为MCPTools增加了protocol_mode参数。

配置形式如下：

MCPTools(protocol_mode=...)

该参数用于选择 MCP 协议协商所处的协议时代。

目前提供两种关键模式：

• •"legacy"

• •"auto"

默认值是：

protocol_mode="legacy"

默认使用"legacy"的目的，是保持当前以会话为中心的行为不变。

也就是说，现有项目即使升级到 agno v3.0.6，也不会因为默认协议行为变化而被迫迁移到新的无会话模式。原有服务端和客户端的会话式交互方式能够继续保持。

而当配置为：

protocol_mode="auto"

MCPTools会自动协商双方都支持的最新协议时代。

文档中明确指出，从 2026 年 7 月 28 日开始，MCP 已经支持无会话的协议时代。在"auto"模式下，如果通信双方均支持这一新的协议能力，就会协商使用更新的模式。

需要注意的是，已有服务不会因此受到影响。

即使服务端已经具备现代协议能力，它依然会接受传统握手方式。也就是说，协议能力提升并不意味着旧客户端立即失效，传统握手仍然可以被现代服务端接受。

这项更新体现了 agno 对兼容性的重视：

• • 默认保持既有会话式行为

• • 可选自动协商最新协议能力

• • 现代服务端继续兼容传统握手

• • 已有服务无需因升级而立即调整协议实现

对于需要稳定运行的现有系统，"legacy"提供了连续性；对于希望使用新协议能力的场景，"auto"提供了向新协议时代演进的入口。

四、MCP 客户端内部升级：基于 fastmcp.Client 构建

agno v3.0.6 中，MCP 客户端的内部实现也进行了调整。

现在，MCP 客户端基于：

fastmcp.Client

构建。

这一变化属于 MCP 客户端实现层面的升级，与 MCP 服务端的无状态能力、协议模式协商共同构成了本次 MCP 相关更新的重要部分。

从版本说明来看，agno 已迁移 MCP 客户端和 AgentOS 服务端，以适配 MCP 2.x。

这意味着 v3.0.6 不仅新增了配置层面的能力，也同步调整了 MCP 相关组件的底层实现方向。

对于使用者来说，重点在于以下几点：

• • MCPTools 可以通过protocol_mode控制协议协商方式

• • 现有默认行为保持为传统会话模式

• • 新协议能力可以通过自动协商方式使用

• • MCP 客户端内部已基于fastmcp.Client构建

• • AgentOS MCP 服务端也已面向 MCP 2.x 演进

五、AgentOS MCP Server Card：新增服务能力说明接口

agno v3.0.6 为 AgentOS MCP Server 增加了 Server Card。

新接口地址为：

GET /mcp/server-card

该接口用于提供 MCP 服务端的能力说明信息。

Server Card 会列出当前服务所提供的工具。也就是说，访问/mcp/server-card后，可以获取到该 MCP 服务端实际对外提供的工具清单。

除了工具列表外，Server Card 还支持携带以下可配置内容：

• • 名称

• • 版本

• • 说明

因此，AgentOS MCP Server 不再仅仅提供工具调用能力，也可以通过固定接口对外描述自身的服务身份与服务说明。

这一能力使 MCP 服务端能够以更清晰的形式呈现以下信息：

• • 当前服务是什么

• • 当前服务使用什么版本

• • 当前服务提供哪些工具

• • 当前服务有哪些说明信息

在 v3.0.6 中，Server Card 的能力包含两个明确部分：

1. 1. 支持配置名称、版本和说明

2. 2. 支持列出当前服务所提供的工具

这使 AgentOS MCP Server 的服务信息具备更完整的可访问入口。

六、AgentOS 文件上传增强：支持.zip与.eml

在文件上传能力方面，agno v3.0.6 为 AgentOS 新增了两种文件类型支持：

• •.zip

• •.eml

其中，.zip是压缩包文件格式，.eml是电子邮件文件格式。

在此版本之前，AgentOS 的文件上传支持范围不包含这两种格式；升级至 v3.0.6 后，文件上传场景可以覆盖.zip与.eml。

这一更新直接扩展了 AgentOS 可接收的文件类型范围。

本次更新说明中明确列出的新增支持就是这两种格式，因此升级后如需处理压缩包文件或邮件文件，可以关注 AgentOS 的文件上传能力变化。

七、认证配置增强：自定义路由可以单独公开

agno v3.0.6 新增了：

AuthorizationConfig.excluded_route_paths

该配置用于将自定义路由标记为公开访问路径。

其关键意义在于：可以让特定自定义路由不受认证限制，同时不需要全局关闭认证。

这是一个更细粒度的认证控制能力。

过去，如果希望某些自定义路由不进行认证校验，可能会面临全局认证开关与局部访问需求之间的取舍。v3.0.6 增加excluded_route_paths后，可以明确指定哪些自定义路由是公开的。

它解决的是以下场景：

• • 全局认证仍然保持开启

• • 某些自定义路由需要对外公开

• • 不希望因为开放个别路由而关闭整个系统的认证能力

通过该配置，认证策略可以在全局保护与局部公开之间进行区分。

版本说明特别强调：AuthorizationConfig.excluded_route_paths可以标记自定义路由为公开路径，而不需要在全局范围内禁用认证。

八、Bedrock 支持传入自定义异步客户端

在 Bedrock 适配方面，agno v3.0.6 新增了自定义异步客户端支持。

现在，可以将自有的异步客户端传递给模型或嵌入器。

也就是说，Bedrock 的模型或嵌入器不再只能使用内部创建的异步客户端，也可以接收调用方提供的异步客户端。

本次更新覆盖两个位置：

• • 模型

• • 嵌入器

这一能力的重点在于“传入自有异步客户端”。对于需要自行管理异步客户端的场景，v3.0.6 提供了对应支持。

九、Anthropic 修复：原样回放助手轮次，避免思考块被拒绝

agno v3.0.6 修复了 Anthropic 相关的一个问题。

修复内容是：回放助手轮次时，将其原样回放。

这样做的结果是，思考块不会再被拒绝。

版本说明中指出，此前在回放助手消息轮次时，思考块可能会出现被拒绝的问题。v3.0.6 通过原样回放助手轮次的方式解决了这一问题。

此次修复的关键点包括：

• • 针对 Anthropic

• • 涉及助手轮次回放

• • 使用原样回放方式

• • 解决思考块被拒绝的问题

这是一项针对消息回放行为的兼容性修复。

十、Gemini 修复：不再固定使用 image/jpeg

在 Gemini 的图像处理相关逻辑中，agno v3.0.6 修复了图像 MIME 类型被固定写为image/jpeg的问题。

现在，系统会解析图像的实际 MIME 类型，而不是一律使用：

image/jpeg

这一修复的含义是：图像在传递给 Gemini 时，不再被统一视为 JPEG 格式，而是根据图像实际类型解析对应的 MIME 类型。

版本说明明确指出，修复方向是：

• • 解析图像 MIME 类型

• • 不再硬编码为image/jpeg

这一调整提升了 Gemini 图像输入处理的准确性。

此外，本次变更列表中还增加了 Gemini 3.8 Flash 示例。

因此，Gemini 相关更新包含两个部分：

1. 1. 修复图像 MIME 类型固定为image/jpeg的问题

2. 2. 增加 Gemini 3.8 Flash 示例

十一、RecursiveChunking 修复：不再产生重复的尾部切片

在文本切分能力方面，agno v3.0.6 修复了RecursiveChunking的重复尾部切片问题。

修复后，RecursiveChunking不会再输出重复的末尾 chunk。

此前，递归切分过程中可能会出现尾部 chunk 被重复发出的情况。v3.0.6 对此进行了修复，目标是停止产生重复的尾部内容块。

此次修复的重点非常明确：

• • 针对RecursiveChunking

• • 修复重复的 trailing chunks

• • 防止末尾内容块被重复输出

对于依赖递归文本切分的使用场景，这项修复改善了切分结果的完整性与一致性。

十二、AG-UI 更新：远程实体传输使用 wire fields

agno v3.0.6 对 AG-UI 的远程实体通信进行了修复。

此前，AG-UI 向远程实体发送内容时，涉及RunContext。本次修复后，AG-UI 将发送 wire fields，而不是发送RunContext。

也就是说，远程实体通信时发送的数据形式发生了调整：

• • 修复前：涉及发送RunContext

• • 修复后：发送 wire fields

版本说明将这一变更描述为：向远程实体发送 wire fields，而不是RunContext。

这是一项面向 AG-UI 远程实体交互的数据传输修复。

十三、AG-UI 新增：暴露流式运行错误

除了远程实体的数据传输修复，AG-UI 在 v3.0.6 中还新增了一项错误处理能力。

现在，AG-UI 可以暴露流式运行错误。

也就是说，在流式运行过程中，如果出现错误，相关错误信息可以被暴露出来。

本次更新中，AG-UI 相关内容包括两项：

1. 1. 向远程实体发送 wire fields，而不是RunContext

2. 2. 暴露流式运行错误

这两项更新分别覆盖数据传输与错误可见性。

十四、代码切分依赖修复：固定 tree-sitter-language-pack 版本范围

agno v3.0.6 对代码切分器相关依赖进行了版本限制调整。

具体内容是固定：

tree-sitter-language-pack < 1.16

这样做是为了恢复 chonkie 代码切分器的可用性。

版本说明明确指出，固定tree-sitter-language-pack小于 1.16，是为了避免该依赖版本导致 chonkie code chunker 被阻塞。

这一改动属于依赖兼容性修复，目标是解除代码切分器的阻塞问题。

关键点包括：

• • 影响组件：chonkie 代码切分器

• • 调整对象：tree-sitter-language-pack

• • 版本限制：小于 1.16

• • 修复目的：解除代码切分器阻塞

十五、文档与工程维护：AGENTS.md 改为指向 CLAUDE.md 的符号链接

在工程维护层面，agno v3.0.6 将AGENTS.md调整为指向CLAUDE.md的符号链接。

这一变更属于项目文件维护调整。

版本变更列表中明确列出：

AGENTS.md 是 CLAUDE.md 的符号链接

该项内容与 MCP、AgentOS、模型适配和 bug 修复不同，属于仓库内文档或工程文件组织方式的调整。

十六、v3.0.6 全量变更内容汇总

为了便于快速核对，agno v3.0.6 的全部更新内容可以汇总如下。

新增功能

1. 1. 新增无状态 MCP 服务
   通过MCPConfig(stateless=True)提供无状态/mcp服务。任何副本都可响应任何请求，多实例部署不再需要会话亲和性。代价是不支持服务端主动通知和 SSE 可恢复能力，因此默认关闭。

2. 2. 新增 MCPTools 协议模式选择
   通过MCPTools(protocol_mode=...)选择 MCP 协议协商时代。默认"legacy"，保持现有会话式行为；"auto"协商双方都支持的最新协议时代，即从 2026 年 7 月 28 日开始的无会话能力。已有服务不受影响，现代服务端仍接受传统握手。

3. 3. MCP 客户端基于fastmcp.Client构建
   MCP 客户端内部实现完成调整，并与 MCP 2.x 迁移相关。

4. 4. 新增 AgentOS MCP Server Card
   提供GET /mcp/server-card接口，用于列出服务工具，并携带可配置的名称、版本和说明。

5. 5. AgentOS 文件上传支持.zip与.eml
   文件上传范围新增压缩包文件和邮件文件支持。

6. 6. 新增AuthorizationConfig.excluded_route_paths
   可将自定义路由标记为公开路径，同时保持全局认证继续启用。

7. 7. Bedrock 支持自定义异步客户端
   可以将自有异步客户端传递给模型或嵌入器。

8. 8. 增加 Gemini 3.8 Flash 示例
   本次变更列表包含 Gemini 3.8 Flash 的示例内容。

问题修复

1. 1. Gemini 图像 MIME 类型修复
   不再将图像 MIME 类型固定为image/jpeg，而是解析实际图像 MIME 类型。

2. 2. chonkie 代码切分器修复
   固定tree-sitter-language-pack < 1.16，解除代码切分器阻塞问题。

3. 3. AG-UI 流式运行错误暴露
   流式运行期间的错误可以被暴露。

4. 4. Bedrock 自定义异步客户端支持
   支持向 Bedrock 模型或嵌入器传入提供的异步客户端。

5. 5. AG-UI 远程实体传输修复
   向远程实体发送 wire fields，不再发送RunContext。

6. 6. RecursiveChunking 重复尾部切片修复
   不再发出重复的末尾 chunk。

7. 7. Anthropic 助手轮次回放修复
   原样回放助手轮次，避免思考块被拒绝。

8. 8. AgentOS MCP Server Card 能力补充
   支持在 Server Card 中配置名称、版本和说明。

9. 9. MCP Server Card 工具列表能力补充
   Server Card 可以列出当前服务提供的工具。

10. 10. 自定义公开路由配置支持
    新增AuthorizationConfig.excluded_route_paths，实现局部公开路由而无需关闭全局认证。

11. 11. AgentOS 上传.zip与.eml支持
    文件上传新增这两种格式。

12. 12. 文档文件组织调整
    AGENTS.md调整为CLAUDE.md的符号链接。

13. 13. MCP 2.x 迁移与无状态传输支持
    MCP 客户端与 AgentOS 服务端完成 MCP 2.x 方向迁移，新增无状态 MCP 传输，并使用fastmcp.Client构建 MCP 客户端。

十七、结语

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

agno v3.0.6 的重点集中在 MCP 与 AgentOS。

MCP 方面，本次版本同时提供了无状态服务、协议模式选择、基于fastmcp.Client的客户端实现，以及可展示服务工具和说明信息的 MCP Server Card。

AgentOS 方面，新增了.zip与.eml文件上传支持，并通过AuthorizationConfig.excluded_route_paths提供了更细粒度的公开路由控制能力。

模型与基础能力方面，Bedrock 支持传入自定义异步客户端，Anthropic 修复了思考块回放被拒绝的问题，Gemini 修复了图像 MIME 类型固定为image/jpeg的问题，RecursiveChunking 解决了重复尾部 chunk 问题，AG-UI 则优化了远程实体数据传输并暴露流式运行错误。

从更新内容来看，agno v3.0.6 在保持传统会话式 MCP 默认行为的同时，为无状态 MCP 与新协议协商能力提供了明确入口；在增强 AgentOS 服务能力的同时，也对多个模型适配、文本切分与流式交互细节进行了修复。

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