agno v3.1.0正式发布：RBAC权限体系、AgentOS 文件系统、MCP行为变更与完整升级指南

2026年10月2日，agno v3.1.0 正式发布。本次版本围绕 AgentOS 的企业级能力、文件管理能力、MCP 配置与认证机制，以及多项工具和数据处理稳定性进行了集中升级。

对于正在构建多用户、多角色、多权限智能体应用的开发者来说，v3.1.0 最值得关注的变化是全新的用户管理与授权能力，也就是基于角色的访问控制机制。同时，AgentOS 新增了可持久化的文件系统能力，MCP 工具的默认发布行为也发生了重要调整。

需要特别注意的是，本次更新包含两项破坏性变更：一项涉及 DbFileSystem 的数据库表结构升级，另一项涉及 MCP 默认工具与生命周期工具的发布逻辑。如果项目中已经使用了相关功能，升级前必须充分评估并完成迁移。

一、版本信息

• • 版本号：v3.1.0

• • 发布时间：2026年10月2日

• • 项目地址：github.com/agno-agi/agno

agno v3.1.0 的更新重点可以概括为四个方向：

1. 1. AgentOS 新增 RBAC 用户管理与授权体系

2. 2. AgentOS 新增数据库驱动的文件系统

3. 3. MCP 配置、认证和工具发布行为更新

4. 4. 图像、视频、语音、转录工具与多个底层稳定性问题修复

二、全新用户管理与授权能力：RBAC 正式进入 AgentOS

agno v3.1.0 新增了agno.os.authz包，为 AgentOS 带来了基于角色的访问控制能力，也就是 RBAC。

在多用户智能体应用中，权限管理一直是非常核心的问题。不同用户可能拥有不同角色，不同角色又可能对应不同的操作范围。比如，有些用户只能查看资源，有些用户能够管理资源，而管理员则可能需要拥有完整的管理权限。

本次新增的agno.os.authz包，提供了一整套围绕授权管理构建的能力，包括：

• • 角色存储

• • 范围策略

• • 审计日志

• • 用户目录

• • 管理路由

• • 可插拔授权引擎

• • 原生授权引擎

• • 细粒度 FGA 授权引擎

其中，角色存储用于保存用户角色相关信息。范围策略用于定义不同角色、不同用户或不同资源在什么范围内可以执行哪些操作。审计日志则用于记录授权相关的行为，方便后续追踪、排查和管理。

用户目录为用户管理提供基础能力，管理路由则为管理员提供了操作入口。通过这些能力，AgentOS 可以更完整地支持用户、角色、权限和资源之间的关联关系。

本次更新还扩展了 scopes 与认证中间件，使其能够执行授权校验。也就是说，权限控制不再只是单独存在的配置或逻辑，而是可以与认证流程、中间件处理流程和访问范围结合起来。

对于 AgentOS 应用而言，这意味着用户身份识别之后，可以进一步根据角色、范围策略和授权引擎判断请求是否允许继续执行。

v3.1.0 同时支持可插拔的授权引擎，包括：

• • 原生授权引擎

• • 细粒度 FGA 授权引擎

原生授权引擎适用于使用 agno 内置授权能力的场景。细粒度 FGA 授权引擎则面向需要进行更细粒度授权处理的情况。

这项更新让 AgentOS 在用户管理、权限划分、访问控制、操作审计等方面具备了更完整的基础能力。

三、AgentOS Filesystem：新增数据库文件系统能力

agno v3.1.0 新增了agno.fs文件系统能力，其中包括DbFileSystem。

DbFileSystem是一个数据库驱动的文件系统实现。它通过专门的/filesystem路由提供文件操作能力，支持以下功能：

• • 列出文件

• • 读取文件

• • 管理文件

这些文件操作由agno_fs数据表支撑。

对于 AgentOS 而言，文件是智能体工作流中的重要资源。无论是用户上传内容、智能体生成的结果，还是不同用户分区下的文件资源，都需要稳定的存储和访问机制。

DbFileSystem提供了以数据库为基础的文件系统管理方案，并且具备独立的表结构和初始化能力。它可以从一个基础的db_url构建，不依赖 MigrationManager 管理。

这一点非常重要：DbFileSystem的数据库表结构由它自身管理，因此不属于 MigrationManager 的迁移范围。

换句话说，如果项目中使用了DbFileSystem，升级时需要单独处理文件系统表的迁移，而不能依赖常规迁移流程自动完成。

四、破坏性变更之一：agno_fs 文件系统表重新设计主键

v3.1.0 对agno_fs文件系统表的键结构进行了调整。

在新版本中，文件系统表使用以下组合字段作为键：

(namespace, user_id, path)

其中：

• •namespace表示命名空间

• •user_id表示用户分区

• •path表示文件路径

这里的user_id被用于用户分区。

当文件属于共享分区或无用户分区时，user_id使用空字符串：

""

也就是说，v3.1.0 通过namespace、user_id和path的组合来定位文件资源。这样的设计使文件能够按照用户进行分区，同时保留共享或无用户场景下的文件访问方式。

但是，这项表结构调整也带来了明确的升级要求。

如果agno_fs表是由更早版本创建的，v3.1.0 会拒绝继续使用旧表，并抛出SchemaOutdatedError。

系统不会自动执行表重建或重新设置键的操作。

这是一次必须手动执行的数据库升级。

需要注意的是，这项变更只影响使用DbFileSystem的项目。如果项目没有使用DbFileSystem，则不需要执行这部分升级。

官方要求是在应用停止运行的情况下，执行一次文件系统表迁移。

PostgreSQL 的迁移脚本如下：

python libs/agno/migrations/migrate_filesystem_postgres.py

SQLite 的迁移脚本如下：

python libs/agno/migrations/migrate_filesystem_sqlite.py

升级步骤可以整理为以下流程：

1. 1. 停止应用运行

2. 2. 确认项目是否使用DbFileSystem

3. 3. 根据实际数据库类型选择对应迁移脚本

4. 4. 执行文件系统迁移

5. 5. 确认迁移完成后再启动应用

由于旧表会被新版本识别为过期结构，因此不能跳过这一步。若未完成迁移，使用DbFileSystem的应用将会因SchemaOutdatedError无法正常继续使用旧文件系统表。

五、MCP 配置与认证能力更新

agno v3.1.0 对 MCP 服务端配置进行了刷新，同时更新了内置 MCP 认证处理能力。

MCP 相关功能在本次更新中有两个重点：

• • MCP 服务端配置更新

• • 内置 MCP 认证处理更新

除此之外，MCP 工具的默认发布行为发生了破坏性调整。

这意味着，开发者需要重点检查现有的MCPConfig配置，尤其是项目中已经通过tools=[...]显式配置工具的场景。

六、破坏性变更之二：MCP 默认工具和生命周期工具改为显式启用

在 v3.1.0 中，MCP 的默认工具和生命周期工具不再自动发布。

新的行为是：

MCPConfig(tools=[...])

只会发布开发者在tools中明确列出的工具。

也就是说，配置中列出了什么工具，就只会暴露什么工具。

此前的行为不同。

在旧版本中，当使用tools=[...]配置 MCP 工具时，除了显式列出的工具之外，系统还会提供内置默认工具，以及生命周期工具。

这些生命周期工具包括：

continue_run
cancel_run

而在 v3.1.0 中：

• •default_tools默认值为False

• •lifecycle_tools默认值为False

这意味着，默认工具和生命周期工具都需要显式启用。

新的行为可以理解为：MCP 工具发布从“包含显式工具并保留内置工具”变成了“严格只发布显式声明的工具”。

这项调整可以让工具暴露范围更加清晰。开发者可以明确控制 MCP 服务到底对外发布哪些能力。

但同时，也意味着旧项目如果依赖默认工具、continue_run或cancel_run，升级后可能出现工具不可用的情况。

因此，升级到 v3.1.0 后，应重点检查以下内容：

• • 是否依赖 MCP 内置默认工具

• • 是否依赖continue_run

• • 是否依赖cancel_run

• • 是否需要显式开启default_tools

• • 是否需要显式开启lifecycle_tools

• • 是否已经在tools中完整列出需要发布的工具

如果原有业务流程依赖继续运行或取消运行等生命周期能力，必须在升级配置时完成适配。

七、新增 AIMLAPITools：支持图像、视频、语音与转录能力

agno v3.1.0 新增了AIMLAPITools工具集。

该工具集支持通过 AI/ML API 使用以下能力：

• • 图像

• • 视频

• • 语音

• • 转录

这项更新为智能体调用多模态服务提供了新的工具入口。

其中，图像、视频、语音和转录属于不同类型的多媒体能力。通过AIMLAPITools，开发者可以在工具体系中使用 AI/ML API 提供的相应能力。

对于需要处理视觉内容、生成视频、处理语音或进行语音转录的智能体应用来说，这项新增工具集扩展了可调用的能力范围。

八、HITL 修复：后台流式继续运行不再重复写入暂停记录

本次版本修复了 HITL 场景中的一个问题。

此前，当一个暂停的运行通过后台模式并使用流式方式继续执行时，暂停的运行可能会在自身历史记录中被重复写入。

v3.1.0 修复后，使用 background 与 stream 继续暂停运行时，不再将该暂停运行重复添加到其自身历史中。

这项修复改善了暂停、继续执行和运行历史之间的一致性。

九、OpenAIResponses 修复：链式响应丢失时可恢复请求

v3.1.0 修复了 OpenAIResponses 的请求恢复问题。

在链式响应场景中，如果前一个响应，也就是 chained 或 previous response 已经不存在，相关请求此前可能无法正常恢复。

本次修复后，当链式响应中引用的前一个响应丢失时，系统可以恢复请求处理。

这提升了 OpenAIResponses 在前序响应不可用场景下的稳定性。

十、数据库修复：异步删除失败不再被误判为运行不存在

数据库层面也修复了一个错误区分问题。

此前，当异步删除操作失败时，系统可能会将失败错误错误地报告为目标运行不存在。

v3.1.0 对这两种情况进行了区分：

• • 运行确实不存在

• • 异步删除操作失败

修复后，异步删除失败不再被当作“运行不存在”处理。

这让数据库操作的错误信息更加准确，也有助于定位真实问题。

十一、结构化输出修复：JSON 片段先出现标量不再崩溃

在结构化输出处理中，v3.1.0 修复了一个 JSON 片段解析问题。

此前，当 JSON 片段在列表之前先提供了一个标量值时，系统可能发生崩溃。

本次修复后，即使 JSON 片段先出现标量、后续再出现列表，也不会因此导致崩溃。

这提升了结构化输出处理在增量 JSON 片段场景下的兼容性。

十二、Python 工具结果修复：区分 None 值与变量缺失

v3.1.0 修复了 Python 工具结果中的值识别问题。

此前，Python 工具结果中的None值与变量不存在的情况可能无法明确区分。

现在，系统能够区分：

• • 变量存在，但值为None

• • 变量根本不存在

这项修复保证了 Python 工具结果的语义更加准确。

None是一个明确的值状态，而变量缺失则是另一种状态。两者应当被不同处理，本次更新完成了这一修正。

十三、Chunking 修复：重叠长度必须小于分块长度

在文本分块功能中，v3.1.0 增加了对无效重叠参数的拒绝处理。

当 overlap 不小于 chunk size 时，系统会拒绝该配置。

也就是说，重叠长度必须小于分块长度。

这是一个必要的参数约束。现在系统会阻止 overlap 不小于 chunk size 的情况继续使用。

十四、CSV 读取修复：支持 CR 换行符

v3.1.0 修复了 CSV 读取器对换行符的处理。

此前，CSV 读取可能无法正确处理仅使用 CR，也就是\r作为记录结尾的文件。

本次修复后，CSV 读取器可以处理使用\r作为记录结束符的 CSV 内容。

这改善了 CSV 文件在不同换行符格式下的读取兼容性。

十五、CsvTools 修复：显式设置零行限制时正确生效

在CsvTools中，v3.1.0 修复了显式设置行限制为零时的行为。

现在，明确指定零行限制会被正确遵守。

也就是说，如果设置的行数限制是0，系统会按照这个值处理，而不会将其忽略或误认为未设置。

十六、Shell 与工作区命令工具修复：显式零尾部限制正确生效

Shell 工具和工作区命令工具也修复了类似问题。

此前，显式设置 tail 为零时，系统可能无法正确遵守该设置。

v3.1.0 修复后，显式设置的零 tail 值会被正确处理。

也就是说，当 tail 被明确设置为0时，工具会尊重这个值。

十七、GeminiTools 修复：视频生成产物保存原始视频字节

v3.1.0 更新了GeminiTools.generate_video的产物处理方式。

现在，生成视频时会在 artifact 中存储原始视频字节。

这项修复确保视频生成结果以原始字节形式被保存在生成产物中。

十八、GithubTools 修复：分支链接与非 ASCII UTF-8 文本处理改进

GithubTools在本次版本中包含两项修复。

第一项修复是分支链接构建方式。

现在，分支链接会基于仓库的 web URL 构建。

第二项修复是get_file_content的内容读取行为。

现在，GithubTools.get_file_content可以保留有效的非 ASCII UTF-8 文本。

也就是说，当仓库文件内容包含有效的非 ASCII UTF-8 字符时，工具能够正确保留这些文本内容。

十九、LocalFileSystemTools 修复：本地文件统一按 UTF-8 读写

LocalFileSystemTools在 v3.1.0 中修复了本地文件读写编码问题。

现在，本地文件会使用 UTF-8 编码进行读取和写入。

这意味着：

• • 读取本地文件时使用 UTF-8

• • 写入本地文件时使用 UTF-8

该修复统一了本地文件工具的文本编码处理方式。

二十、PubMed 修复：短摘要保留元数据

PubMed 工具修复了短摘要场景下的元数据保留问题。

此前，较短的摘要可能无法完整保留相关元数据。

v3.1.0 修复后，短摘要也可以保留元数据。

二十一、Claude 引用修复：保留可为空的文档标题

在 Claude citations 处理方面，v3.1.0 修复了文档标题为空时的处理问题。

现在，可为空的文档标题能够被保留。

也就是说，当引用中的文档标题是 nullable 状态时，系统不会错误丢弃这一信息。

二十二、agno v3.1.0 升级重点汇总

升级到 agno v3.1.0 时，最需要关注以下几个方面。

1. 是否使用 DbFileSystem

如果使用了DbFileSystem，必须检查agno_fs表是否来自旧版本。

旧表结构不能自动升级，新版本会抛出SchemaOutdatedError。

需要停止应用后，根据数据库类型执行对应迁移脚本：

python libs/agno/migrations/migrate_filesystem_postgres.py

或：

python libs/agno/migrations/migrate_filesystem_sqlite.py

2. 是否依赖 MCP 默认工具

如果原来使用MCPConfig(tools=[...])，并依赖系统自动提供的默认工具，升级后需要重新确认配置。

v3.1.0 中，工具列表只会发布显式列出的工具。

3. 是否依赖 MCP 生命周期工具

如果流程中依赖以下工具：

continue_run
cancel_run

则需要注意，生命周期工具默认不再发布。

lifecycle_tools的默认值现在是False。

4. 是否需要默认 MCP 工具

default_tools的默认值现在也是False。

若业务需要默认工具，应在配置中明确启用。

5. 检查数据处理相关边界行为

本次版本修复了多个边界问题，包括：

• • JSON 片段中的标量和列表处理

• • Python 工具中None与变量缺失的区分

• • overlap 与 chunk size 的约束

• • CSV 的\r记录结尾

• • 零行限制

• • 零 tail 限制

• • UTF-8 文本读写

• • 非 ASCII UTF-8 内容保留

• • 短摘要元数据保留

• • 可为空文档标题保留

如果项目依赖这些功能，应在升级后重点验证相关流程。

二十三、结语

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

agno v3.1.0 是一次面向 AgentOS 管理能力、文件系统能力、MCP 工具控制能力和稳定性的重要更新。

本次版本最核心的新增能力包括：

• •agno.os.authzRBAC 用户管理与授权体系

• • 角色存储、范围策略、审计日志、用户目录和管理路由

• • 原生授权引擎与细粒度 FGA 授权引擎

• •agno.fs与DbFileSystem

• •/filesystem文件列出、读取和管理路由

• •AIMLAPITools的图像、视频、语音与转录能力

• • MCP 服务端配置与内置认证处理更新

同时，本次版本最关键的兼容性变化包括：

• •agno_fs文件系统表改为以(namespace, user_id, path)为键

• • 旧版文件系统表必须在应用停止后手动迁移

• • MCP 默认工具默认关闭

• • MCP 生命周期工具默认关闭

• •MCPConfig(tools=[...])只发布明确列出的工具

除此之外，v3.1.0 还修复了 HITL、OpenAIResponses、数据库异步删除、结构化输出、Python 工具结果、文本分块、CSV、Shell、GeminiTools、GithubTools、本地文件系统、PubMed 和 Claude citations 等多个问题。

对于使用 AgentOS、DbFileSystem 和 MCP 的项目而言，升级前应优先完成文件系统表迁移评估，并重新检查 MCP 工具发布配置。

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