agno v2.3.21版本發布詳解：AgentOS全面支持Agent As Judge評測與多項穩定性增強

2025年12月23日，agno 官方發布了 v2.3.21 版本。本次更新在保持高性能和私有化架構優勢的基礎上，重點增強了 AgentOS 對評測體系的支持，同時修復了多個在實際生產和評測場景中可能遇到的問題，并補充了新的 Cookbook 示例。下面將基于本次發布內容，對 v2.3.21 的核心更新進行系統梳理。

一、核心新特性：AgentOS全面集成Agent-as-Judge評估

本次更新最核心的增強在于對“Agent as Judge”（智能體作為評判者）評估功能的全面支持，并將其深度集成到了AgentOS控制平面中。

1. 功能概述
“Agent as Judge”是一種先進的評估范式，它使用一個專門的智能體（Judge Agent）來評估另一個智能體（或團隊）在給定任務上的輸出質量。這通常用于衡量響應的準確性、相關性、完整性等主觀性較強的指標。與傳統的基于規則或簡單字符串匹配的評估方式相比，Agent as Judge能夠利用大語言模型的理解能力，進行更接近人類判斷的評估。

2. 集成詳情
在v2.3.21之前，開發者可能已經能夠在Agno框架內創建Agent as Judge評估邏輯，但管理和運行這些評估可能不夠便捷。本次更新后，這一功能在AgentOS中獲得了完整的官方支持：

• ? 配置與觸發 ：用戶現在可以直接在AgentOS的Evals（評估）頁面中，配置新的Agent as Judge評估任務并觸發其運行。這為評估工作流提供了統一的圖形化界面。

• ? 統一管理 ：Agent as Judge評估的運行記錄將與現有的準確性、性能、可靠性等評估結果一同，集中展示在Evals頁面中。這實現了對所有類型評估的集中監控和管理，極大地提升了操作效率。

• ? API端點增強 ：對應的GET API端點也已更新，現在可以返回Agent as Judge評估的相關數據，確保了控制平面與后端服務的數據一致性。

3. 開發者價值
這一集成意味著團隊可以更系統化地對智能體的輸出質量進行監控和迭代。例如，在產品上線后，可以定期用Agent as Judge評估客服智能體的回答是否恰當，或者審核內容生成智能體的輸出是否符合安全規范。所有評估歷史和結果都可在AgentOS中追溯，為模型優化和提示詞工程提供了數據基礎。

二、關鍵問題修復

v2.3.21版本修復了兩個可能影響開發體驗和生產穩定性的問題。

1. RunInput對象持久化修復

• ? 問題描述 ：當開發者將 RunInput 對象的 input_content 屬性設置為一個 Message 對象的列表時，框架在嘗試持久化（例如存入數據庫）該對象時會發生錯誤。 RunInput 用于封裝單次智能體運行的輸入信息，而 Message 是構成對話歷史的基本單元。這個問題會導致包含復雜對話歷史的運行記錄無法正確保存。

• ? 修復內容 ：開發團隊修復了 RunInput （及其對應的 TeamRunInput ）的 to_dict() 和 input_content_string() 方法中的序列化邏輯。現在，當 input_content 是一個混合了 Message 對象、字典或其他基礎類型的列表時，框架能夠正確地將所有元素遞歸地轉換為可JSON序列化的字典結構。修復確保了無論輸入內容多么復雜，都能被無歧義地轉換為字符串或字典格式，從而順利地進行網絡傳輸或數據庫存儲。

• ? 影響 ：這個修復對于依賴會話歷史、實現復雜對話邏輯或進行運行審計的應用至關重要。它保證了數據管道的可靠性。

2. MistralEmbedder類超時設置修復

• ? 問題描述 ： MistralEmbedder 類用于調用Mistral AI的嵌入模型，將文本轉換為向量。在之前的版本中，其 timeout 參數（用于設置HTTP請求超時時間）的傳遞方式存在錯誤，導致設置可能未生效或格式不正確。

• ? 修復內容 ：修復了初始化Mistral客戶端時的參數映射。現在， timeout 參數會被正確地轉換并傳遞給底層的客戶端庫（ timeout 秒被轉換為 timeout_ms 毫秒）。這保證了開發者可以有效地控制嵌入過程的等待時間，避免因網絡問題或服務延遲導致進程無限期掛起。

• ? 影響 ：該修復提升了使用Mistral嵌入模型進行知識庫構建（RAG）時的穩定性和可預測性。特別是在處理大量文檔或網絡環境不穩定時，合理的超時設置可以防止整個工作流阻塞。

本次更新在cookbook中添加了一個全新的、名為“Speech to Text”的示例目錄，展示了如何利用Agno構建一個端到端的語音轉文本應用。

1. 示例結構
該示例包含了多個獨立的腳本和一個完整的工作流，演示了不同的實現方式和集成深度：

• ? 基礎單智能體轉錄 ：

• • ? stt_openai_agent_simple.py ：使用OpenAI的語音模型（gpt-audio）進行簡單轉錄，返回純文本。

  • ? stt_openai_agent.py ：同樣使用OpenAI模型，但通過 parser_model （如gpt-5-mini）將轉錄結果解析為結構化的Pydantic模型輸出（包含說話人、每句話文本等字段）。

  • ? stt_gemini_agent.py ：使用Google Gemini模型進行結構化轉錄，展示了模型無關的特性。

• ? 高級工作流 ： stt_workflow.py ：演示了如何構建一個Agno Workflow，將音頻URL獲取、音頻格式轉換（如MP3轉WAV）、智能體轉錄、結構化輸出生成等多個步驟編排成一個自動化流程。該工作流可部署到AgentOS，提供一個完整的服務端點。

2. 技術亮點

• ? 多模態支持 ：示例核心利用了Agno智能體原生的多模態處理能力。通過 agno.media.Audio 類，可以直接將音頻字節數據或文件傳遞給智能體。

• ? 結構化輸出 ：展示了如何通過定義Pydantic output_schema ，讓智能體返回高度結構化的轉錄結果，而非雜亂文本，便于下游系統處理。

• ? 工作流編排 ： stt_workflow.py 是Agno Workflow能力的典型展示。它將不同的處理單元（函數、智能體）連接成有向無環圖，管理狀態傳遞和錯誤處理，適用于生產級復雜任務。

• ? 模型無關性 ：示例同時使用了OpenAI和Gemini的模型，強調了Agno可以輕松切換底層AI提供商。

3. 開發者價值
這個示例為開發者處理音頻輸入場景提供了即用的模板。無論是構建會議記錄工具、客服錄音分析系統，還是任何需要將語音轉換為可分析文本的應用，都可以以此為起點快速開發。

四、其他重要變更與文檔更新

除了上述核心內容，v2.3.21版本還包含了一系列細微但重要的調整。

1. 數據庫集成調整
在agent_as_judge_basic.py示例中，數據庫從SQLite切換為了PostgreSQL，并提供了標準的連接字符串示例。這引導開發者從開發環境（SQLite）更平滑地過渡到生產環境（PostgreSQL）。

2. 評估邏輯優化
在Agent as Judge評估運行后，將評估結果記錄到數據庫時，現在正確地將“評判者智能體”所使用的模型信息（model_id, model_provider）與“被評估智能體”的模型信息區分開來并分別存儲。這使得評估元數據更加清晰，便于分析不同評判者模型對評估結果的影響。

3. README與文檔優化
項目的主README.md文件以及Cookbook的說明文檔cookbook/README.md都進行了大幅重寫，風格更加簡潔、指向性更強。

• ? 快速定位 ：新文檔更明確地根據用戶目標（“我想構建單個智能體”、“我想讓智能體協作”、“我想部署和管理”）來引導讀者前往相應的示例目錄。

• ? 特性強調 ：更突出地強調了Agno“私有化部署”、“性能極致”、“生產就緒”的核心優勢。

• ? 入門引導 ：將“入門指南”和“完整演示”作為最優先的路徑，降低新用戶的學習曲線。

4. 依賴項更新

• ? 將核心 agno 包版本升級至 2.3.21 。

• ? 更新了 fastapi 、 fastapi-cli 、 yfinance 等關鍵依賴的版本，以獲取最新的功能和安全補丁。

Agno v2.3.21版本是一次扎實的迭代，它沒有引入顛覆性的變更，而是在現有強大的基礎上進行打磨和增強。

• ? 對于評估與監控 ：通過將Agent as Judge深度集成到AgentOS，它為團隊提供了企業級的智能體性能評估工具，使得基于LLM的定性評估變得可配置、可觸發、可追溯。

• ? 對于框架穩定性 ：對RunInput序列化和MistralEmbedder超時的修復，解決了特定場景下的潛在bug，提升了框架在處理復雜數據和外部服務調用時的魯棒性。

• ? 對于開發者生態 ：新增的語音轉文本示例是一個高質量、可直接復用的“菜譜”（Cookbook），豐富了Agno的應用場景庫，展示了其在多模態和復雜工作流方面的強大能力。

拓展視野：擁抱AI浪潮，關注行業前沿

在鉆研Agno這類前沿多智能體技術的同時，了解更廣闊的AI行業動態同樣重要。如今，AI正以前所未有的深度重塑工作和創造力。

在此為大家推薦一個高質量的行業信息源——由脈脈平臺推出的 【脈向AI】 直播欄目。這個欄目專注于：

核心價值：

• ? 提供最新的AI工具、模型趨勢和行業深度解析

• ? 邀請AI領域 頭部創作者、行業專家 分享一線經驗和未來洞見

• ? 探討AI在內容創作、效率提升、產品創新等場景的實際應用

• ? 提供 實時互動 機會，可直接向嘉賓提問并獲得解答

? 對開發者的意義：
這不僅是了解行業趨勢的窗口，更是拓展技術視野、連接行業人脈、把握職業新機遇的平臺。在脈脈這個覆蓋超2億職場用戶的生態中，你能接觸到最真實的行業聲音和機會。

參與方式：
歡迎關注脈脈APP內的 「脈向AI」 欄目，預約最新直播，與AI前沿保持同步。