語言模型工具 API
語言模型工具使您能夠透過特定領域的功能擴充套件大型語言模型 (LLM) 在聊天中的功能。為了處理使用者的聊天提示，VS Code 中的代理模式可以自動呼叫這些工具，作為對話的一部分執行專門任務。透過在 VS Code 擴充套件中貢獻語言模型工具，您可以擴充套件代理編碼工作流，同時還提供與編輯器的深度整合。
在本擴充套件指南中，您將學習如何使用語言模型工具 API 建立語言模型工具，以及如何在聊天擴充套件中實現工具呼叫。
您還可以透過貢獻 MCP 伺服器來使用專門工具擴充套件聊天體驗。有關不同選項以及如何決定使用哪種方法的詳細資訊，請參閱AI 擴充套件性概述。
LLM 中的工具呼叫是什麼？
語言模型工具是一個可以在語言模型請求中呼叫的函式。例如，您可能有一個從資料庫檢索資訊、執行某些計算或呼叫線上 API 的函式。當您在 VS Code 擴充套件中貢獻一個工具時，代理模式可以根據對話的上下文呼叫該工具。
LLM 實際上從不執行工具本身，而是生成用於呼叫您的工具的引數。清楚地描述工具的用途、功能和輸入引數非常重要，以便可以在正確的上下文中呼叫該工具。
下圖顯示了 VS Code 代理模式下的工具呼叫流程。有關涉及的具體步驟的詳細資訊，請參閱工具呼叫流程。
在 OpenAI 文件中閱讀有關函式呼叫的更多資訊。
為什麼要在擴充套件中實現語言模型工具？
在擴充套件中實現語言模型工具具有以下幾個優點：
- 擴充套件代理模式，使用專門的、特定領域工具，這些工具作為響應使用者提示的一部分自動呼叫。例如，啟用資料庫腳手架和查詢，以動態地為 LLM 提供相關上下文。
- 透過使用廣泛的擴充套件 API 與 VS Code 深度整合。例如，使用除錯 API 獲取當前除錯上下文並將其用作工具功能的一部分。
- 透過 Visual Studio Marketplace 分發和部署工具，為使用者提供可靠、無縫的體驗。使用者無需為您的工具進行單獨的安裝和更新過程。
在以下場景中，您可以考慮使用MCP 伺服器實現語言模型工具：
- 您已經有一個 MCP 伺服器實現，並且也想在 VS Code 中使用它。
- 您希望在不同的開發環境和平臺中重用相同的工具。
- 您的工具作為服務遠端託管。
- 您不需要訪問 VS Code API。
建立語言模型工具
實現語言模型工具主要包括兩個部分：
- 在擴充套件的
package.json檔案中定義工具的配置。 - 使用語言模型 API 參考在擴充套件程式碼中實現工具。
您可以從基本示例專案開始。
1. package.json 中的靜態配置
在擴充套件中定義語言模型工具的第一步是在擴充套件的 package.json 檔案中定義它。此配置包括工具名稱、描述、輸入模式和其他元資料：
-
在擴充套件的
package.json檔案的contributes.languageModelTools部分中為您的工具新增一個條目。 -
給工具一個唯一的名稱
屬性 描述 name工具的唯一名稱，用於在擴充套件實現程式碼中引用工具。將名稱格式化為 {動詞}_{名詞}格式。請參閱命名指南。displayName工具的使用者友好名稱，用於在 UI 中顯示。 -
如果工具可以在代理模式中使用或在聊天提示中用
#引用，請新增以下屬性：使用者可以在聊天檢視中啟用或停用該工具，類似於模型上下文協議 (MCP) 工具的操作方式。
屬性 描述 canBeReferencedInPrompt如果工具可以在代理模式中使用或在聊天中引用，則設定為 true。toolReferenceName使用者透過 #在聊天提示中引用工具的名稱。icon在 UI 中為工具顯示的圖示。 userDescription工具的使用者友好描述，用於在 UI 中顯示。 -
在
modelDescription中新增詳細描述。LLM 使用此資訊來確定在何種情況下應使用您的工具。- 工具具體做什麼？
- 它返回什麼型別的資訊？
- 何時應該使用，何時不應該使用？
- 描述工具的重要限制或約束。
-
如果工具接受輸入引數，請新增一個
inputSchema屬性，描述工具的輸入引數。此 JSON 模式描述了一個物件，其中包含工具作為輸入接受的屬性，以及它們是否必需。檔案路徑應為絕對路徑。
描述每個引數的作用以及它與工具功能的關係。
-
新增
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. 工具實現
使用語言模型 API 實現語言模型工具。這包括以下步驟：
-
在擴充套件啟用時，使用
vscode.lm.registerTool註冊工具。提供您在
package.json的name屬性中指定的工具名稱。如果您希望工具對您的擴充套件是私有的，請跳過工具註冊步驟。
export function registerChatTools(context: vscode.ExtensionContext) { context.subscriptions.push( vscode.lm.registerTool('chat-tools-sample_tabCount', new TabCountTool()) ); } -
建立一個實現
vscode.LanguageModelTool<>介面的類。 -
在
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，則將顯示通用確認訊息。請注意，使用者還可以選擇“始終允許”某個工具。 -
定義一個描述工具輸入引數的介面。
該介面在
vscode.LanguageModelTool類的invoke方法中使用。輸入引數根據您在package.json的inputSchema中定義的 JSON 模式進行驗證。以下示例顯示了選項卡計數工具的介面。
export interface ITabCountParameters { tabGroup?: number; } -
實現
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 擴充套件示例倉庫中檢視實現語言模型工具的完整原始碼。
工具呼叫流程
當用戶傳送聊天提示時，會發生以下步驟：
-
Copilot 根據使用者配置確定可用工具列表。
工具列表包括內建工具、擴充套件註冊的工具以及來自MCP 伺服器的工具。您可以透過擴充套件或 MCP 伺服器（圖中標綠部分）為代理模式做出貢獻。
-
Copilot 將請求傳送到 LLM，並向其提供提示、聊天上下文以及要考慮的工具定義列表。
LLM 生成響應，其中可能包括一個或多個呼叫工具的請求。
-
如果需要，Copilot 使用 LLM 提供的引數值呼叫建議的工具。
工具響應可能會導致更多的工具呼叫請求。
-
如果存在錯誤或後續工具請求，Copilot 會迭代工具呼叫流程，直到所有工具請求都得到解決。
-
Copilot 向用戶返回最終響應，其中可能包括來自多個工具的響應。
指南和約定
-
命名：為工具和引數編寫清晰和描述性的名稱。
-
工具名稱：應唯一，並清楚地描述其意圖。將工具名稱結構化為
{動詞}_{名詞}格式。例如，get_weather、get_azure_deployment或get_terminal_output。 -
引數名稱：應描述引數的用途。將引數名稱結構化為
{名詞}格式。例如，destination_location、ticker或file_name。
-
-
描述：為工具和引數編寫詳細描述。
- 描述工具的作用以及何時應該使用和不應該使用它。例如，“此工具檢索給定位置的天氣。”
- 描述每個引數的作用以及它與工具功能的關係。例如，“
destination_location引數指定要檢索天氣的位置。它應該是一個有效的地點名稱或座標。” - 描述工具的重要限制或約束。例如，“此工具僅檢索美國境內位置的天氣資料。它可能不適用於其他地區。”
-
使用者確認：為工具呼叫提供確認訊息。對於來自擴充套件的工具，將始終顯示通用確認對話方塊，但工具可以自定義確認訊息。向用戶提供足夠的上下文以瞭解工具正在做什麼。
-
錯誤處理：當發生錯誤時，丟擲一個對 LLM 有意義的訊息的錯誤。可選地，提供 LLM 接下來應該做什麼的說明，例如使用不同的引數重試，或執行不同的操作。
在 OpenAI 文件和Anthropic 文件中獲取更多建立工具的最佳實踐。