在 VS Code 中尝试 ！

LanguageModelTool API

语言模型工具使你能够扩展大型语言模型 (LLM) 的功能。VS Code 在 Copilot 代理模式下展示扩展贡献的工具。通过在 VS Code 扩展中贡献工具，可以将代理编程的力量与通过 VS Code 扩展 API 实现的深度 VS Code 集成相结合。

在此扩展指南中，你将学习如何创建语言模型工具以及如何在聊天扩展中实现工具调用。

大型语言模型 (LLM) 中的工具调用是什么？

语言模型工具是一个函数，可以作为语言模型请求的一部分被调用。例如，你可能有一个从数据库检索信息、执行一些计算或调用一些在线 API 的函数。当你在 VS Code 扩展中贡献一个工具时，代理模式就可以根据对话的上下文来调用该工具。

LLM 实际上从未执行工具本身，而是生成用于调用你的工具的参数。重要的是要清晰地描述工具的目的、功能和输入参数，以便工具能在正确的上下文被调用。

在 OpenAI 文档中阅读有关函数调用的更多信息。

为什么要在扩展中实现语言模型工具？

通过在你的扩展中实现语言模型工具，你可以

  • 扩展代理模式：通过专门的工具扩展代理模式，这些工具会自动作为响应用户提示的一部分被调用。例如，将数据库支架搭建和查询作为聊天对话的一部分。
  • 扩展询问和编辑模式：通过专门的工具扩展询问和编辑模式，用户可以使用 # 在聊天提示中直接引用这些工具。例如，用于从网络获取内容。
  • 与 VS Code 深度集成：通过使用广泛的扩展 API 与 VS Code 深度集成。例如，使用调试 API 来增强用户的调试体验。

创建语言模型工具

你可以创建一个执行特定任务的工具，例如从数据库检索信息、查找文件或执行计算。

实现语言模型工具主要包括两个部分

  1. 在扩展的 package.json 文件中定义工具的配置。
  2. 在扩展代码中实现工具。

package.json 中的静态配置

工具的静态配置在扩展的 package.json 文件中定义。这包括工具名称、描述、输入模式和其他元数据。

  1. 在扩展的 package.json 文件中的 contributes.languageModelTools 部分添加你的工具条目。

  2. 给工具一个唯一的名称

    属性 描述
    name 工具的唯一名称，用于在扩展实现代码中引用该工具。名称格式为 {verb}_{noun}。参见命名指南。
    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 中 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 将最终响应返回给用户，其中可能包含来自多个工具的响应。

下图展示了 Copilot 工具调用流程。

Diagram that shows the Copilot tool-calling flow

入门

指南

  • 命名：为工具和参数编写清晰且具有描述性的名称。

    • 工具名称：应唯一，并清晰描述其意图。工具名称的格式为 {verb}_{noun}。例如，get_weather、get_azure_deployment 或 get_terminal_output。

    • 参数名称：应描述参数的目的。参数名称的格式为 {noun}。例如，destination_location、ticker 或 file_name。

  • 描述：为工具和参数编写详细描述。

    • 描述工具的作用以及何时应该使用和何时不应该使用。例如，“此工具检索给定位置的天气。”
    • 描述每个参数的作用以及它与工具功能的关系。例如，“destination_location 参数指定要检索天气的位置。它应该是一个有效的位置名称或坐标。”
    • 描述工具的重要限制或约束。例如，“此工具仅检索美国境内位置的天气数据。它可能不适用于其他地区。”

  • 用户确认：为工具调用提供确认消息。对于扩展提供的工具，始终会显示一个通用确认对话框，但工具可以自定义确认消息。向用户提供足够的上下文，以了解工具正在做什么。

  • 错误处理：发生错误时，抛出一个对 LLM 有意义的消息的错误。可以选择提供关于 LLM 下一步应该做什么的指令，例如使用不同的参数重试，或执行不同的操作。

在OpenAI 文档和Anthropic 文档中获取更多创建工具的最佳实践。

相关内容

05/08/2025