语言模型工具 API
语言模型工具使您能够在聊天中通过特定领域的功能扩展大型语言模型（LLM）的功能。为了处理用户的聊天提示，Agent可以在VS Code中自动调用这些工具来执行专门的任务，作为对话的一部分。
通过在 VS Code 扩展中贡献一个语言模型工具，您可以在扩展的编码工作流程中增加代理性，同时提供与编辑器的深度集成。扩展工具是 VS Code 中可用的三种类型工具之一，另外两种是内置工具和 MCP 工具。
在本扩展指南中，您将学习如何使用语言模型工具 API 创建语言模型工具，以及如何在聊天扩展中实现工具调用。
您还可以通过贡献一个MCP服务器来扩展聊天体验，使用专用工具。 有关不同选项的详细信息以及如何选择要使用的这种方法，请参阅AI可扩展性概述。
有关终端用户使用工具的信息，请参见在聊天中使用工具.
在LLM中，工具调用是什么？
语言模型工具是一种可以作为语言模型请求的一部分调用的功能。例如，你可能有一个从数据库检索信息、进行一些计算或调用在线API的函数。当你在VS Code扩展中贡献一个工具时，代理模式可以根据对话的上下文调用该工具。
LLM实际上从不执行工具本身，而是生成用于调用工具的参数。清楚地描述工具的目的、功能和输入参数非常重要，以便在正确的上下文中调用工具。
以下图表显示了 VS Code 中代理模式下工具调用的流程。请参阅 工具调用流程 以了解具体步骤的详细信息。
阅读更多关于函数调用的内容，请参阅OpenAI文档。
为什么在你的扩展中实现一个语言模型工具？
在您的扩展中实现语言模型工具具有以下几点好处：
- 扩展代理模式，使用专门的、领域特定的工具，这些工具在响应用户提示时自动调用。例如，启用数据库 scaffolding 和查询，以动态地为 LLM 提供相关上下文。
- 深度集成到VS Code，通过使用广泛的扩展API。例如，使用调试API获取当前调试上下文并将其作为工具功能的一部分使用。
- 分发和部署工具通过Visual Studio Marketplace，为用户提供了可靠且无缝的体验。用户不需要为您的工具进行单独的安装和更新过程。
您可能需要在以下场景中考虑实现一个带有MCP服务器的语言模型工具：
- 你已经有一个MCP服务器实现，并且也想在VS Code中使用它。
- 您希望在不同的开发环境和平台上重复使用相同的工具。
- 您的工具作为服务远程托管。
- 您不需要访问 VS Code API。
了解更多关于工具类型之间的差异。
创建语言模型工具
实现语言模型工具包括两个主要部分：
- 定义工具的配置
package.json您的扩展文件。 - 在你的扩展代码中使用语言模型 API 参考来实现该工具
你可以通过一个基本示例项目开始。
1. 静态配置在package.json
定义扩展中语言模型工具的第一步是将其定义在package.json您的扩展文件。此配置包括工具名称、描述、输入模式和其他元数据：
-
在工具中添加一个条目
贡献语言模型工具您扩展的章节package.json文件。 -
给工具起一个独特的名字：
财产 描述 名字工具的唯一名称，用于在扩展实现代码中引用该工具。将名称格式化为格式 动词_名词。请参阅命名指南。显示名称该工具在用户界面中显示的用户友好名称。 -
如果该工具可以与智能体一起使用或在聊天提示中引用
#，添加以下属性：用户可以在聊天视图中启用或禁用该工具，类似于模型上下文协议（MCP）工具的启用或禁用方式。
财产 描述 可以在提示中引用设置为 真如果该工具可以与 智能体 或在聊天中提及。工具参考名称用户在聊天提示中通过引用该工具的名称 #输入：.图标在用户界面中显示该工具的图标。 用户描述用户友好型工具描述，用于在用户界面中显示。 -
添加详细描述
模型描述此信息将被LLM用于确定您的工具应在何种上下文中使用。- 这个工具具体是做什么的？
- 它返回什么信息？
- 何时该使用，何时不该使用？
- 描述工具的重要限制或约束。
-
如果该工具需要输入参数，请添加一个
输入模式描述工具输入参数的属性。此JSON模式描述了工具作为输入所具有的属性及其是否为必需。文件路径应为绝对路径。
描述每个参数的作用以及它如何与工具的功能相关。
-
添加一个
当控制工具可用性的条款。该
语言模型工具贡献点允许您限制工具在代理模式下何时可用，或在提示中使用进行引用。例如，获取调试调用堆栈信息的工具，应在用户调试时才可用。when子句"贡献": { "语言模型工具": [ { "名称": "聊天工具样本_标签计数", ... "条件": "调试状态 == '运行'"" } ] }
示例工具定义
以下示例展示了如何定义一个工具来计算标签组中活动标签的数量。
"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输入：.如果你希望该工具仅对你扩展中的用户可见，请跳过工具注册步骤。
导出 函数 registerChatTools(上下文: vscode.ExtensionContext) { 上下文.subscriptions.push( vscode.lm.registerTool('chat-tools-sample_tabCount', new TabCountTool()) ); } -
创建一个实现该类的
vscode.语言模型工具<>接口。 -
添加工具确认信息
准备调用方法。对于来自扩展的工具，将始终显示一个通用的确认对话框，但工具可以自定义确认消息。给用户提供足够的上下文，使用户了解工具正在做什么。消息可以是一个
Markdown字符串包含一个代码块。以下示例展示了如何为标签计数工具提供确认消息。
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 !== 未定义 ? 在标签组中 ${选项.输入.标签组}`` : '') ), }; return { invocationMessage: 'Counting the number of tabs', confirmationMessages, }; }如果
准备调用返回未定义, 通用确认消息将显示。请注意，用户也可以选择“始终允许”某个工具。 -
定义一个接口，描述工具输入参数。
该界面用于
调用方法vscode.语言模型工具类。输入参数会根据您在JSON模式中定义的进行验证输入模式在package.json输入：.以下示例显示了标签计数工具的界面。
导出 接口 ITabCountParameters { tabGroup?: number; } -
实施
调用方法。当在处理聊天提示时调用语言模型工具时，会调用此方法。该
调用方法接收工具输入参数选项参数。参数根据在中定义的JSON模式进行验证输入模式在package.json输入：.当发生错误时，抛出一个对LLM有意义的错误消息。可选地，提供LLM接下来应执行的说明，例如使用不同的参数重试，或执行不同的操作。
以下示例展示了标签计数工具的实现。工具的结果是类型的一个实例
vscode.语言模型工具结果输入：.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.语言模型工具结果([新的 vscode.语言模型文本部分(有 _${组.Tab.长度} 个标签打开。)]); } }
查看在VS Code扩展示例库中实现语言模型工具的完整源代码。
工具调用流程
当用户发送聊天提示时，会发生以下步骤：
-
Copilot根据用户的配置确定可用工具的列表。
工具列表包括内置工具、通过扩展注册的工具以及来自MCP服务器的工具。您可以通过扩展或MCP服务器（图中显示为绿色）贡献到代理模式中。
-
Copilot将请求发送到LLM，并为其提供提示、聊天上下文和需要考虑的工具定义列表。
LLM生成一个响应，响应中可能包含一个或多个调用工具的请求。
-
如果需要， Copilot 调用 LLM 提供参数值的建议工具。
工具响应可能会导致更多工具调用请求。
-
如果有错误或后续工具请求， Copilot将循环执行工具调用流程，直到所有工具请求都得到解决。
-
Copilot将最终回复返回给用户，回复可能包含多个工具的响应。
指南和约定
-
命名：为工具和参数编写清晰和描述性的名称。
-
工具名称：应唯一，并清楚地描述其用途。工具名称的格式应为
动词_名词例如，获取天气，获取Azure部署，或获取终端输出输入：. -
参数名称：应描述参数的目的。参数名称的格式应为
{名词}例如，目的地位置，股票代码，或文件名输入：.
-
-
描述：为工具和参数编写详细描述。
- 描述该工具的作用以及何时该使用和不该使用。例如，“这个工具可以获取给定位置的天气。”
- 描述每个参数的作用及其与工具功能的关系。例如，“The
目的地位置参数指定要获取天气的位置。它应该是一个有效的地点名称或坐标。 - 描述工具的重要限制或约束。例如，“此工具仅获取美国地区的天气数据。它可能无法在其他地区使用。”
-
用户确认：为工具调用提供确认消息。对于来自扩展的工具，将始终显示通用确认对话框，但工具可以自定义确认消息。给用户提供足够的上下文，使用户了解工具在做什么。
-
错误处理：当发生错误时，抛出一个对LLM有意义的错误消息。可选地，提供LLM应采取的下一步操作说明，例如使用不同的参数重试，或执行不同的操作。
在 OpenAI 文档 和 Anthropic 文档 中获取更多关于创建工具的最佳实践。