agno 在 2025 年 12 月 20 日正式发布 v2.3.18 版本。本次更新提交数量虽不多，但涵盖了对 Google Vertex AI 使用方式的重要改进，以及对 AgentOS 中数据库迁移路由的一项关键缺陷修复，整体提升了在生产环境和系统重同步场景下的稳定性与可配置性。

一、版本基本信息

版本号：v2.3.18
发布日期：2025 年 12 月 20 日
本次发布共包含 3 个提交，涉及 6 个文件变更，新增代码约 730 行，主要集中在模型能力扩展、系统路由修复和测试补充三个方面。

二、主要改进内容

1. Google Vertex AI 新增显式凭证文件支持

在 v2.3.18 中，agno 的 Gemini 模型对 Vertex AI 的认证方式进行了增强，新增了对 google oauth2 凭证对象的直接支持。这意味着在使用 Vertex AI 模式时，不再只依赖环境变量或默认凭证，而可以显式传入一个凭证对象，用于精细化控制生产环境下的认证方式。

核心变化点包括：

• Gemini 模型新增 credentials 参数，用于接收 Google Cloud 的凭证对象
• 当 vertexai 参数为 True 时，如果提供了 credentials，将其直接传入 genai Client
• 在非 Vertex AI 模式（即 Google AI Studio 模式）下，即使提供了 credentials，也不会被传递，避免混用认证方式

这种设计使得模型在不同运行环境下的行为更加明确，特别适合以下场景：

• 多项目、多服务账号并存的生产环境
• 容器化或 CI/CD 场景中需要显式加载服务账号 JSON 文件
• 不方便或不允许使用全局默认凭证的部署环境

官方示例中通过加载服务账号 JSON 文件创建凭证对象，并在初始化 Gemini 模型时传入，从而直接完成 Vertex AI 的身份认证配置。

2. Gemini 客户端初始化逻辑完善

在 Gemini 模型的 get_client 方法中，对 Client 初始化参数进行了细化处理：

• Vertex AI 模式下，project 和 location 参数会被明确设置
• 如果 credentials 不为空，则加入 Client 初始化参数
• 最终统一过滤掉值为 None 的参数，保证 Client 初始化参数干净且可控

同时补充了对应的单元测试，分别验证了以下情况：

• Vertex AI 模式下传入 credentials 时，Client 能正确接收
• Vertex AI 模式下未传入 credentials 时，不会错误传递该参数
• 非 Vertex AI 模式下，即使传入 credentials，也不会传递给 Client

这些测试确保了不同模式下 Gemini 客户端行为的一致性和可预期性。

三、问题修复：数据库迁移路由无法重建

本次版本还修复了一个在 AgentOS 重同步过程中存在的问题。此前在执行 resync 操作时，数据库迁移路由在某些情况下不会被正确重新注册，导致相关接口缺失。

在 v2.3.18 中：

• 重构了路由重新注册列表
• 确保数据库路由在重同步时能够被正确重新 provision
• 避免系统在重载配置或恢复状态后出现数据库相关功能不可用的问题

这一修复对依赖 AgentOS 进行长期运行和热更新的场景尤为重要。

四、测试与版本号更新

为了保证上述改动的稳定性，本次更新新增了：

• 针对 Gemini 模型凭证逻辑的单元测试
• 针对 AgentOS resync 行为的集成测试

同时，agno 的项目版本号在 pyproject.toml 中从 2.3.17 正式更新为 2.3.18，与发布版本保持一致。

五、小结

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

agno v2.3.18 是一次以稳定性和生产可用性为核心的版本更新：

• 在模型层面，为 Vertex AI 提供了更灵活、安全的认证方式
• 在系统层面，修复了数据库路由在重同步时的关键缺陷
• 在工程层面，通过新增测试确保行为的一致性