Hugging Face 在 Python 中的 Tiny Agents

Hugging Face 已將其「Tiny Agents」概念移植至 Python，擴充 huggingface_hub 客戶端 SDK，使其能作為模型上下文協議（MCP）客戶端。透過標準化大型語言模型（LLM）發現與執行外部工具的方式，開發者只需約 70 行程式碼即可建立功能完整的 AI 代理。

模型上下文協議（MCP）

MCP 是一項開放協議，旨在標準化 LLM 與外部工具或 API 之間的互動。透過提供通用介面，MCP 消除開發者為每個工具編寫自訂整合的需求，簡化為 LLM 添加新功能的流程。

執行與設定 Tiny Agents

在安裝帶有 mcp 額外套件的 huggingface_hub 函式庫後，即可透過 CLI 部署 Tiny Agents：

pip install "huggingface_hub[mcp]>=0.32.0"

代理設定

代理的行為由 agent.json 檔案定義，並可選擇性提供 PROMPT.md 以給予詳細的系統指示。agent.json 檔案指定：

  • Model: 要使用的 LLM（例如 Qwen/Qwen2.5-72B-Instruct）。
  • Provider: 推論提供者（例如 Nebius）。
  • Servers: 代理應連接的 MCP 伺服器陣列。這些可以是 stdio 伺服器（透過指令與參數以本地程序執行）或 http 伺服器（遠端工具）。

部署範例

代理可以從本機設定載入，或直接從 Hugging Face Hub 上的 tiny-agents/tiny-agents 資料集載入。範例包括：

  • Web-Browsing Agent：使用 Playwright MCP 伺服器操作沙盒 Chromium 瀏覽器。
  • Image Generation Agent：連接到作為 MCP 伺服器的 FLUX.1 [schnell] 圖像生成 HF Space。

技術架構：MCPClient

huggingface_hub 中的 MCPClient 是管理工具使用功能的核心元件。其主要職責包括管理與 MCP 伺服器的非同步連線、發現可用工具、為 LLM 格式化這些工具，以及執行工具呼叫。

連線與工具發現

add_mcp_server 方法根據伺服器類型（stdio、sse 或 http）建立連線。連線成功後，客戶端會初始化 ClientSession，並呼叫 list_tools() 以取得伺服器的可用工具。這些工具隨後會被格式化為符合 OpenAI Chat Completions API 的結構，該結構是 InferenceClient 使用的標準介面。

工具執行迴圈

process_single_turn_with_tools 方法處理 LLM 互動循環：

  1. Preparation（準備）: 彙總來自 MCP 伺服器的工具以及任何「exit loop」控制工具。
  2. Streaming（串流）: 使用 AsyncInferenceClient.chat.completions.create 向 LLM 發出串流呼叫。
  3. Processing（處理）: 當資料塊到達時，客戶端重建文字回應及任何請求的工具呼叫。
  4. Execution（執行）: 若呼叫了工具，客戶端會識別相應的 MCP 工作階段，並透過 session.call_tool() 執行該工具。結果隨後會被格式化並加入對話歷史。

代理實作

Agent 類別繼承自 MCPClient，並加入對話管理層。它被設計為一個簡單的迴圈，維持狀態並判斷任務何時完成。

初始化

在建立時，Agent 會以系統提示初始化對話歷史，並呼叫 load_tools() 以連接所有已設定的 MCP 伺服器，填充代理可用的工具箱。

核心執行迴圈

Agent.run() 方法是一個非同步生成器，透過 while True 迴圈處理使用者輸入。每次迭代時，它將 LLM 與工具的互動委派給 process_single_turn_with_tools，並即時產出結果。

迴圈會在以下三種情況下終止：

  • 明確呼叫了「exit loop」工具。
  • 已達到最大回合數 (MAX_NUM_TURNS)。
  • LLM 提供了最終文字回應，且不再需要進一步的工具呼叫。

Sources