WebMCP 評估

Kasper Kulikowski

發布日期：2026 年 5 月 19 日

WebMCP 支援使用生成式 AI 模型的代理程式。如要使用生成式 AI 測試任何系統，測試必須支援機率性結果：一個輸入內容可能會產生數千個答案，準確度各不相同。這項測試技術稱為「評估」。

將工具發布到正式環境前，請務必確認代理程式瞭解何時應呼叫工具、如何執行工具，以及可接受的答案。在發生故障前，找出並解決問題。

編寫評估內容，測試系統與大型語言模型 (LLM) 的觸控點：

• 根據工具的說明和結構定義，確認模型是否瞭解工具的用途。
• 確認模型選擇的工具正確無誤，且參數符合使用者意圖。
• 確認模型是否根據收到的資訊採取行動，例如使用資訊呼叫其他工具。
• 確認使用者歷程是否順利。根據使用者的意圖，代理程式是否能使用提供的工具，在我的網站上順利完成使用者歷程？

對於任何不與模型通訊的系統互動，您都應繼續編寫傳統的決定性測試。

故障模式

開發人員應測試系統，防範故障發生。如要達成這個目標，您必須瞭解系統可能發生故障的時間，包括系統本身故障，以及與外部因素互動時發生故障。如果是 WebMCP，工具本身可能會發生故障，代理商也可能無法正常使用工具。

WebMCP 工具可能會失敗，代理也可能無法使用 WebMCP 工具。 舉例來說，假設使用者想將 T 恤加入購物車。

失敗	範例	疑難排解
代理未選取正確的工具，或直接呼叫錯誤的工具。	代理程式會略過 addToCart，直接前往 checkout。	工具的description是否清楚、完整，且準確反映工具的功能？ functionName是否直覺易懂且具描述性？ 工具是否在目前狀態/情境中正確向 LLM 公開？ 這個工具的結構定義是否可能與其他工具過於相似，導致呼叫不明確？
代理以錯誤順序呼叫工具	代理程式會呼叫 checkout，然後呼叫 addToCart。	工具說明是否重疊，導致 LLM 對必要順序感到困惑？ 前一個工具的輸出內容是否提供下一個工具呼叫所需的脈絡？ 狀態是否正確更新，且是否如預期向 LLM 公開任何新工具？ 如果以不同順序呼叫特定工具，端對端用途是否仍正確？ 您是否已強制執行先前的呼叫，確認 LLM 選擇正確的後續步驟，藉此單獨測試特定工具呼叫鏈？
代理呼叫工具時使用錯誤的引數	服務專員致電「addToCart」，但加入的是鞋子，而非 T 恤。	inputSchema 是否已清楚定義，包括 enum 值和每個屬性的良好 description？ 所有必要參數是否都已明確標示並經過檢查？ 引數的說明是否明確引導 LLM，瞭解如何將使用者輸入內容對應至預期的結構化資料 (例如特定 ID 或格式)？

如果使用者想查看購物車內容，該怎麼做？

失敗	範例	疑難排解
工具輸出內容有誤或遺漏資訊。	使用者要求 viewCart，但服務專員輸出購物車總價，而非產品名稱和個別價格。	基礎工具邏輯是否有錯誤 (請透過確定性測試檢查)？ UI 狀態是否已正確更新，且服務專員是否收到副作用的正確資訊？ 如果 LLM 會在後續呼叫中使用輸出內容，輸出內容的格式是否清楚明瞭，方便 LLM 擷取？ 輸出內容是否過於冗長？是否只包含 LLM 執行下一個動作所需的最低限度必要資訊？

最後，工具可能會以任何方式導致 JavaScript 失敗。如要排解問題，請調查下列事項：

• 工具程式碼是否能正確處理所有潛在的執行階段錯誤和例外狀況？
• 是否已將錯誤回報給代理程式和模型？
• 工具所依賴的外部 API 或服務是否正常運作？
• 錯誤結構是否夠清楚，讓模型能區分暫時性問題 (重試) 和嚴重失敗？

單獨測試工具

如果代理程式無法判斷要為「我要一份小披薩」這類要求呼叫哪個工具，就無法在複雜的使用者歷程中發揮作用。

您可以先單獨測試工具，在執行瀏覽器模擬之前，先調整結構定義和說明。

提示：您可以觸發 WebMCP 工具呼叫 using navigator.modelContext.executeTool(...)。

評估通話準確度

歡迎參考我們的示範，也就是 WebMCP zaMaker。 當使用者提示「我要小披薩」時，模型回應會指出要使用 "size":"Small" 引數執行 set_pizza_size 呼叫。

expectedCall 函式會定義預期的函式和引數。這種做法可確保代理程式會根據提供的結構定義，選擇正確的工具來支援使用者意圖。

{
  "messages": [
    {
      "role": "user",
      "content": "I'd like a small pizza."
    }
  ],
  "expectedCall": [
    {
      "functionName": "set_pizza_size",
      "arguments": { "size": "Small" }
    }
  ]
}

expectedCall 用於執行以規則為準的確定性測試：

您可以將 WebMCP 工具繫結至元件的生命週期，也就是說，您必須在應用程式狀態符合 WebMCP 預期時進行測試。如要管理這項設定，請提供與您想評估的狀態相關的完整工具清單。舉例來說，使用者與服務專員共同瀏覽網頁時，開啟了 WebMCP zaMaker。

[
...
  {
    "name": "add_topping",
    "description": "Add one or more toppings to the pizza",
    ...
  },
  {
    "name": "set_pizza_size",
    "description": "Set the pizza size directly.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "size": {
          "type": "string",
          "enum": [
            "Small",
            "Medium",
            "Large",
            "Extra Large"
          ],
          "description": "The specific size name."
        },
      }
    }
  },
  {
    "name": "set_pizza_style",
    "description": "Set the style of the pizza (colors/theme)",
  ...
  },
...
]

...
 "expectedCall": [
   {
     "functionName": "set_pizza_size",
     "arguments": { "size": "Small" }
   }
 ]
...

開啟後，WebMCP 會顯示 add_topping、set_pizza_size 和 set_pizza_style 工具。如要準確測試這些個別工具，請納入所有工具，建立模擬的完整狀態。

注意：代理程式可能可以使用其他工具，但您只能評估自己提供的工具。

現在您已瞭解代理程式會視需要呼叫正確的工具，接下來可以測試工具呼叫是否含有正確的參數，以及結果是否符合預期。分為兩個步驟：確定性測試和機率性測試。

執行確定性測試

由於 WebMCP 工具是以 JavaScript 或 HTML 註解建構而成，因此您可以編寫確定性測試，執行下列工作：

• 驗證工具邏輯。
• 確認依附元件是否已正確呼叫。
• 確認使用者介面已如預期更新，以及任何其他刻意產生的副作用。
• 確認傳回的資訊符合預期值。
• 驗證測試參數。

舉例來說，如果工具使用 SearchComponent 函式，您可以傳遞 SearchComponent 的模擬項目進行測試。請記得模擬工具運作的環境，盡可能取得最佳結果。這與您編寫其他 Application Integration 測試時使用的技術相同。

執行機率測試

如要讓模型輸出內容正確呼叫下一個工具，您需要編寫評估。

使用者可能會直接查詢模型，明確要求工具執行特定動作，也可能提出含糊不清的查詢，暗示應使用工具。例如「在我的披薩上加義大利辣香腸」就是直接查詢。「我要在披薩上加所有肉類」則較為模稜兩可，模型必須瞭解需要使用 add_topping 工具，以及哪些配料可定義為肉類。

建立評估資料集時，請同時納入測試基準工具執行的直接查詢，以及測試模型推論和工具選取邏輯的開放式查詢。

舉例來說，如果你經營咖啡店，使用者可以要求代理程式重新訂購上個月的咖啡。請編寫工具來搜尋先前的訂單 OrderHistoryService，以及另一個訂購咖啡的工具。如要測試訂單記錄服務，可以傳送會傳回咖啡產品 ID 的模擬。

在本例中，您會評估模型是否瞭解查詢意圖、選取正確工具，以及該工具是否提供採取行動所需的正確資訊。如果模型未呼叫 get_order_history，就不知道要使用哪個 item_id 執行 order_product。

端對端測試

編寫端對端測試，確保使用者和代理程式可以順利完成歷程。除了測試個別工具，您也要測試多步驟動作是否以正確順序執行。

舉例來說，假設您經營線上服飾店，使用者向服務專員詢問：「我想買一件黑色外套和一條牛仔褲。請提供所用材料的明細。

成功的代理程式歷程可能如下所示：

1. 前往服飾類別。
2. 找出其中一件要求的衣物 (訂單不重要)。
3. 尋找特定項目 (search_clothes)。
4. 取得包含材料清單的產品詳細資料 (get_product_details)。
5. 針對每個要求項目重複執行步驟 2 到 4。

當服務專員來到步驟 2 時，可以先搜尋黑色或牛仔褲，順序並不重要。不過，其餘步驟必須依序完成。

編寫端對端評估，確認代理程式以預期順序呼叫工具：

{
  "messages": [
    {
      "role": "user",
      "content": "I am looking to buy a black jacket and a pair of jeans.
        Could you provide a breakdown of the materials used ?"
    }
  ],
  "expectedCall": [
    {
      "functionName": "navigate_to_category",
      "arguments": { "category": "clothes" }
    },
    {
      "unordered": [
        {
          "ordered": [
            {
              "functionName": "search_clothes",
              "arguments": { "query": "black jacket" }
            },
            {
              "functionName": "get_product_details",
              "arguments": { "productId": "JACKET002" }
            }
          ]
        },
        {
          "ordered": [
            {
              "functionName": "search_clothes",
              "arguments": { "query": "jeans" }
            },
            {
              "functionName": "get_product_details",
              "arguments": { "productId": "JEANS001" }
            }
          ]
        }
      ]
    }
  ]
}

評估中鏈失敗

有時代理必須依序呼叫多個工具。如果工具在這項程序中途發生故障，會怎麼樣？舉例來說，使用者想使用優待券代碼訂購披薩：

「我要一份小份的青醬披薩。使用我的優惠碼「FreePizza」。

代理人可能會在 add_discount_coupon 失敗，然後繼續以全價結帳購買披薩。如要測試 add_discount_coupon 工具，您可以手動執行這一連串的工具呼叫，不必與模型互動，即可模擬這個情境。將應用程式帶到您預期工具會失敗的狀態。在本例中，這是指 start_checkout 工具之後。接著，您就可以單獨評估 add_discount_coupon。

試用 WebMCP

開始實驗，針對工具進行獨立評估，並使用任何與 WebMCP 相容的代理程式，評估啟用 WebMCP 的網站：

• 前往 GitHub 下載實驗性評估工具。
• 請參閱「建立 AI 評估結果」課程。