在 VS Code 中试用！

语言模型工具 API

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

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

LLM 中的工具调用是什么？

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

LLM 实际上从不执行工具本身，而是 LLM 生成用于调用工具的参数。清楚地描述工具的目的、功能和输入参数非常重要，以便可以在正确的上下文中使用工具。

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

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

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

  • 通过专用工具扩展代理模式，这些工具会作为响应用户提示的一部分自动调用。例如，作为聊天对话的一部分启用数据库支架和查询。
  • 通过专用工具扩展询问和编辑模式，用户可以使用 # 在聊天提示中直接引用这些工具。例如，从 Web 获取内容。
  • 通过使用广泛的扩展 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 中 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

入门

指南

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

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

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

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

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

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

  • 错误处理：发生错误时，抛出带有对 LLM 有意义的消息的错误。或者，提供关于 LLM 接下来应该做什么的说明，例如使用不同的参数重试，或执行不同的操作。

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

相关内容

06/12/2025