Visual Studio 和 VS Code 中的自定义代理：完整指南

主页 » Python » Visual Studio 和 VS Code 中的自定义代理：完整指南

AI 驱动的代理正在重塑开发人员在 Visual Studio 和 VS Code 中的工作方式，远远超越了单一的通用助手，发展成为一个由专业化、可定制的助手组成的丰富的生态系统。 这些代理不仅可以在聊天窗口中回答问题，还可以规划工作、编辑解决方案中的代码、运行工具，甚至可以与云服务或外部知识库协调，从而端到端地交付真正的功能。

当您将内置代理、本地和云执行模式以及存储库中定义的完全自定义代理配置文件结合起来时，您将获得一个灵活的框架，该框架可以适应您团队的工作流程，而不是强迫您采用单一的工作方式。 从调试和性能分析到自动化测试、现代化、文档编写和代码审查，这些都与您的内部标准相关联，Visual Studio 和 VS Code 中的自定义代理为您提供了一种将最佳实践直接编码并扩展到 IDE 的方法。

Visual Studio 中的预设代理：针对常见工作流程的专用助手

Visual Studio 附带一套精心挑选的预设代理，这些代理与 IDE 深度集成，每个代理都专注于开发生命周期的特定部分。 这些代理的功能远远超出了一般的聊天模型，因为它们可以直接从您的解决方案中访问调用堆栈、诊断信息、分析器跟踪、项目图表和测试基础架构。

调试器代理旨在进行系统性的错误分析，利用您的运行时上下文，而不是简单地将错误消息复述给您。 它可以检查调用堆栈、局部变量和诊断输出，逐步排查故障，通常会跨多个文件或层跟踪错误，直到找到真正的根本原因，而不是可见的症状。

Profiler 代理与 Visual Studio 的性能分析堆栈紧密连接，因此性能建议是基于您的实际代码路径和热点。 它不提供通用的调优技巧，而是检查性能分析器会话，突出真正的瓶颈，并提出与您的项目架构和技术栈相一致的有针对性的优化方案。

测试代理（在加载解决方案时可用）专注于生成和改进符合项目框架和约定的单元测试。 它不会直接抛出会被 CI 立即标记的样板测试，而是会学习你现有的模式，并利用这些上下文来创建现实的、可维护的测试，这些测试可以插入到你的管道中。

Modernize 代理（适用于 .NET 和 C++ 项目）旨在指导整个解决方案图的框架和依赖项升级。 它可以发现破坏性变更，提出迁移代码建议，并根据您的编码模式进行调整，使现代化感觉像是辅助重构，而不是有风险的手动重写。

您可以通过聊天面板中的代理选择器访问这些预设代理，或者直接在聊天中使用“@”语法。 在它们之间切换，可以让你将不同的“角色”应用于同一个代码库——例如，从以调试为中心的对话过渡到以测试或性能为导向的对话，而不会丢失上下文。

从预设到自定义：在平台上构建您自己的代理

预设代理涵盖了最常见的工作流程，但真正的强大之处在于您可以定义自定义代理，使其与您的团队实际工作方式相匹配。 Visual Studio 和 GitHub Copilot 的代理具有共同的基础：工作区感知模型，能够理解您的代码，可以通过提示调用 IDE 工具，并且可以被赋予专门的角色、模型和工具集。

自定义代理被定义为 Markdown 配置文件（通常带有一个 .agent.md 后缀）存储在 agents 您的仓库或个人资料中的文件夹。 在 GitHub 托管的项目中，这通常意味着 .github/agents/your-agent.agent.md但在组织或企业层面，您可以使用顶级 agents 没有目录的 .github/ 添加前缀，以便同一个代理可以在多个存储库中重复使用。

在每个代理配置文件中，您可以声明一个 YAML frontmatter 块，用于指定其身份、功能、工具和可选的 MCP 配置。 典型特征包括以人为本 name，简短 description 概括代理人所做的事情，列表如下： tools 它可以调用，可选 mcp-servers 参赛作品，首选 model，可选 target （例如 vscode or github-copilot然后是定义代理行为方式的主要指令消息。

YAML 文件中 Markdown 区域的消息部分就像该代理的长格式系统提示符一样。 你可以用它来描述语气、优先级、编码标准、审查清单、测试期望，或者你希望代理始终遵循的任何其他规则，最多可以有相当宽裕的字符限制（大约 30,000 个字符），让你能够对相当复杂的行为进行编码。

文件命名规则非常严格，以确保系统的稳健性和可移植性。 文件名（之前） .agent.md必须唯一且具有描述性，并且只能包含字母等字符（a-z, A-Z),数字（0-9）、点、连字符和下划线，这有助于避免跨工具和平台出现问题。

MCP 和外部知识：将代理商与公司大脑连接起来

当您通过模型上下文协议 (MCP) 将自定义代理连接到外部知识源时，自定义代理才能真正发挥作用。 MCP 不会将代理限制在你的存储库内部，而是允许它与内部文档系统、设计库、API 或数据库进行交互，将其作为一流的工具。

您可以在代理配置文件中配置 mcp-servers 允许只有该代理才能调用特定的 MCP 工具。 例如，设计执行代理可能连接到 Figma 支持的 MCP 服务器，而合规性代理可能与策略数据库通信；除非您明确启用它们，否则这些工具不会影响其他代理。

各个团队已经开始利用这些功能构建适合自身组织的特定工作流程。 一种常见的模式是代码审查代理，它不仅根据通用最佳实践来评估拉取请求，还根据您通过 MCP 提供的内部样式指南或架构决策记录来评估拉取请求。

另一个常见的场景是设计系统强制执行，其中代理程序连接到您的设计资产和组件库。 该代理可以调用​​由 Figma 文件或 UI 组件注册表支持的工具，在视觉或结构偏差进入生产环境之前就将其标记出来，从而引导开发人员回归到已批准的模式。

规划代理也越来越受欢迎，它们完全专注于在编写任何代码之前进行探索和范围界定工作。 这些代理会收集需求、提出澄清问题、探索极端情况，然后生成结构化的实施计划，您可以将其交给人或更注重行动的编码代理来执行。

如果您正在寻找现成的示例，社区维护的“awesome-copilot”存储库提供了不断增长的代理配置集合。 您可以将它们克隆为起点，但您仍然需要检查工具名称是否实际存在于您的 Visual Studio 或 VS Code 环境中，因为 GitHub.com、VS Code、JetBrains IDE 和其他平台之间的工具标识符有所不同。

自主代理在不同工具和环境中的行为方式

从概念层面来说，“代理”是一种人工智能助手，它可以自主执行编码任务，而不仅仅是提供内联代码片段。 你提供一个高层次的目标（“修复失败的测试”、“实现此功能”），代理会将其分解成步骤，编辑文件，运行命令，并在出现失败时进行迭代，通常以提交或拉取请求结束。

VS Code 通过多种方式展现了这种代理行为，从编辑器中的交互式聊天到通过 Copilot CLI 实现的后台自动化。 您可以让代理程序在您的本地机器上运行，也可以在远程云环境中运行，或者通过 Anthropic 或 OpenAI 等第三方提供商运行，并根据具体情况决定代理程序拥有多少自主权以及可以调用哪些工具。

无论客服人员实际在何处运行，所有正在进行的会话都会显示在聊天视图中的统一会话列表中。 这样更容易跟踪多个长时间运行的任务，在它们之间切换，并保持连贯的活动历史记录。

智能体主要从两个维度运行：运行位置（本地与云端）以及与用户的交互方式（完全交互式与高度自主）。 本地代理使用 VS Code 代理循环直接在编辑器中工作，并可充分访问工作区；Copilot CLI 代理在您的计算机上后台运行，并可以使用 Git 工作树；云代理在 GitHub 的基础架构上运行，并与 pull 请求紧密集成以进行协作。

它还支持依赖于 Anthropic 或 OpenAI 等提供商的 SDK 的“第三方”代理，以及 API演进与智能体人工智能. 这些程序可以在本地运行，也可以在您自己的云端运行，让您可以更好地控制数据边界，同时仍然可以受益于 VS Code 中相同的聊天和会话管理模式。

智能体主要从两个维度运行：运行位置（本地与云端）以及与用户的交互方式（完全交互式与高度自主）。 本地代理使用 VS Code 代理循环直接在编辑器中工作，并可充分访问工作区；Copilot CLI 代理在您的计算机上后台运行，并可以使用 Git 工作树；云代理在 GitHub 的基础架构上运行，并与 pull 请求紧密集成以进行协作。

选择合适的代理角色和权限级别

如果说代理类型定义了工作运行的地点，那么代理角色则定义了工作是如何进行的。 代码审查代理配置为对质量和风格进行评论，但不会更改文件；而实现代理则被授权编辑代码、运行命令，并根据需要调用许多工具。

VS Code 提供了三个内置的代理角色作为基本角色：代理、计划和询问。 主要的代理角色专注于端到端的实现、协调工具和多文件更改；计划角色创建结构化的、分步的计划，无需编辑代码；提问角色回答有关您的代码库或技术主题的问题，并可以建议您手动应用的代码块。

您可以随时通过聊天视图中的代理下拉菜单在这些角色之间切换，对于更专业的流程，您可以定义具有自己角色和工具集的自定义代理。 这样就很容易将保守的审查代理与激进的重构代理分开，每个代理都针对自己的目的进行调整。

由于代理可以自主调用工具和运行 shell 命令，因此 VS Code 添加了一个权限层来控制它们在每个会话中获得的自由度。 使用权限选择器，您可以决定是否每次调用工具都需要您明确批准，是否只有高风险调用需要确认，或者是否允许代理以几乎完全自动化的“自动驾驶”模式运行。

默认审批模式通常会将只读且显然安全的工具视为预先批准的工具，同时提示用户执行可能修改文件或运行命令的操作。 绕过审批功能通过自动审批所有内容来最大限度地提高速度；自动驾驶（目前处于预览阶段）更进一步，它既可以审批工具，也可以自动回答澄清提示，以便代理可以一直工作，直到系统认为任务完成为止。

在代理人之间交接工作并分配任务

VS Code 中代理最强大的功能之一是能够将会话从一个代理移交给另一个代理。 这样一来，就可以实现这样的工作流程：使用本地 Plan 代理定义一个复杂的功能，然后将该计划交给 Copilot CLI 代理在本地进行原型设计，最后将结果发送到云代理，该云代理会在 GitHub 上发起拉取请求。

当您从会话下拉列表中更改代理类型时，VS Code 会创建一个新会话，该会话将继承完整的聊天历史记录和上下文。 原始代理的对话会被存档以供参考，而新代理则从相同的起点继续，但角色或执行环境不同。

通过 Copilot CLI，您可以使用以下方式显式地将工作委派给基于云的代理： /delegate 在聊天中发出指令。 您可以添加更多指令来微调接收代理应该关注的内容，这在从探索性工作切换到生产就绪的更改时非常有用。

与 GitHub issues 和 pull requests 的深度集成意味着您可以在不离开正常工作流程的情况下将编码任务分配给代理。 通过将问题分配给 copilot 或者在评论中提及 Copilot 编码代理，您可以请求符合代理配置配置文件的代码更改或审查。

在支持 GitHub Pull Requests 扩展的 IDE 中，您甚至可以要求代理实现此功能。 TODO 编辑的直接评论。 这样就有效地将分散的待办事项标记变成了一个结构化任务队列，编码代理可以选取这些任务，执行它们，然后将它们作为提交或 PR 推送回去。

在 GitHub 和 IDE 中创建和配置自定义代理

设置自定义代理通常从 GitHub.com 或您的 IDE 开始，您需要在其中创建一个新的代理配置文件。 agents 目录。 在 GitHub.com 的 Copilot 区域下有一个专门的“代理”选项卡，允许您在选定的存储库和分支中启动模板配置文件。

当您从 GitHub 代理选项卡创建新代理时，平台会生成一个模板文件，通常名为 my-agent.agent.md在仓库中 .github/agents 文件夹中。 对于组织或企业级代理，您需要移除 .github/ 将文件添加到路径中，并将其放置在顶级目录下。 agents 改为使用目录，这样就可以在多个项目中使用。

下一步是将文件重命名为有意义且唯一的名称，并遵循允许的字符集。 清晰的文件名可以让队友更容易理解代理的用途，并稍后在 GitHub.com 或 IDE 的聊天界面中从下拉列表中正确选择它。

文件就位后，您可以编辑 YAML frontmatter 来配置代理的名称、描述、工具以及可选的模型和 MCP 服务器配置。 描述是必需的，应该简要说明代理针对哪些方面进行了优化——性能评估、API 加固、测试生成、特定领域的验证等等。

将代理配置文件提交并合并到默认分支后，新代理将出现在 Copilot 编码代理体验可用的地方的代理下拉列表中。 这包括 GitHub.com、Copilot CLI 和受支持的 IDE，因此一个单一的代理定义就可以在所有这些表面上驱动一致的行为。

在 VS Code 中使用自定义代理

VS Code 使得直接从聊天视图创建和调整自定义代理变得特别简单。 在聊天面板底部有一个代理下拉菜单，其中包含配置自定义代理的选项，以及创建新代理的快捷方式。

在 VS Code 中创建新的自定义代理时，您可以决定其配置文件应该位于何处：当前工作区还是用户配置文件中。 工作区级代理的作用域限定于该项目。 .github/agents 文件夹，而用户配置文件代理则存在于您的个人配置下，并且在您打开的所有工作区中均可用。

然后，您可以为新的代理配置文件指定文件名；这也是代理下拉列表中显示的默认标签。 VS Code 打开了新创建的文件 .agent.md 文件，以便您可以填写 YAML 和 Markdown 指令，其中包含描述、工具以及您需要的任何行为提示。

编辑器提供了一个“配置工具…”按钮，点击后会打开一个专门的对话框，其中列出了您的环境中代理可以使用的所有工具。 这包括内置工具、MCP 提供的工具以及来自已安装扩展的工具；您可以选择所需的工具，VS Code 会将相应的条目写入代理配置文件中。

要控制代理所依赖的 AI 模型，您可以添加一个 model: 在 YAML 中设置属性，然后使用自动完成功能从支持的模型集中进行选择。 例如，这样就可以轻松地让功能强大的重构代理访问功能更强大的模型，同时让轻量级的问答代理使用更小、更便宜的模型。

更新现有代理同样简单：从代理下拉菜单中选择“配置自定义代理…”，然后选择要修改的配置文件。 VS Code 打开底层 .agent.md 文件，编辑并保存后，更改将在使用该配置文件的任何地方生效。

JetBrains IDE、Eclipse 和 Xcode 中的自定义代理

相同的代理配置文件格式适用于多个主流 IDE，而不仅仅是 VS Code。 JetBrains IDE（例如 IntelliJ IDEA、WebStorm 或 Rider）、Eclipse 和 Xcode 都与 GitHub Copilot 的代理集成，可以创建和编辑 .agent.md 以熟悉的方式处理文件。

在 JetBrains IDE 中，首先打开 GitHub Copilot Chat 窗口，然后使用底部的代理下拉菜单来配置代理。 选择工作区范围会在其中创建一个新的配置文件。 .github/agents 在您的项目中，IDE 会打开它，以便您可以设置描述、工具和说明。

JetBrains 编辑器中的“配置工具…”按钮可让您浏览可用工具（包括基于 MCP 的工具），并一键将其添加到代理中。 您还可以指定 model 此处的属性同样由支持的 AI 模型自动完成列表驱动。

在 Eclipse 中，工作流程类似：打开 Copilot Chat 视图，使用代理下拉菜单选择“配置代理…”，然后通过“添加…”操作创建新配置文件。 编辑打开了一个新页面 .agent.md 文件下 .github/agents您可以在此处定义描述、工具、MCP 服务器和行为提示，并根据需要调整模型和其他属性。

Xcode 的集成还依赖于聊天视图的代理下拉菜单，并提供了一个专门的“创建代理”选项。 命名配置文件后，Xcode 会生成 .agent.md 文件下 .github/agents 并在编辑器中提供了一个“自定义代理”按钮，让您可以选择 AI 模型、选择工具（包括 MCP 工具）以及配置自定义代理之间的交接。

在 JetBrains、Eclipse 和 Xcode 中，更新现有配置文件总是遵循相同的模式：打开代理配置，选择代理，然后编辑底层 Markdown 文件。 这些修改会反馈到 GitHub 的 Copilot 生态系统中，因此无论使用哪个 IDE，同一个自定义代理都能保持一致。

设计强大的代理配置文件：身份、工具和行为

要想真正发挥定制代理的价值，取决于你如何精心设计他们的个人资料，首先要明确他们的身份和重点突出的能力。 一个精心制作的 name 和 description 明确表达代理的意图，帮助底层模型优先考虑正确的行为。

此 tools 列表是你控制代理人实际能做什么的主要手段。 您可以通过省略属性来授予代理访问环境中所有工具的权限，或者您可以非常精确地控制权限，仅启用部分功能——例如 "read", "edit", "search" 以及一些特定领域的 MCP 工具。

可选 mcp-servers 条目允许您配置仅对该特定代理配置文件可见的额外服务器。 当代理人需要对内部系统（如机密设计文档或合规性数据库）拥有特权访问权限，但您不希望每个代理人都能查询相同的资源时，这非常有用。

在 VS Code、JetBrains IDE、Eclipse 或 Xcode 中使用代理时，您还可以指定一个专用的代理。 model 属性使得每个代理人都可以使用最适合其工作的模型。 有些团队为规划和架构审查代理运行复杂的推理模型，而为轻量级的问答代理提供更便宜的模型以控制成本。

可选的 target 当您希望代理人只在特定环境中出现时，属性非常有用。 通过设置 target: vscode or target: github-copilot您可以构建专门用于基于 IDE 的工作流或基于 GitHub.com 的工作流的配置文件，而省略该属性则可使代理在任何地方可用。

最后，Markdown 文件的主体部分包含了代理的实际指令或“声音”，您可以在这里编写您的标准和期望。 您可以详细说明单元测试覆盖率规则、技术限制、文档的语气指南或详细的审查清单；内容越丰富、越清晰，代理在不同会话中的行为就越一致。

在 GitHub.com、CLI 和 IDE 中使用自定义代理

一旦定义了自定义代理，你就不必局限于在一个地方使用它——无论 Copilot 的编码代理在哪里运行，它都会随你的代码一起移动。 在 GitHub.com 上，您可以向 Copilot 请求对问题或拉取请求执行任务时，从面板或代理选项卡中选择您的自定义代理。

在分配 GitHub 问题时，如果任务需要使用特定自定义代理的专门配置，则可以选择该代理而不是通用编码代理。 例如，可以分配一个专注于安全的代理配置文件来审查身份验证模块中的更改，而性能调优代理则负责后端服务中的热点路径。

通过 GitHub Copilot CLI，您可以使用斜杠命令选择加入特定的自定义代理，例如： /agent 或者通过在提示符或命令行参数中引用代理来实现。 这样，您的终端工作流程就能与您在浏览器或 IDE 中使用的相同角色保持一致。

每当 Copilot 编码代理代表您打开拉取请求时，GitHub 都会记录是哪个自定义代理完成了这项工作。 这有助于进行审计，并了解特定代理配置是否倾向于产生某些类型的变化或行为模式。

然后，可以通过聊天窗格直接在受支持的 IDE 中使用相同的代理配置文件，因此您可以根据手头的任务在规划、编辑、研究或合规性代理之间切换。 尽管某些 YAML 属性在 GitHub.com 和 IDE 环境中的行为可能略有不同，但整体配置文件仍然具有可移植性和一致性。

VS Code 中的本地代理：具有完整工作区上下文的交互式会话

VS Code 中的本地代理在您自己的计算机上针对您当前的工作区运行，并为您提供高度交互式、低延迟的对话。 他们拥有对您的文件、扩展程序、MCP 工具以及您配置的所有型号（包括自带钥匙 (BYOK) 型号）的一流访问权限。

这些本地会话非常适合需要立即进行来回沟通或与当前开发状态​​深度集成的任务。 这包括头脑风暴和规划、调试堆栈跟踪、响应代码检查错误、检查单元测试结果，以及任何涉及扩展贡献工具的工作流程。

每个本地代理聊天都会使用内置代理（代理、计划或咨询）之一，除非您选择自定义角色，并且您可以根据需求的变化在它们之间切换。 例如，您可以先使用 Ask 来了解部分代码库，然后切换到 Plan 来设计一个功能，最后使用 Agent 来实现它。

启动本地代理会话非常简单，只需从聊天代理选择器中选择“代理”，然后描述一个高层次的目标即可。 你可以说“使用 OAuth2 和 JWT 实现用户身份验证系统”或“为此项目设置 CI/CD”，代理将规划工作、运行工具并提出对整个解决方案的修改建议。

当代理程序运行时，VS Code 使用编辑器叠加层来显示建议的编辑，使用户能够轻松地浏览、查看、接受或拒绝这些编辑。 您还可以通过工具选择器调整代理可以调用​​的工具集，并根据需要扩展或限制其功能。

当您需要知识和指导，但又不希望文件自动更改时，“提问”角色尤其适用。 Ask 可以深入分析您的代码库，回答技术问题，并返回您可以通过“在编辑器中应用”操作手动应用的代码块，让您完全掌控代码。

与此同时，“计划”角色专门负责在编写任何代码之前制定结构化的实施计划。 这些计划可以移交给其他代理人，或者只是用作您自己工作的检查清单，确保您在深入实施之前已经考虑了依赖关系、数据模型和边界情况。

虽然之前存在用于多文件更改的“编辑模式”，但该模式已被弃用，取而代之的是功能更强大的代理角色。 您仍然可以通过特定的 VS Code 设置重新启用编辑模式，但在大多数情况下，代理角色是进行多文件重构和功能开发的推荐方法。

在会话期间，即使请求正在运行，您也可以随时发送后续提示。 您可以稍后对代理进行调整，在飞行途中改变方向，或者根据需要中断和控制代理，这使得整个过程感觉不像是一个批处理作业，而更像是一个协作式结对编程会话。

所有这些功能都与更广泛的代理生态系统相关联——您可以查看概览、管理会话、添加工具、连接 MCP 服务器以及定义自定义代理或钩子来强制执行策略和自动化生命周期事件。 当你投资于优秀的客服人员资料和工作流程时，同样的构建模块可以在聊天、CLI、IDE 和 GitHub 本身中获得回报。

Visual Studio 和 VS Code 中的自定义代理将所有这些部分整合在一起，使您的编码环境变成一组可重用的、以角色为中心的协作者，这些协作者了解您的技术栈、工具和标准，帮助团队更快地前进，同时保持质量和一致性。