探索智能体开发 -

使用工具与代理

工具通过为 Visual Studio Code 中的代理提供专业功能来扩展其能力，从而完成诸如搜索代码、运行命令、获取网页内容或调用 API 等特定任务。VS Code 支持三种类型的工具：内置工具、模型上下文协议 (MCP) 工具和扩展工具。

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

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

为聊天启用工具

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

提示

仅选择与您的提示词相关的工具，以改善结果。

如何访问工具选择器

  1. 打开“聊天”视图，并从代理选择器中选择代理 (Agent)。

  2. 在聊天输入框中选择配置工具 (Configure Tools) 按钮。

    Screenshot showing the Chat view, highlighting the Configure Tools button in the chat input.

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

    使用搜索框筛选工具列表。

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

在提示词中使用工具

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

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

显式工具引用的示例

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

默认情况下，工具调用的详细信息在聊天对话中是折叠的。您可以通过选择聊天中的工具摘要行来展开它们，或者使用 chat.agent.thinking.collapsedTools 在 VS Code 中打开 在 VS Code Insiders 中打开 设置（实验性功能）更改默认行为。

权限级别

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

权限级别 描述
默认批准 使用您配置的批准设置。需要批准的工具在运行前会显示确认对话框。代理可能会在需要时提出澄清性问题。
绕过批准 自动批准所有工具调用，不显示确认对话框，并在出错时自动重试。代理可能会在需要时提出澄清性问题。
自动驾驶 (Autopilot)（预览版） 自动批准所有工具调用，不显示确认对话框，并自动回答澄清性问题。代理将持续自主工作，直到任务完成。
注意

绕过批准和自动驾驶会跳过手动批准提示，包括针对文件编辑、终端命令和外部工具调用等可能具有破坏性的操作。首次启用任一级别时，系统会弹出一个警告对话框要求您确认。仅在了解安全隐患的情况下使用这些级别。有关更多详细信息，请参阅安全注意事项。

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

自动驾驶的工作原理

注意

自动驾驶目前处于预览阶段。

当您选择自动驾驶权限级别时，代理的行为与标准代理会话不同

  • 持续迭代：代理持续自主工作，直到确定任务完成为止。
  • 自动批准所有工具：与绕过批准级别类似，所有工具调用均被自动批准。
  • 错误自动重试：遇到错误时，代理会自动重试。
  • 自动回答问题：通常会阻塞并请求您输入的工具（例如澄清性问题）会自动响应，因此代理不会因等待回复而停滞。此行为特定于自动驾驶，不适用于绕过批准。

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

工具批准

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

当工具需要批准时，会显示一个确认对话框，展示工具详细信息。批准工具前请仔细审阅信息。您可以选择批准工具单次使用、在当前会话中使用、在当前工作区使用，或允许所有未来的调用。

Screenshot of a tool confirmation dialog showing tool details and approval options.

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

重要

在批准前务必仔细检查工具参数，特别是针对那些会修改文件、运行命令或访问外部服务的工具。请参阅在 VS Code 中使用 AI 的安全注意事项。

管理工具批准

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

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

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

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

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

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

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

URL 批准

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

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

    此步骤确保您信任正在联系的域，并防止将敏感数据发送到不受信任的站点。

    Screenshot of a URL approval dialog showing URL details and approval options.

    您可以选择单次批准，或自动批准未来对特定 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)）。

要查看并有选择地更改单个工具批准，而不是清除所有批准，请使用聊天：管理工具批准命令。

编辑工具参数

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

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

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

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

终端命令

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

在聊天对话中，代理会显示其运行的命令。您可以通过选择命令旁边的显示输出 (Show Output) (>) 来查看聊天的内联输出。您也可以通过选择显示终端 (Show Terminal) 在集成终端中查看完整输出。

Screenshot showing terminal command output in chat.

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

在终端面板中，您可以查看代理为聊天会话使用的终端列表。您还可以通过终端列表中的聊天图标来区分代理终端。

Screenshot showing the integrated terminal with multiple agent terminals.

在后台继续终端命令

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

命令运行时，聊天对话中的终端命令旁边会出现一个在后台继续 (Continue in Background) 按钮。选择此按钮可将命令移至后台。命令将继续运行，代理以后可以检查其输出或将终端用于其他任务。

代理在运行终端命令时还可以指定超时时间。当达到超时时间时，代理将停止等待命令并返回目前已收集的输出。使用 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 中打开 此设置由组织级别管理。请联系您的管理员进行更改。：永久禁用自动批准功能
  • chat.tools.terminal.blockDetectedFileWrites 在 VS Code 中打开 在 VS Code Insiders 中打开 （实验性）：检测文件写入（实验性功能）
  • chat.tools.terminal.ignoreDefaultAutoApproveRules 在 VS Code 中打开 在 VS Code Insiders 中打开 （实验性）：禁用所有默认规则（包括允许和阻止），从而完全控制所有规则。
注意

自动批准终端命令提供了尽力而为的保护，并假定代理没有恶意行为。在启用终端自动批准时保护自己免受提示词注入攻击非常重要，因为某些命令可能会溜过去。以下是检测可能失效的一些示例

  • VS Code 使用 PowerShell 和 bash tree sitter 语法来提取子命令，因此如果这些语法检测不到，模式将无法被识别。
  • VS Code 使用 bash 语法，因为没有 zsh 或 fish 语法，所以某些子命令无法检测到。
  • 文件写入的检测目前非常有限，因此可能会出现通过终端写入文件的情况，而这些在文件编辑代理工具中是无法做到的。
  • 通过各种技术（如引号拼接）可以绕过自动批准。例如，find -exec 通常被阻止，但 find -e"x"ec 不会被阻止，尽管它们的作用完全相同。

如果可能存在提示词注入，或者您处于高风险环境中，请考虑启用代理沙盒或在容器中运行 VS Code。

沙盒代理命令

注意

代理沙盒目前处于预览阶段，未来可能会进一步演变。

有关沙盒工作原理、其防护内容以及操作系统级实现细节的概述，请参阅代理沙盒。

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

要启用代理沙盒，请将 chat.agent.sandbox 在 VS Code 中打开 在 VS Code Insiders 中打开 设置为 true。

当启用沙盒时

  • 命令对整个文件系统拥有读取权限
  • 命令仅对当前工作目录及其子目录拥有写入权限
  • 所有域的网络访问均被阻止
  • 命令在无需用户确认提示的情况下运行
重要

如果未安装沙盒所需的操作系统依赖项，VS Code 将提示您安装必要的组件。如果您选择不安装，则沙盒功能将不会启用。

配置文件系统访问

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

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

{
  "chat.agent.sandboxFileSystem.mac": {
    // Allow writes to the working directory
    "allowWrite": ["."],
    // Block writes to specific subdirectories
    "denyWrite": ["./secrets/"],
    // Block reads from specific paths
    "denyRead": ["/etc/passwd"]
  }
}

配置网络访问

默认情况下，启用沙盒时，所有域的网络访问均被阻止。使用 chat.agent.sandboxNetwork.allowedDomains 在 VS Code 中打开 在 VS Code Insiders 中打开 和 chat.agent.sandboxNetwork.deniedDomains 在 VS Code 中打开 在 VS Code Insiders 中打开 设置来允许特定域名。

{
    "chat.agent.sandboxNetwork.allowedDomains": [
        "api.github.com"
    ],
    "chat.agent.sandboxNetwork.deniedDomains": [
        "example.com"
    ]
}

使用工具集组合工具

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

创建工具集

创建工具集的方法

  1. 在命令面板中运行聊天：配置工具集 (Chat: Configure Tool Sets) 命令，然后选择创建新的工具集文件 (Create new tool sets file)。

    或者，在“聊天”视图中选择省略号 (...) 菜单，选择工具集 (Tool Sets)，然后选择创建新的工具集文件。

  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 中打开 此设置由组织级别管理。请联系您的管理员进行更改。 设置，以自动批准所有工作区中的所有工具。您也可以直接在聊天中通过使用 /yolo 或 /autoApprove 斜杠命令来启用它，或使用 /disableYolo 或 /disableAutoApprove 来禁用它。首次启用全局自动批准时，系统会弹出一个警告对话框要求您确认。
注意

这两种方法都会禁用手动批准提示，包括针对可能具有破坏性的操作。它们会消除关键的安全保护措施，并使攻击者更容易破坏机器。仅在了解后果的情况下使用这些选项。有关更多详细信息，请参阅安全文档。

chat.tools.global.autoApprove 在 VS Code 中打开 在 VS Code Insiders 中打开 此设置由组织级别管理。请联系您的管理员进行更改。 设置适用于您的所有工作区。如果您更喜欢将自动批准限制在当前会话中，请使用会话范围的权限级别。

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

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

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

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

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

相关资源

4/8/2026
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.