make-custom-agent

创建自定义 Agent

本技能将指导你创建自定义 GitHub Copilot Agent——一个可通过 @ 调用的聊天参与者，为 Copilot 扩展特定领域的专业能力。自定义 Agent 与 Agent Skills 不同：技能提供按需加载的可复用指令，而 Agent 负责完整的对话交互，并可编排工具、调用 API 和维护自己的提示词策略。

何时不应使用

• 添加可复用、可调用的工作流——改用 Agent Skills（.agents/skills/）
• 添加后台编码规范——改用基于文件的指令（.github/instructions/）
• 为 Copilot 添加项目范围的上下文——改用 .github/copilot-instructions.md
• 创建可复用提示词——改用 .prompt.md

工作流

对于现有提案，应审核完整定义，而不只是工具：描述必须明确指出哪些自然语言请求应能发现该 Agent，正文必须补充根指令之外的领域知识，配套的评估必须能单独检验其贡献。将每项工具和行为都与用户预期的权限进行对照。禁止执行命令的审查者不得通过通配符工具、交接或其他方式获得命令执行或发布权限，即使工作流本身是只读的也不例外。

步骤 1：选择 Agent 类型

类型	位置	适用场景
声明式（提示词文件）	.github/agents/<name>.md	无需代码、由提示词驱动且可跨平台使用的简单 Agent
基于扩展（聊天参与者）	VS Code 扩展项目	需要完全控制、调用工具和访问 VS Code API
GitHub App（Copilot 扩展）	托管服务 + GitHub App	跨平台 Agent（github.com、VS Code、Visual Studio）

如果 Agent 只需要限定范围的系统提示词，且不需要自定义代码，请从声明式 Agent 开始。

步骤 2：创建声明式 Agent（提示词文件）

声明式 Agent 是 .github/agents/ 中的 Markdown 文件。VS Code 和 GitHub Copilot 会自动发现它们。

.github/agents/
└── <agent-name>.md        # Agent definition

模板：

---
name: my-agent
description: A short description of what this agent does and when to use it.
---

# <Agent Title>

You are an expert in <domain>. Your job is to:
- <behavior 1>
- <behavior 2>

## Guidelines

- <guideline 1>
- <guideline 2>

## Workflow

1. <step 1>
2. <step 2>

## Constraints

- <constraint 1>
- <constraint 2>

支持的 frontmatter 字段：

字段	必填	描述
name	是	小写，可使用连字符。用于 @ 提及。
description	是	说明 Agent 的功能及适用场景。会显示在参与者列表中。
target	否	目标环境：vscode 或 github-copilot（默认两者都适用）
tools	否	允许使用的工具或工具集列表
model	否	大模型名称或按优先级排列的模型数组
user-invocable	否	是否显示在 Agent 下拉菜单中（默认：true）
disable-model-invocation	否	是否禁止子 Agent 调用（默认：false）
mcp-servers	否	面向 GitHub Copilot 目标的 MCP 服务配置
metadata	否	用于其他任意元数据的键值映射。
argument-hint	否	引导用户交互的提示文本（仅限 VS Code）
agents	否	允许使用的子 Agent 列表（* 表示全部，[] 表示无，仅限 VS Code）
handoffs	否	后续 Agent 转接列表（仅限 VS Code）

指令提示：

• 使用 Markdown 链接引用其他文件
• 使用 #tool:<tool-name> 语法引用工具
• 明确说明 Agent 的行为和约束

步骤 3：配置工具

指定 Agent 可以使用哪些工具：

tools:
  - search              # Built-in tool
  - fetch               # Built-in tool
  - codebase            # Tool set
  - myServer/*          # All tools from MCP server

常见的工具配置模式：

• 只读 Agent：['search', 'fetch', 'codebase']
• 完整编辑 Agent：['*'] 或指定的编辑工具
• 专用 Agent：挑选特定工具

步骤 4：添加交接（可选，仅限 VS Code）

配置转接到其他 Agent：

handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Implement the plan outlined above.
    send: false
    model: GPT-5.2 (copilot)

交接字段：

• label：显示给用户的按钮文本
• agent：目标 Agent 标识符
• prompt：为目标 Agent 预填的提示词
• send：自动提交提示词（默认：false）
• model：交接时可选的模型覆盖设置

步骤 5：创建基于扩展的聊天参与者（仅限 VS Code）

如需完全掌控，请实现一个带有聊天参与者的 VS Code 扩展：

1. 在 package.json 中定义参与者：

"contributes": {
    "chatParticipants": [
        {
            "id": "my-extension.my-agent",
            "name": "my-agent",
            "fullName": "My Agent",
            "description": "Short description shown in chat input",
            "isSticky": false,
            "commands": [
                {
                    "name": "explain",
                    "description": "Explain the selected code"
                }
            ]
        }
    ]
}

2. 在 extension.ts 中注册并实现请求处理程序：

export function activate(context: vscode.ExtensionContext) {
    const agent = vscode.chat.createChatParticipant('my-extension.my-agent', handler);
    agent.iconPath = vscode.Uri.joinPath(context.extensionUri, 'icon.png');
}

const handler: vscode.ChatRequestHandler = async (
    request: vscode.ChatRequest,
    context: vscode.ChatContext,
    stream: vscode.ChatResponseStream,
    token: vscode.CancellationToken
) => {
    const model = request.model;
    const messages = [
        vscode.LanguageModelChatMessage.User(request.prompt)
    ];
    const response = await model.sendRequest(messages, {}, token);
    for await (const fragment of response.text) {
        stream.markdown(fragment);
    }
};

3. 在 package.json 中声明扩展依赖项：

"extensionDependencies": ["github.copilot-chat"]

4. 添加工具调用（可选）

Agent 可以调用由其他扩展注册的语言模型工具：

const tools = vscode.lm.tools.filter(tool => tool.tags.includes('my-domain'));
const result = await chatUtils.sendChatParticipantRequest(request, context, {
    prompt: 'You are an expert in <domain>.',
    tools,
    responseStreamOptions: { stream, references: true, responseText: true }
}, token);
return await result.result;

步骤 6：创建 GitHub App（Copilot 扩展），以便在多个界面中使用（可选）

如果 Agent 应同时在 GitHub.com、Visual Studio、JetBrains 和 VS Code 中使用，请实现一个作为 Copilot 扩展的 GitHub App。该应用会注册一个 webhook 端点，接收聊天请求，并将响应流式传回。

关键注意事项：

• GitHub App 必须安装在用户的账户或组织中
• 响应通过服务器发送事件（SSE）进行流式传输
• 完整集成指南请参阅 GitHub Copilot 扩展文档
• 对于 VS Code 专属功能（访问编辑器、文件树、命令按钮），优先使用基于扩展的参与者

步骤 7：编写 harness 评估

创建 eng/harness-evaluation/agents/<agent-id>/eval.yaml，并遵循 eng/harness-evaluation/README.md。

• 仅在 eval 根目录的 agent_environment.files 中声明 Agent 文件；实验会将其从对照组中移除。
• 使用真实的刺激来测试 Agent 特有的行为，但不要在提示词中说明预期的诊断结果或实现方式。
• 结合确定性的输出检查、重点语义评分标准、有界资源、令牌评分，以及已提交的评分阈值。
• eval 名称和从目录派生的组件 ID 必须与 Agent ID 相同。

步骤 8：验证

创建或修改 Agent 后，请确认：

• name 为小写，使用连字符（不含空格），且唯一
• description 清楚说明 Agent 的功能以及何时调用它
• Frontmatter YAML 有效（无语法错误）
• 声明式 Agent 文件位于 .github/agents/
• 工具列表仅包含可用工具
• 基于扩展的 Agent：参与者 ID 在 package.json 和 createChatParticipant 调用中一致
• Agent 不会与内置 Agent（@workspace、@vscode、@terminal）的功能重复
• 交接 Agent 的名称与现有 Agent 相匹配
• Agent 指令不包含机密、令牌或内部 URL
• 配套的 harness eval 仅针对此 Agent，并且旨在有效区分处理组与对照组

常见问题

问题	解决方案
Agent 名称与内置参与者冲突	使用唯一前缀（域名）
描述过于模糊	加入用户自然会说出的具体关键词
系统提示词过长	只保留必要行为的指令；将参考资料移至 Agent Skills
Agent 需要 VS Code API，但采用声明式方式编写	改用基于扩展的参与者
不必要地使用 isSticky: true	仅当 Agent 默认应在不同轮次间持续存在时才设置 sticky
没有针对 github.copilot-chat 的 extensionDependencies	添加该项；否则贡献点可能不可用
Agent 意外地作为子 Agent 被调用	设置 disable-model-invocation: true
子 Agent 出现在下拉列表中	设置 user-invocable: false

参考资料

• VS Code 聊天参与者 API
• VS Code AI 扩展性概述
• VS Code 扩展示例 – chat-sample
• GitHub Copilot 扩展文档
• GitHub Copilot 自定义 Agent 配置
• Agent Skills 规范
• 相关仓库技能：make-skill 和 make-instructions