🚀 在 VS Code 中！

LanguageModelTool API

語言模型工具可讓您擴充大型語言模型 (LLM) 的功能。VS Code 會在 Copilot 代理人模式中顯示由擴充功能貢獻的工具。藉由在 VS Code 擴充功能中貢獻工具，您可以將代理人編碼的強大功能與透過其擴充功能 API 進行的深度 VS Code 整合結合。

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

LLM 中的工具呼叫是什麼？

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

LLM 實際上從未執行工具本身，而是 LLM 產生用於呼叫工具的參數。務必清楚描述工具的用途、功能和輸入參數，以便在正確的內容中叫用該工具。

請參閱 OpenAI 文件，深入瞭解 函式呼叫。

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

藉由在您的擴充功能中實作語言模型工具，您可以

  • 使用特殊工具擴充代理人模式，這些工具會自動叫用，做為回應使用者提示的一部分。例如，在聊天對話中啟用資料庫基架和查詢。
  • 透過使用廣泛的擴充功能 API，與 VS Code 深度整合。例如，使用偵錯 API來擴增使用者的偵錯體驗。

建立語言模型工具

您可以建立執行特定工作的工具，例如從資料庫擷取資訊、尋找檔案或執行計算。

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

  1. 在擴充功能的 package.json 檔案中定義工具的組態。
  2. 在擴充功能程式碼中實作工具。

package.json 中的靜態組態

工具的靜態組態是在擴充功能的 package.json 檔案中定義。這包括工具名稱、描述、輸入結構描述和其他中繼資料。

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

  2. 為工具指定唯一名稱

    屬性 描述
    name 工具的唯一名稱，用於在擴充功能實作程式碼中參考該工具。以 {動詞}_{名詞} 格式格式化名稱。請參閱命名指南。
    displayName 工具的使用者友善名稱，用於在 UI 中顯示。

  3. 如果工具可以在代理人模式中使用或在聊天提示中參考，請新增下列屬性

    使用者可以在「聊天」檢視中啟用或停用工具，類似於模型內容通訊協定 (MCP) 工具的做法。

    屬性 描述
    canBeReferencedInPrompt 如果工具可以在代理人模式中使用或在聊天中參考，則設定為 true。
    toolReferenceName 使用者在聊天提示中透過 # 參考工具的名稱。
    icon 要在 UI 中為工具顯示的圖示。
    userDescription 工具的使用者友善描述，用於在 UI 中顯示。

  4. 在 modelDescription 中新增詳細描述

    • 工具究竟有什麼作用？
    • 它會傳回哪種資訊？
    • 何時應該以及不應該使用它？
    • 描述工具的重要限制或約束。

  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
                    }
                }
            }
        }
    ]
}

工具實作

  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. 定義一個介面，描述工具輸入參數。

    該介面用於 invoke 方法中。輸入參數會根據 package.json 中 inutSchema 中定義的 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 將最終回應傳回給使用者，其中可能包含來自多個工具的回應。

下圖顯示 Copilot 工具呼叫流程。

Diagram that shows the Copilot tool-calling flow

開始使用

指南

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

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

    • 參數名稱：應描述參數的用途。以 {名詞} 格式組織參數名稱。例如，destination_location、ticker 或 file_name。

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

    • 描述工具的作用，以及何時應該和不應該使用它。例如，「此工具會擷取指定位置的天氣。」
    • 描述每個參數的作用及其與工具功能的關係。例如，「destination_location 參數指定要擷取天氣的位置。它應該是有效的位置名稱或座標。」
    • 描述工具的重要限制或約束。例如，「此工具僅擷取美國位置的天氣資料。它可能不適用於其他地區。」

  • 使用者確認：為工具叫用提供確認訊息。一般確認對話方塊一律會針對來自擴充功能的工具顯示，但工具可以自訂確認訊息。為使用者提供足夠的內容，以瞭解工具的作用。

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

在 OpenAI 文件和 Anthropic 文件中取得更多建立工具的最佳做法。

相關內容

04/03/2025