🚀 在 VS Code 中！

LanguageModelTool API

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

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

LLM 中的工具调用是什么？

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

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

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

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

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

  • 使用专门的工具扩展代理模式，这些工具作为响应用户提示的一部分自动调用。例如，启用数据库基架和查询作为聊天对话的一部分。
  • 通过使用广泛的扩展 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 clause 来限制工具何时可用于代理模式或可以在提示中引用。例如，获取调试调用堆栈信息的工具应仅在用户正在调试时可用。

    "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 中的 inutSchema 中定义的 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 文档中获取有关创建工具的更多最佳实践。

相关内容

04/03/2025