使用工具与代理

工具通过特定功能扩展 Visual Studio Code 中的智能体，以完成搜索代码、运行命令、获取 Web 内容或调用 API 等特定任务。VS Code 支持三种类型的工具：内置工具、模型上下文协议 (MCP) 工具和扩展工具。

有关工具类型以及工具如何在智能体循环中工作的背景信息，请参阅工具概念。

本文介绍了如何在聊天提示词中使用工具，以及如何管理工具的调用和批准。

为聊天启用工具

在聊天中使用工具之前，您需要在“聊天”视图中启用它们。您可以使用工具选择器按请求启用或禁用工具。您可以通过安装 MCP 服务器或扩展程序来添加更多提供工具的插件。

访问工具选择器

1. 打开“聊天”视图，并从智能体选择器中选择智能体。

2. 选择聊天输入框中的配置工具按钮。

   

3. 选择或取消选择工具，以控制当前请求可以使用哪些工具。

   使用搜索框过滤工具列表。

当您使用提示词文件或自定义智能体自定义聊天时，您可以指定特定提示词或模式下可用的工具。了解更多关于工具列表优先级顺序的信息。

在提示词中使用工具

当使用智能体时，智能体会根据您的提示词和请求上下文，自动从已启用的工具中确定使用哪些工具。智能体会根据需要自主选择并调用相关工具来完成任务。

您也可以通过输入 # 后跟工具名称来在提示词中显式引用工具。当您想确保使用特定工具时，此功能非常有用。在聊天输入框中输入 # 可查看可用工具列表，包括内置工具、来自已安装服务器的 MCP 工具、扩展工具和工具集。

显式引用工具的示例

• “Node.js 的最新版本是多少 #web”
• “Next.js 中的路由是如何工作的？ #web”
• “修复 #problems 中的问题”
• “解释身份验证流程 #codebase”

权限级别

“聊天”视图中的权限选择器控制智能体在会话期间的自主程度。从聊天输入区域的权限下拉菜单中选择一个权限级别，以选择如何处理工具调用和批准。

权限级别适用于当前聊天会话。您可以随时通过从权限选择器中选择不同的级别来更改它。您可以随时通过选择停止按钮来停止智能体。

自动驾驶 (Autopilot) 的工作原理

当您选择自动驾驶权限级别时，智能体的行为与标准智能体模式不同：

• 持续迭代：智能体保持自主工作，直到确定任务完成。
• 自动批准所有工具：所有工具调用都会自动批准，类似于绕过批准级别。
• 出错自动重试：遇到错误时智能体会自动重试。
• 自动响应问题：通常会阻塞并询问您输入的工具（例如澄清问题）会自动响应，这样智能体就不会因等待答复而停滞。此行为是自动驾驶特有的，不适用于绕过批准。

当启用了 chat.autopilot.enabled 在 VS Code 中打开 在 VS Code Insiders 中打开 设置（默认为开启）时，自动驾驶在“聊天”视图中可用。

工具批准

某些工具在运行前需要您的批准。这是一种安全措施，因为工具可以执行修改文件、环境的操作，或者尝试通过恶意工具输出进行提示词注入攻击。

当工具需要批准时，会显示一个确认对话框，展示工具详细信息。在批准工具之前，请仔细审查这些信息。您可以批准该工具进行单次使用、当前会话使用、当前工作区使用或未来所有调用。

工具和智能体操作可能会导致文件修改。了解如何防止意外编辑工作区中的敏感文件。

管理工具批准

使用命令面板中的 Chat: Manage Tool Approval 命令（⇧⌘P (Windows, Linux Ctrl+Shift+P)）集中审查和配置工具批准。快速选择窗口显示所有按来源（如 MCP 服务器或扩展）分组的工具。

对于每个工具，您可以配置两种类型的批准

• 预批准（“无需批准”）：在工具运行前跳过确认对话框。
• 后批准（“无需审查结果”）：跳过在工具输出被添加到聊天上下文之前对其进行审查的步骤。这适用于返回外部数据的工具，因为其内容可能包含提示词注入尝试。

展开一个来源以配置单个工具的批准，或者选择顶层复选框以一次性信任来自特定 MCP 服务器或扩展的所有工具。

启用或禁用工具自动批准（实验性功能）

默认情况下，您可以选择自动批准任何工具。为了防止意外批准，您可以使用 chat.tools.eligibleForAutoApproval 在 VS Code 中打开 在 VS Code Insiders 中打开 此设置在组织级别进行管理。请联系您的管理员进行更改。ORG 设置禁用特定工具的自动批准。将值设置为 false 可始终要求该工具进行手动批准。

组织也可以使用设备管理策略来强制要求对特定工具进行手动批准。在企业文档中了解更多信息。

URL 批准

当工具尝试访问 URL（例如使用 #web/fetch 工具）时，系统会采用两步批准流程来保护您免受恶意或意外内容的影响。VS Code 会在“聊天”视图中显示一个包含 URL 详细信息的确认对话框供您审查。

• 预批准：批准对该 URL 的请求

  此步骤确保您信任正在访问的域，并可以防止敏感数据被发送到不受信任的站点。

  

  您可以选择单次批准或自动批准未来对特定 URL 或域的请求。选择自动批准不会影响审查结果的需要。当您选择允许请求至时，您可以选择为该 URL 或域配置预批准和后批准。

  注意

  预批准遵循“受信任的域”功能。如果一个域列在那里，系统会自动批准您对该域发出的请求，并跳过结果审查步骤。

• 后批准：批准从 URL 获取的响应内容

  此步骤确保您在内容被添加到聊天或传递给其他工具之前审查获取的内容，从而防止潜在的提示词注入攻击。

  例如，您可能会批准从 GitHub.com 等知名站点获取内容的请求。但由于内容（如问题描述或评论）是用户生成的，它可能包含可能操纵模型行为的有害内容。

  您可以选择单次批准或自动批准来自特定 URL 或域的未来响应。

  重要

  后批准步骤与“受信任的域”功能无关，并且始终需要您的审查。这是一项安全措施，旨在防止在您本应信任的域上出现不受信任内容的问题。

chat.tools.urls.autoApprove 在 VS Code 中打开 在 VS Code Insiders 中打开 设置用于存储您的自动批准 URL 模式。该设置的值可以是用于启用或禁用请求和响应自动批准的布尔值，或者是一个包含 approveRequest 和 approveResponse 属性的对象，以实现细粒度控制。您可以使用确切的 URL、glob 模式或通配符。

URL 自动批准示例

{
"chat.tools.urls.autoApprove": {
    "https://www.example.com": false,
    "https://*.contoso.com/*": true,
    "https://example.com/api/*": {
        "approveRequest": true,
        "approveResponse": false
    }
}

重置工具确认

要清除所有保存的工具批准，请使用命令面板中的 Chat: Reset Tool Confirmations 命令（⇧⌘P (Windows, Linux Ctrl+Shift+P)）。

若要审查并选择性地更改单个工具的批准，而不是全部清除，请使用 Chat: Manage Tool Approval 命令。

编辑工具参数

您可以在工具运行前审查和编辑输入参数

1. 当工具确认对话框出现时，选择工具名称旁边的 chevron 图标以展开其详细信息。

2. 根据需要编辑任何工具输入参数。

3. 选择允许以使用修改后的参数运行该工具。

终端命令

智能体可能会在其工作流中使用终端命令来完成任务。当智能体决定运行终端命令时，它会使用内置的终端工具在 VS Code 的集成终端中执行它们。

在聊天对话中，智能体会显示它所运行的命令。您可以通过选择命令旁边的显示输出 (>) 来在聊天中内联查看命令输出。您也可以通过选择显示终端在集成终端中查看完整输出。

使用实验性 chat.tools.terminal.outputLocation 在 VS Code 中打开 在 VS Code Insiders 中打开 设置来配置终端命令输出的显示位置：聊天内联或集成终端中。

在终端窗格中，您可以看到智能体在聊天会话中使用的终端列表。您还可以通过终端列表中的聊天图标来区分智能体终端。

在后台继续终端命令

当智能体运行长时间运行的终端命令（如启动开发服务器或在监视模式下运行构建）时，您可以将命令推送到后台。这允许智能体继续处理其他任务，而无需等待命令完成。

当命令正在运行时，聊天对话中的终端命令旁边会出现一个在后台继续按钮。选择此按钮可将命令移动到后台。该命令继续运行，智能体稍后可以检查其输出或使用终端执行其他任务。

智能体在运行终端命令时也可以指定超时时间。当达到超时时间时，智能体会停止等待命令并返回迄今收集到的输出。使用 chat.tools.terminal.enforceTimeoutFromModel 在 VS Code 中打开 在 VS Code Insiders 中打开 设置来控制是否强制执行智能体指定的超时值。

智能体也可以选择直接在后台运行命令，无需用户交互。未显示的后台终端会在其命令完成后自动清理，这防止了陈旧的终端在长时间会话中积压。若要显示后台终端并使其在命令完成后保持打开状态，请选择聊天工具调用标题中的显示链接。即使在终端被清理后，终端输出在聊天对话中仍可见。

自动批准终端命令

您可以使用 chat.tools.terminal.autoApprove 在 VS Code 中打开 在 VS Code Insiders 中打开 设置来配置哪些终端命令被自动批准。您可以指定允许和拒绝的命令：

• 将命令设置为 true 以自动批准它们
• 将命令设置为 false 以始终要求批准
• 通过将模式包裹在 / 字符中来使用正则表达式

例如

{
  // Allow the `mkdir` command
  "mkdir": true,
  // Allow `git status` and commands starting with `git show`
  "/^git (status|show\\b.*)$/": true,

  // Block the `del` command
  "del": false,
  // Block any command containing "dangerous"
  "/dangerous/": false
}

默认情况下，模式匹配单个子命令。要使一个命令被自动批准，所有子命令都必须匹配一个 true 条目，并且不能匹配 false 条目。

对于高级场景，请使用带有 matchCommandLine 属性的对象语法来匹配整个命令行，而不是单个子命令。

相关设置

• chat.tools.terminal.enableAutoApprove 在 VS Code 中打开 在 VS Code Insiders 中打开 此设置在组织级别进行管理。请联系您的管理员进行更改。ORG：永久禁用自动批准功能。
• chat.tools.terminal.blockDetectedFileWrites 在 VS Code 中打开 在 VS Code Insiders 中打开 （实验性功能）：当设置为 outsideWorkspace（默认值）时，需要对在工作区之外写入文件的终端命令进行批准。当启用了会话级命令批准时，写入操作系统临时文件夹（macOS 和 Linux 上为 /tmp，Windows 上为 %TEMP%）的操作豁免。
• chat.tools.terminal.ignoreDefaultAutoApproveRules 在 VS Code 中打开 在 VS Code Insiders 中打开 （实验性功能）：禁用所有默认规则（允许和阻止），从而完全控制所有规则。

沙盒智能体命令

有关沙盒的工作原理、其防御对象以及操作系统级实现细节的概述，请参阅智能体沙盒。

智能体沙盒限制了智能体执行命令时的文件系统和网络访问。启用沙盒后，终端命令会自动批准而无需用户确认，因为它们在受控环境中运行。

您可以选择完全隔离（限制文件系统和网络访问）或仅文件系统隔离（允许不受限制的出站网络流量）。

要配置智能体沙盒，请设置 chat.agent.sandbox.enabled 在 VS Code 中打开 在 VS Code Insiders 中打开 此设置在组织级别进行管理。请联系您的管理员进行更改。ORG 设置。

当启用沙盒（on 或 allowNetwork）时

当文件系统访问受到限制时，以下规则适用于智能体命令：

• 命令对工作区文件夹、沙盒运行时临时文件夹以及 VS Code 自动添加的任何每个命令路径（例如 git、node、npm、dotnet 所需的路径）具有读取权限。默认情况下，拒绝从您的主目录 ($HOME) 读取数据。
• 命令仅对当前工作目录及其子目录具有写入权限。
• 命令运行无需用户确认提示。

当网络访问受到限制时，以下规则适用于智能体命令：

• 除非明确允许某些域，否则所有出站网络访问均被阻止。
• 您可以使用 chat.agent.allowedNetworkDomains 在 VS Code 中打开 在 VS Code Insiders 中打开 此设置在组织级别进行管理。请联系您的管理员进行更改。ORG 和 chat.agent.deniedNetworkDomains 在 VS Code 中打开 在 VS Code Insiders 中打开 此设置在组织级别进行管理。请联系您的管理员进行更改。ORG 来配置域级异常。被拒绝的域优先于允许的域。
• 当设置为 allowNetwork 时，允许所有出站网络流量，并忽略域设置。

配置文件系统访问

使用 chat.agent.sandbox.FileSystem.linux 在 VS Code 中打开 在 VS Code Insiders 中打开 或 chat.agent.sandbox.FileSystem.mac 在 VS Code 中打开 在 VS Code Insiders 中打开 设置来控制文件系统访问。

您可以指定读取和写入访问的允许规则，以及读取和写入访问的拒绝规则。这些规则不支持 glob 模式。denyWrite 和 denyRead 规则优先于 allowWrite 和 allowRead 规则。

工作区文件夹、沙盒运行时临时文件夹以及每个命令的读取路径会自动允许，因此您通常只需要 allowRead 来授予对工作区外部工具配置或数据的访问权限。

{
  "chat.agent.sandbox.FileSystem.mac": {
    // Allow writes to the working directory
    "allowWrite": ["."],
    // Allow reads from an additional path outside the workspace
    "allowRead": ["/Users/me/.config/myapp"],
    // Block writes to specific subdirectories
    "denyWrite": ["./secrets/"],
    // Block reads from specific paths
    "denyRead": ["/etc/passwd"]
  }
}

配置网络访问

您可以通过启用 chat.agent.networkFilter 在 VS Code 中打开 在 VS Code Insiders 中打开 此设置在组织级别进行管理。请联系您的管理员进行更改。ORG 设置来限制智能体工具（fetch 工具、集成浏览器）可以访问的域。启用后，网络访问由 chat.agent.allowedNetworkDomains 在 VS Code 中打开 在 VS Code Insiders 中打开 此设置在组织级别进行管理。请联系您的管理员进行更改。ORG 和 chat.agent.deniedNetworkDomains 在 VS Code 中打开 在 VS Code Insiders 中打开 此设置在组织级别进行管理。请联系您的管理员进行更改。ORG 设置来控制。当两个列表都为空时，所有域都被阻止。

当同时启用了沙盒时，这些网络规则也会额外应用于智能体执行的终端命令。

被拒绝的域总是优先于允许的域。这两个设置都支持 *.example.com 这样的通配符。

{
    "chat.agent.networkFilter": true,
    "chat.agent.allowedNetworkDomains": [
        "api.github.com"
    ],
    "chat.agent.deniedNetworkDomains": [
        "example.com"
    ]
}

使用工具集对工具进行分组

工具集是一组工具，您可以将其作为单个实体在提示词中引用。工具集可帮助您组织相关工具，使它们在聊天提示词、提示词文件和自定义聊天智能体中更易于使用。一些内置工具属于预定义的工具集，例如 #edit 和 #search。

创建工具集

要创建工具集

1. 运行命令面板中的 Chat: Configure Tool Sets 命令，然后选择 Create new tool sets file。

   或者，选择“聊天”视图中的省略号 (...) 菜单，选择 Tool Sets，然后选择 Create new tool sets file。

2. 在打开的 .jsonc 文件中定义您的工具集。

   工具集具有以下结构

   {
     "reader": {
       "tools": ["search/changes", "search/codebase", "read/problems", "search/usages"],
       "description": "Tools for reading and gathering context",
       "icon": "book"
     }
   }
   

   工具集属性

   • tools：工具名称数组（内置工具、MCP 工具或扩展工具）
   • description：在工具选择器中显示的简短描述
   • icon：工具集的图标（请参阅产品图标参考）

使用工具集

通过输入 # 后跟工具集名称，在您的提示词中引用工具集。

• “分析代码库的安全问题 #reader”
• “数据库连接字符串定义在哪里？ #search”

在工具选择器中，工具集作为相关工具的可折叠组提供。您可以选择或取消选择整个工具集，以一次性快速启用或禁用多个相关工具。

常见问题

我怎么知道哪些工具可用？

在聊天输入框中输入 # 以查看所有可用工具的列表。您还可以使用聊天中的工具选择器来查看和管理活动工具列表。

我收到一条错误信息说“每个请求不能拥有超过 128 个工具。”

一个聊天请求一次最多可以启用 128 个工具。如果您看到有关超出每个请求 128 个工具的错误

• 在“聊天”视图中打开工具选择器，并取消选择一些工具或整个 MCP 服务器以减少数量。

• 或者，通过 github.copilot.chat.virtualTools.threshold 在 VS Code 中打开 在 VS Code Insiders 中打开 设置启用虚拟工具，以自动管理大型工具集。

为什么智能体没有使用我配置的终端 shell？

智能体使用您配置为终端默认的 shell，但 Windows 上的 cmd (命令提示符) 和 macOS/Linux 上的 sh 除外。这是因为这些 shell 不支持 shell 集成，这意味着智能体对终端内部发生的情况的可见性非常有限。智能体需要依赖超时和观察终端是否空闲来继续工作，而不是直接获得命令何时运行或完成的信号。这会导致缓慢且不稳定的体验。

您仍然可以通过终端配置文件设置配置智能体使用这些 shell，但是与在 Windows 上使用 PowerShell 或在 macOS/Linux 上使用 bash/zsh 相比，这将导致体验较差。

• chat.tools.terminal.terminalProfile.windows 在 VS Code 中打开 在 VS Code Insiders 中打开 - 在 Windows 上覆盖 shell
• chat.tools.terminal.terminalProfile.osx 在 VS Code 中打开 在 VS Code Insiders 中打开 - 在 macOS 上覆盖 shell
• chat.tools.terminal.terminalProfile.linux 在 VS Code 中打开 在 VS Code Insiders 中打开 - 在 Linux 上覆盖 shell

我可以自动批准所有工具和终端命令吗？

您有几种自动批准工具调用的选项：

• 权限级别：从权限选择器中选择绕过批准或自动驾驶权限级别，以自动批准当前会话的所有工具。
• 全局设置：启用 chat.tools.global.autoApprove 在 VS Code 中打开 在 VS Code Insiders 中打开 此设置在组织级别进行管理。请联系您的管理员进行更改。ORG 设置，以自动批准所有工作区中的所有工具。您也可以直接通过在聊天中使用 /yolo 或 /autoApprove 斜杠命令来启用它，或使用 /disableYolo 或 /disableAutoApprove 来禁用它。首次启用全局自动批准时，系统会弹出警告对话框要求您确认。

工具和聊天参与者有什么区别？

聊天参与者是专门的助手，使您能够在聊天中提出特定领域的查询。可以将聊天参与者想象成一位领域专家，您将聊天请求移交给它，它会处理剩下的事情。

工具作为智能体流的一部分被调用，以贡献和执行特定任务。您可以在单个聊天请求中包含多个工具，但一次只能激活一个聊天参与者。

我可以创建自己的工具吗？

是的。您可以通过两种方式创建工具：

• 开发 VS Code 扩展，使用语言模型工具 API 提供工具。
• 创建 MCP 服务器以提供工具。请参阅 MCP 开发者指南。

相关资源

• 聊天工具参考
• 智能体钩子 - 在工具生命周期事件中执行自定义命令
• 在 VS Code 中使用 AI 的安全注意事项