agno v2.3.18 版本更新詳解：Vertex AI 顯式憑證支持與數據庫路由修復

agno 在 2025 年 12 月 20 日正式發布 v2.3.18 版本。本次更新提交數量雖不多，但涵蓋了對 Google Vertex AI 使用方式的重要改進，以及對 AgentOS 中數據庫遷移路由的一項關鍵缺陷修復，整體提升了在生產環境和系統重同步場景下的穩定性與可配置性。

一、版本基本信息

版本號：v2.3.18
發布日期：2025 年 12 月 20 日
本次發布共包含 3 個提交，涉及 6 個文件變更，新增代碼約 730 行，主要集中在模型能力擴展、系統路由修復和測試補充三個方面。

二、主要改進內容

1. 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 的身份認證配置。

1. 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 提供了更靈活、安全的認證方式

• ? 在系統層面，修復了數據庫路由在重同步時的關鍵缺陷

• ? 在工程層面，通過新增測試確保行為的一致性

我們相信人工智能為普通人提供了一種“增強工具”，并致力于分享全方位的AI知識。在這里，您可以找到最新的AI科普文章、工具評測、提升效率的秘籍以及行業洞察。 歡迎關注“福大大架構師每日一題”，發消息可獲得面試資料，讓AI助力您的未來發展。