为 GitHub Copilot CLI 创建和使用自定义智能体

介绍

Custom agents 使你能够为特定任务定制 Copilot 的专业知识。

当您提示 Copilot 执行任务时，如果 custom agents 确定代理的专业知识非常适合该任务，那么它可能会选择使用您的 Copilot。

当主代理将工作委托给custom agent时，该工作由具有其自己的上下文窗口的子代理执行。 这使专家能够专注于其分配的任务，而不会使主代理的上下文混乱。 还可以直接为会话选择一个 custom agent 。

有关详细信息，请参阅“自定义代理”。

创建 custom agent

每个 custom agent 文件都由扩展名为 .agent.md Markdown 文件定义。 可以自行创建这些文件，也可以从 CLI 中添加这些文件，如以下步骤中所述。

1. 在交互模式下，输入 /agent。

2. 按 N 创建新代理。

3. 选择在存储库或主目录中创建 custom agent 的选项：

   • Project （.github/agents/）

   • 用户 （~/.copilot/agents/）

   注意

   如果个人和存储库 custom agents 具有相同的 ID，则使用个人代理。 对于位于 agents 目录根目录中的代理，ID 是去掉 .agent.md 或 .md 扩展名后的文件名。 可选 name 字段不会影响重复数据删除。 具有相同 name 但 ID 不同的代理程序都会被加载，但如果某个 --agent 值匹配多个 ID 或 name，CLI 会使用优先级最高的匹配项。

4. 选择是否让 Copilot 创建 custom agent 文件，或自行创建。

选项 1：使用 Copilot

输入要创建的代理的详细信息。 描述代理的专业知识以及何时应使用代理。 Copilot 将采用你输入的说明，并使用它为你编写代理配置文件。

例如，可以输入：

I am a security expert. I check code files thoroughly for potential security issues. Use me whenever a security review/check/audit is requested for one or more code files, or when the word "seccheck" is used in a prompt in reference to code files.

I will identify potential problems, such as code that:

- Exposes secrets or credentials
- Allows cross-site scripting
- Allows SQL injection
- Contains vulnerable dependencies
- Allows authentication to be bypassed

If any problems are identified, create a single GitHub issue in this repository on GitHub.com with details of problems, giving full details of each issue, including, but not limited to, risk level and recommended fix.

生成完初始代理配置文件后 Copilot ，会显示以下选项：

• 继续
• 查看内容
• 重试
• 退出

如果选择查看内容，则会在默认编辑器中打开代理文件。 在 CLI 中继续执行代理创建过程之前，可以根据需要查看和进行更改。

若要完成创建过程，请选择 “继续”。

选项 2：手动创建代理配置文件

选择自行创建代理文件时，将引导你完成一系列提示，以填写创建代理配置文件所需的信息。

1. 输入代理的名称。 输入的名称是列出可用代理时显示的名称。 此版本的版本将用作代理文件的名称，例如，如果输入“安全专家”，代理文件将命名 security-expert.agent.md。

   提示

   为了便于在以编程方式使用 custom agent 时使用，建议选择一个名称，只包含小写字母和连字符。

2. 输入说明，说明此代理具有哪些专业知识，以及何时应使用它。

3. 输入代理的操作说明，包括任何特定的准则、应执行的操作或应遵循的约束。

4. 选择你 custom agent 应有权访问的工具。

   默认情况下， custom agents 有权访问所有工具。 如果限制代理的访问，代理文件中将添加一个tools规范。

5. 请重启 CLI，以加载新的 custom agent。

使用 custom agent

Custom agents 可通过以下方式使用：

• 斜杠命令

  以交互模式输入 /agent ，然后从可用 custom agents列表中进行选择。 然后输入一个提示，将其传递给所选代理。

  注意

  此列表中不包括 CLI 的默认代理。 有关默认代理的详细信息，请参阅 自定义代理。

• 显式指令

  告知 Copilot 使用特定代理。 例如：

  Use the security-auditor agent on all files in the /src/app directory
  

• 按推理

  使用提示符根据智能体文件中的描述触发特定智能体的使用。 例如：

  Check all TypeScript files in or under the src directory for potential security problems
  

  或 （其中“seccheck”定义为代理配置文件中的触发词）：

  seccheck /src/app/validator.go
  

Copilot 将自动推断要使用的代理。

• 通过编程

  通过命令行选项指定要使用的 custom agent。 例如：

  copilot --agent security-auditor --prompt "Check /src/app/validator.go"
  

  在此示例中， security-auditor 是 . custom agent的 ID。 ID 由文件名派生，不含 .md 或 .agent.md 扩展名。 在这种情况下，文件的路径为 agents/security-auditor.md 或 agents/security-auditor.agent.md。 如果文件位于 ID 中的子目录中 agents，则子目录名称包含在 ID 中，目录分隔符替换为 --。 因此，位于 agents/security/security-auditor.agent.md 的代理文件其 ID 为 security--security-auditor。 或者，可以使用字段的值 name 而不是 ID，将其括在引号中。 例如，--agent "Security Auditor"。

将重点任务委派给特定模型

可以将custom agent配置为使用特定模型。

如果要将小型、定义明确的任务委托给使用本地托管模型的 custom agent，而主会话则使用基于云的模型，这尤其有用。 例如，此方法允许将单文件更改或重点测试修复委托给使用本地模型的 custom agent，然后让主代理查看结果。

首先，将本地托管模型添加到 CLI。 请参阅“将 LLM 模型添加到 GitHub Copilot CLI”。

1. 使用以下内容创建 ~/.copilot/agents/local-coder.agent.md ：

   ---
   name: local-coder
   description: >
     Use for small, well-defined coding tasks, such as a
     single-file change or a focused test fix.
   model: LOCAL-PROVIDER/LOCAL-MODEL
   model-policy: required
   tools: ["read", "grep", "glob", "edit", "execute"]
   strict-tools-list: true
   include-custom-instructions: true
   ---
   
   Complete only the requested task. Inspect the relevant
   code, make the smallest correct change, and run focused
   checks. Report what changed and any remaining issues.
   

2. 用本地模型的提供程序限定 ID 替换 LOCAL-PROVIDER/LOCAL-MODEL，而不是其显示名称。 对于 providers.json 中的模型，请合并模型条目的 provider 和 id 值，并用正斜杠分隔。 例如，"provider": "local" 和 "id": "qwen3:8b" 可为你提供 local/qwen3:8b。

model-policy: required 要求使用已配置的模型，而不是将其视为首选项。

strict-tools-list: true 将代理限制为列出的工具组，而无需添加常用的默认工具。

include-custom-instructions: true 使存储库的说明持续对子代理生效。

1. 重启 CLI 以加载代理。 在使用云模型的会话中，显式委托范围受限的任务：

   Use the local-coder agent to add an empty-input test for
   parseConfig in src/config.test.ts. Do not change other
   files. Then review the result in the main session.
   

   本地模型运行委托的任务，但主代理仍会收到结果。 这不会使整个会话变为本地或离线状态。

将存储库的自定义说明应用于 custom agent

自定义指令文件（例如 .github/copilot-instructions.md、AGENTS.md 和 CLAUDE.md）会告知 Copilot 如何在你的代码库中工作。 有关详细信息，请参阅“为GitHub Copilot添加存储库自定义说明”。

当 custom agent 将你的 Copilot 作为子代理运行时——以处理较大任务的一部分——该子代理默认不会遵循你的代码仓库中的自定义指令。 这让子代理专注于它给出的特定任务。

如果您希望某个子代理遵循代码仓库的约定（例如，用于审查或编辑代码的代理），请将 include-custom-instructions: true 添加到该代理文件的前置元数据中：

---
name: RepoAwareReviewer
description: Reviews a change against this repository's conventions
tools: ["*"]
include-custom-instructions: true
---

Review the change and flag anything that violates the repository's conventions.

有关详细信息，包括此设置如何与 --no-custom-instructions 选项交互，请参阅 GitHub Copilot CLI 命令参考。

延伸阅读

• 比较Copilot自定义功能
• 自定义代理配置
• GitHub Copilot CLI 命令参考
• 自定义智能体 — 精选的示例集合