Hugging Face 小型代理：用 50 行程式碼構建 MCP 驅動的代理

Hugging Face 已證明，結合模型上下文協議（MCP）以及現代大型語言模型（LLM）原生的工具呼叫支援，只需約 50 行程式碼即可實作一個功能完整的 AI 代理。其核心概念在於，一旦建立了用於處理工具發現與執行的 MCP 客戶端，代理本質上只是一個在 LLM 推理與工具執行之間交替的 while 迴圈。

模型上下文協議（MCP）作為工具標準

MCP 作為一套標準 API，用於公開可與 LLM 整合的工具集合。透過 MCP，開發者可以將工具與 LLM 的實作解耦，讓推理客戶端能夠將來自不同 MCP 伺服器的可用工具掛接到模型的推理流程中。

目前，MCP 伺服器以本地程序的形式運行。Hugging Face 的實作使用 @modelcontextprotocol/sdk/client TypeScript SDK 連接這些伺服器，並透過 listTools() 方法取得可用工具。這些工具隨後會重新格式化為符合原生 LLM 工具呼叫介面的 JSONSchema 表示（名稱、說明與參數）。

使用 InferenceClient 實作 MCP 客戶端

為了構建 MCP 驅動的代理，Hugging Face 使用 @huggingface/inference JS 函式庫中的 InferenceClient。整體架構包含三個主要元件：

  1. Inference Client：管理與 LLM 供應商（例如 Nebius）以及模型（例如 Qwen2.5-72B-Instruct）的連線。
  2. MCP Client Sessions：為每個已連線的 MCP 伺服器維護會話映射，以處理工具執行。
  3. Tool Registry：從所有已連線的 MCP 伺服器彙總的可用工具清單。

當 LLM 產生工具呼叫時，客戶端會識別對應的 MCP 會話，並使用 client.callTool() 方法執行該函式並取得結果，然後將結果作為工具訊息回饋給 LLM。

代理架構：「While 迴圈」邏輯

代理被定義為系統提示、LLM 推理客戶端、MCP 客戶端以及基本控制流程的組合。Hugging Face 避免手動將工具說明注入提示中，而是依賴推理引擎的原生 tools 參數。

控制流程與迴圈終止

代理的主迴圈在工具呼叫與將結果回饋給 LLM 之間交替。迴圈在以下情況下會終止：

  • Explicit Task Completion：LLM 呼叫特定的 task_complete 工具。
  • User Interaction：LLM 呼叫 ask_question 工具以向使用者請求更多資訊。
  • Turn Limit：回合數超過預先定義的 MAX_NUM_TURNS。
  • Response Pattern：當 LLM 連續兩條非工具訊息回應時，迴圈即中斷。

實作範例與 Demo

使用者可以透過 npx @huggingface/mcp-client 執行完整的 Demo。預設設定會連接兩個本地 MCP 伺服器：

  • File System Server：允許代理存取本機桌面，以讀寫檔案。
  • Playwright MCP Server：提供一個沙盒化的 Chromium 瀏覽器，用於網頁導覽與搜尋。

例如，代理可以處理複雜的多步驟提示，如在桌面上寫入一首俳句至檔案，或執行 Brave Search 以搜尋推理供應商並開啟前三個結果。

技術規格與可擴充性

  • Default Model：Qwen/Qwen2.5-72B-Instruct
  • Default Provider：Nebius
  • Language：TypeScript/JavaScript（使用 async generators 處理 LLM 回應）。
  • Extensibility：系統設計能與任何相容 OpenAI 的客戶端 SDK 以及多種推理供應商（包括 Cerebras、Cohere、Fireworks 等）協同運作，也支援透過 llama.cpp 或 LM Studio 使用本地 LLM。

Sources