💻 歡迎參加 6 月 3 日舉行的 MS Build 之 VS Code 直播活動。

語言模型工具 API

語言模型工具讓您可以擴充大型語言模型 (LLM) 在對話中的功能，使其具備特定領域的能力。為了處理使用者的對話提示，VS Code 中的代理程式 (Agents) 可以自動呼叫這些工具，作為對話的一部分來執行專業任務。

透過在您的 VS Code 擴充功能中貢獻語言模型工具，您可以擴充代理程式化編碼工作流程，同時與編輯器進行深度整合。擴充功能工具是 VS Code 中提供的三種工具類型之一，另外兩種為內建工具與 MCP 工具。

在本擴充功能指南中，您將學習如何使用語言模型工具 API 建立語言模型工具，以及如何在聊天擴充功能中實作工具呼叫。

您也可以透過貢獻 MCP 伺服器，利用專業工具來擴充聊天體驗。請參閱 AI 可擴充性概觀，以了解不同選項的詳細資訊以及如何決定使用哪種方法。

提示

有關終端使用者如何使用工具的資訊，請參閱在聊天中使用工具。

LLM 中的工具呼叫是什麼？

語言模型工具是一種可以作為語言模型請求一部分來呼叫的函式。例如，您可能有一個從資料庫擷取資訊、執行運算或呼叫線上 API 的函式。當您在 VS Code 擴充功能中貢獻工具時，代理程式模式就能根據對話內容呼叫該工具。

LLM 本身實際上並不會執行工具，而是由 LLM 產生用於呼叫您工具的參數。清楚描述工具的用途、功能和輸入參數非常重要，這樣工具才能在正確的上下文中被呼叫。

下圖顯示了 VS Code 代理程式模式中的工具呼叫流程。有關所涉及步驟的詳細資訊，請參閱工具呼叫流程。

Diagram that shows the Copilot tool-calling flow

閱讀更多關於 OpenAI 文件中函式呼叫 (function calling) 的資訊。

為什麼要在您的擴充功能中實作語言模型工具？

在擴充功能中實作語言模型工具具有多項好處：

  • 擴充代理程式模式：使用專業、特定領域的工具，這些工具會在回應使用者提示時自動呼叫。例如，啟用資料庫構建與查詢，以便動態地為 LLM 提供相關內容。
  • 與 VS Code 深度整合：透過使用廣泛的擴充功能 API。例如，使用偵錯 API 取得目前的偵錯內容，並將其作為工具功能的一部分。
  • 散佈與部署：透過 Visual Studio Marketplace 發布工具，為使用者提供可靠且無縫的體驗。使用者不需要為您的工具進行額外的安裝與更新流程。

在下列情況下，您可以考慮使用 MCP 伺服器來實作語言模型工具：

  • 您已經擁有 MCP 伺服器實作，並希望在 VS Code 中使用它。
  • 您希望在不同的開發環境與平台之間重複使用相同的工具。
  • 您的工具是以遠端服務方式託管。
  • 您不需要存取 VS Code API。

深入了解各類工具之間的差異。

建立語言模型工具

實作語言模型工具包含兩個主要部分：

  1. 在擴充功能的 package.json 檔案中定義工具的設定。
  2. 使用 Language Model API 參考在您的擴充功能程式碼中實作工具。

您可以從一個基礎範例專案開始。

1. package.json 中的靜態設定

在擴充功能中定義語言模型工具的第一步，是在 package.json 檔案中進行定義。此設定包含工具名稱、描述、輸入架構以及其他詮釋資料。

  1. 在擴充功能的 package.json 檔案的 contributes.languageModelTools 區段中，為您的工具新增一個項目。

  2. 為工具命名一個唯一的名稱

    屬性 說明
    name 工具的唯一名稱，用於在擴充功能實作程式碼中參照該工具。名稱格式請使用 {動詞}_{名詞}。請參閱命名規範。
    displayName 工具的使用者友好名稱，用於在 UI 中顯示。

  3. 如果該工具可以與代理程式一起使用，或是在聊天提示中以 # 參照，請新增以下屬性：

    使用者可以在聊天視圖中啟用或停用該工具，方式與模型內容協定 (MCP) 工具類似。

    屬性 說明
    canBeReferencedInPrompt 如果該工具可以與代理程式一起使用或在聊天中參照，請設為 true。
    toolReferenceName 供使用者在聊天提示中透過 # 參照該工具的名稱。
    icon 要在 UI 中顯示的工具圖示。
    userDescription 工具的使用者友好描述，用於在 UI 中顯示。

  4. 在 modelDescription 中新增詳細說明。LLM 會使用此資訊來判斷應在何種情境下使用您的工具。

    • 此工具確切的功能為何？
    • 它會回傳哪種類型的資訊？
    • 何時應該使用，何時不該使用？
    • 描述該工具的重要限制或約束。

  5. 如果工具需要輸入參數，請新增一個 inputSchema 屬性來描述工具的輸入參數。

    此 JSON 架構描述了一個包含工具輸入屬性的物件，以及它們是否為必要欄位。檔案路徑應為絕對路徑。

    描述每個參數的作用，以及它與工具功能之間的關聯。

  6. 新增 when 子句來控制工具的可用時機。

    languageModelTools 貢獻點讓您可以使用 when 子句來限制工具在代理程式模式下的可用時間，或限制其是否能在提示中被參照。例如，取得偵錯呼叫堆疊資訊的工具，應僅在使用者進行偵錯時才可用。

    "contributes": {
    "languageModelTools": [
        {
            "name": "chat-tools-sample_tabCount",
            ...
            "when": "debugState == 'running'"
        }
    ]
}
工具定義範例

以下範例顯示如何定義一個計算分頁群組中有效分頁數量的工具。

"contributes": {
    "languageModelTools": [
        {
            "name": "chat-tools-sample_tabCount",
            "tags": [
                "editors",
                "chat-tools-sample"
            ],
            "toolReferenceName": "tabCount",
            "displayName": "Tab Count",
            "modelDescription": "The number of active tabs in a tab group in VS Code.",
            "userDescription": "Count the number of active tabs in a tab group.",
            "canBeReferencedInPrompt": true,
            "icon": "$(files)",
            "inputSchema": {
                "type": "object",
                "properties": {
                    "tabGroup": {
                        "type": "number",
                        "description": "The index of the tab group to check. This is optional- if not specified, the active tab group will be checked.",
                        "default": 0
                    }
                }
            }
        }
    ]
}

2. 工具實作

使用 Language Model API 實作語言模型工具。這包含以下步驟：

  1. 在擴充功能啟用時，使用 vscode.lm.registerTool 註冊該工具。

    提供您在 package.json 的 name 屬性中指定的工具名稱。

    如果您希望該工具僅供您的擴充功能私有使用，請跳過工具註冊步驟。

    export function registerChatTools(context: vscode.ExtensionContext) {
  context.subscriptions.push(
    vscode.lm.registerTool('chat-tools-sample_tabCount', new TabCountTool())
  );
}

  2. 建立一個類別來實作 vscode.LanguageModelTool<> 介面。

  3. 在 prepareInvocation 方法中新增工具確認訊息。

    來自擴充功能的工具將永遠顯示通用的確認對話框，但工具可以自訂確認訊息。為使用者提供足夠的背景資訊，讓他們了解工具正在執行什麼操作。訊息可以是一個包含程式碼區塊的 MarkdownString。

    以下範例顯示如何為分頁計數工具提供確認訊息。

    async prepareInvocation(
    options: vscode.LanguageModelToolInvocationPrepareOptions<ITabCountParameters>,
    _token: vscode.CancellationToken
) {
    const confirmationMessages = {
        title: 'Count the number of open tabs',
        message: new vscode.MarkdownString(
            `Count the number of open tabs?` +
            (options.input.tabGroup !== undefined
                ? ` in tab group ${options.input.tabGroup}`
                : '')
        ),
    };

    return {
        invocationMessage: 'Counting the number of tabs',
        confirmationMessages,
    };
}

    如果 prepareInvocation 回傳 undefined，將會顯示通用的確認訊息。請注意，使用者也可以選擇「永遠允許」特定工具。

  4. 定義一個描述工具輸入參數的介面。

    該介面會在 vscode.LanguageModelTool 類別的 invoke 方法中使用。輸入參數會根據您在 package.json 的 inputSchema 中定義的 JSON 架構進行驗證。

    以下範例顯示了分頁計數工具的介面。

    export interface ITabCountParameters {
  tabGroup?: number;
}

  5. 實作 invoke 方法。當處理聊天提示時呼叫語言模型工具，就會執行此方法。

    invoke 方法會在 options 參數中接收工具輸入參數。這些參數會根據 package.json 中 inputSchema 定義的 JSON 架構進行驗證。

    當發生錯誤時，拋出一個對 LLM 有意義的錯誤訊息。您可以選擇性地提供關於 LLM 接下來該做什麼的指示，例如使用不同的參數重試，或是執行其他動作。

    以下範例顯示了分頁計數工具的實作。工具的結果是 vscode.LanguageModelToolResult 類型的執行個體。

    async invoke(
    options: vscode.LanguageModelToolInvocationOptions<ITabCountParameters>,
    _token: vscode.CancellationToken
) {
    const params = options.input;
    if (typeof params.tabGroup === 'number') {
        const group = vscode.window.tabGroups.all[Math.max(params.tabGroup - 1, 0)];
        const nth =
            params.tabGroup === 1
                ? '1st'
                : params.tabGroup === 2
                    ? '2nd'
                    : params.tabGroup === 3
                        ? '3rd'
                        : `${params.tabGroup}th`;
        return new vscode.LanguageModelToolResult([new vscode.LanguageModelTextPart(`There are ${group.tabs.length} tabs open in the ${nth} tab group.`)]);
    } else {
        const group = vscode.window.tabGroups.activeTabGroup;
        return new vscode.LanguageModelToolResult([new vscode.LanguageModelTextPart(`There are ${group.tabs.length} tabs open.`)]);
    }
}

在 VS Code 擴充功能範例儲存庫中檢視語言模型工具的完整原始碼。

工具呼叫流程

當使用者傳送聊天提示時，會發生以下步驟：

  1. Copilot 根據使用者的設定決定可用工具列表。

    工具列表包含內建工具、擴充功能註冊的工具，以及來自 MCP 伺服器的工具。您可以透過擴充功能或 MCP 伺服器貢獻代理程式模式（如圖中綠色所示）。

  2. Copilot 將請求發送給 LLM，並提供提示、聊天內容以及要考慮的工具定義列表。

    LLM 產生回應，其中可能包含一個或多個呼叫工具的請求。

  3. 如有需要，Copilot 會使用 LLM 提供的參數值呼叫建議的工具。

    工具回應可能會導致更多的工具呼叫請求。

  4. 如果存在錯誤或後續的工具請求，Copilot 會反覆執行工具呼叫流程，直到所有工具請求都已解析。

  5. Copilot 將最終回應回傳給使用者，其中可能包含來自多個工具的回應。

規範與約定

  • 命名：為工具和參數編寫清晰且具描述性的名稱。

    • 工具名稱：應為唯一，並清楚描述其意圖。工具名稱結構請採用 {動詞}_{名詞} 格式。例如：get_weather、get_azure_deployment 或 get_terminal_output。

    • 參數名稱：應描述參數的用途。參數名稱結構請採用 {名詞} 格式。例如：destination_location、ticker 或 file_name。

  • 描述：為工具和參數編寫詳細的描述。

    • 描述工具的功能以及何時該使用或不該使用。例如：「此工具可擷取指定地點的天氣資訊。」
    • 描述每個參數的作用，以及它與工具功能之間的關聯。例如：「destination_location 參數指定要擷取天氣的地點。它應該是一個有效的地點名稱或座標。」
    • 描述工具的重要限制或約束。例如：「此工具僅能擷取美國境內地點的天氣資料，對於其他地區可能無法運作。」

  • 使用者確認：為工具呼叫提供確認訊息。來自擴充功能的工具將永遠顯示通用的確認對話框，但工具可以自訂確認訊息。為使用者提供足夠的背景資訊，讓他們了解工具正在執行什麼操作。

  • 錯誤處理：當發生錯誤時，拋出一個對 LLM 有意義的錯誤訊息。您可以選擇性地提供關於 LLM 接下來該做什麼的指示，例如使用不同的參數重試，或是執行其他動作。

從 OpenAI 文件和 Anthropic 文件中取得更多建立工具的最佳實踐。

相關內容

5/28/2026
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.