語言模型工具 API
語言模型工具使您能夠透過特定於領域的 istory 來擴充套件大型語言模型 (LLM) 的功能。為了處理使用者的聊天提示，VS Code 中的代理可以自動呼叫這些工具來在對話中執行專門的任務。
透過在您的 VS Code 擴充套件中貢獻一個語言模型工具，您可以擴充套件代理式編碼工作流，同時還提供與編輯器的深度整合。擴充套件工具是 VS Code 中可用的三種工具型別之一，另外還有內建工具和 MCP 工具。
在本擴充套件指南中，您將學習如何使用語言模型工具 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用於在擴充套件實現程式碼中引用工具的工具的唯一名稱。將名稱格式化為 {verb}_{noun}。請參閱命名指南。displayName使用者友好的工具名稱，用於在 UI 中顯示。 -
如果該工具可以與代理一起使用，或者可以使用
#在聊天提示中引用，請新增以下屬性使用者可以在聊天檢視中啟用或停用該工具，方式與模型上下文協議 (MCP) 工具類似。
屬性 描述 canBeReferencedInPrompt如果該工具可以與代理一起使用或在聊天中引用，則將其設定為 true。toolReferenceName使用者透過 #在聊天提示中引用該工具的名稱。icon將在 UI 中顯示的工具圖示。 userDescription使用者友好的工具描述，用於在 UI 中顯示。 -
在
modelDescription中新增詳細描述。LLM 使用此資訊來確定應在何種上下文中使用您的工具。- 該工具具體做什麼？
- 它返回什麼型別的資訊？
- 何時應使用它，何時不應使用？
- 描述工具的重要限制或約束。
-
如果工具需要輸入引數，請新增
inputSchema屬性來描述工具的輸入引數。此 JSON schema 描述了一個物件，其中包含工具作為輸入接收的屬性以及它們是否必需。檔案路徑應為絕對路徑。
描述每個引數的作用以及它與工具功能的聯絡。
-
新增一個
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 schema 進行驗證。以下示例顯示了選項卡計數工具的介面。
export interface ITabCountParameters { tabGroup?: number; } -
實現
invoke方法。當在處理聊天提示時呼叫語言模型工具時，將呼叫此方法。invoke方法在options引數中接收工具輸入引數。這些引數將根據package.json的inputSchema中定義的 JSON schema 進行驗證。發生錯誤時，請丟擲一條對 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 提供提示、聊天上下文和要考慮的工具定義列表。
LLM 生成響應，其中可能包含一個或多個呼叫工具的請求。
-
如果需要，Copilot 將使用 LLM 提供的引數值呼叫建議的工具。
工具響應可能會導致更多工具呼叫的請求。
-
如果存在錯誤或後續工具請求，Copilot 將在工具呼叫流程中進行迭代，直到所有工具請求都得到解決。
-
Copilot 將最終響應返回給使用者，其中可能包含來自多個工具的響應。
指南和約定
-
命名：為工具和引數編寫清晰且描述性的名稱。
-
工具名稱：應是唯一的，並清晰地描述其意圖。將工具名稱格式化為
{verb}_{noun}。例如，get_weather、get_azure_deployment或get_terminal_output。 -
引數名稱：應描述引數的用途。將引數名稱格式化為
{noun}。例如，destination_location、ticker或file_name。
-
-
描述：為工具和引數編寫詳細的描述。
- 描述工具的作用以及何時應使用它，何時不應使用。例如，“此工具檢索給定位置的天氣。”
- 描述每個引數的作用以及它與工具功能的聯絡。例如，“
destination_location引數指定要檢索天氣的位置。它應為有效的地點名稱或座標。” - 描述工具的重要限制或約束。例如，“此工具僅檢索美國境內的天氣資料。對於其他地區可能不起作用。”
-
使用者確認：為工具呼叫提供確認訊息。始終會顯示一個通用的確認對話方塊，用於擴充套件中的工具，但工具可以自定義確認訊息。為使用者提供足夠的資訊以瞭解工具正在做什麼。
-
錯誤處理：發生錯誤時，請丟擲一條對 LLM 有意義的錯誤訊息。或者，提供有關 LLM 接下來應該做什麼的說明，例如使用不同的引數重試，或執行不同的操作。
在此處獲取建立工具的更多最佳實踐，請參閱OpenAI 文件和Anthropic 文件。