Copilot SDK 的自定义 Agent 是"轻量级 Agent 定义，附加到会话上"。每个 Agent 有独立的系统 Prompt 和工具集，SDK 运行时根据用户请求自动路由到最合适的 Agent，或者手动指定。Agent 活动通过事件流实时反馈，便于 UI 可视化。

GitHub Copilot SDK 自定义 Agent：构建专项 AI 代理

什么是自定义 Agent

自定义 Agent 是"附加到 Session 的轻量级 Agent 定义"，每个 Agent 有：

• 系统 Prompt：定义这个 Agent 的角色和行为
• 工具集：限定这个 Agent 可以使用哪些工具（避免权限过大）
• 数据源：这个 Agent 可以访问的上下文数据

多个 Agent 可以同时注册到一个 Session，SDK 运行时会根据用户请求的内容自动委派给最合适的 Agent。

定义和注册 Agent

import { createSession } from '@github/copilot-sdk'

const session = await createSession()

// 定义一个代码审查 Agent
session.registerAgent({
  name: 'code-reviewer',
  description: '负责代码审查，关注安全漏洞、性能问题和代码质量',
  systemPrompt: `你是一个专业的代码审查员。
  审查重点：
  - SQL 注入和 XSS 等安全漏洞
  - N+1 查询等性能问题
  - 函数长度和代码可读性
  审查结果使用 [CRITICAL/HIGH/MEDIUM/LOW] 标注严重程度。`,
  tools: ['read_file', 'search_code']  // 只允许只读工具
})

// 定义一个修复 Bug 的 Agent
session.registerAgent({
  name: 'bug-fixer',
  description: '负责诊断和修复 Bug，会读取错误信息、查找相关代码并实施修复',
  systemPrompt: `你是一个 Bug 修复专家。
  工作流程：
  1. 先读取错误信息和堆栈跟踪
  2. 找到相关代码文件
  3. 分析根因
  4. 实施最小改动的修复
  5. 更新或新增对应测试用例`,
  tools: ['read_file', 'write_file', 'run_tests', 'search_code']
})

自动路由

注册多个 Agent 后，当用户发送请求时，SDK 根据请求内容自动选择最合适的 Agent：

// 用户说"审查这段代码" → 自动路由到 code-reviewer
// 用户说"这个 TypeError 怎么修" → 自动路由到 bug-fixer
await session.sendPrompt({
  messages: [{ role: 'user', content: '帮我审查 auth/login.ts' }]
})

手动指定 Agent

如果需要精确控制使用哪个 Agent：

await session.sendPrompt({
  messages: [{ role: 'user', content: '修复这个 Bug' }],
  agent: 'bug-fixer',    // 直接指定 Agent 名称
  infer: false           // 禁用自动推断，强制使用指定 Agent
})

监听 Agent 活动事件

通过事件流追踪 Agent 的执行过程，适合构建 UI 显示进度：

// Agent 开始执行
session.on('subagent.started', (event) => {
  console.log(`Agent "${event.agentName}" 开始处理...`)
})

// Agent 正在使用工具
session.on('tool.called', (event) => {
  console.log(`[${event.agentName}] 调用工具: ${event.toolName}`)
})

// Agent 完成
session.on('subagent.completed', (event) => {
  console.log(`Agent "${event.agentName}" 完成`)
})

// 父 Session 收到子 Agent 的文字输出
session.on('assistant.message_delta', (event) => {
  process.stdout.write(event.delta)
})

最佳实践

1. 写清楚 description：SDK 用 description 做路由决策，描述越精确，路由越准确。

2. 工具集最小权限原则：只读 Agent（代码审查、分析）只给读文件工具；写入 Agent（Bug 修复、重构）才给写文件工具。

3. 读写 Agent 配对：先用只读 Agent 分析问题，再用写入 Agent 实施修复，避免 Agent 在没有分析清楚前就开始修改代码。

// 推荐的配对模式
session.registerAgent({ name: 'analyzer', tools: ['read_file', 'search_code'], ... })
session.registerAgent({ name: 'implementer', tools: ['read_file', 'write_file'], ... })

与 Claude Code Agent SDK 的对比

Claude Code Agent SDK（Anthropic）提供类似的多 Agent 编排能力；Copilot SDK 的 Agent 系统更轻量，适合直接集成到现有 GitHub 工作流中，对 GitHub 原生工具（仓库、PR、Issue）有更好的原生支持。

常见问题

Q: 一个 Session 能注册多少个 Agent？

A: 没有固定上限，但 Agent 数量太多会增加 SDK 的路由推断成本（每次推断消耗 token）。建议 3~7 个，覆盖核心场景即可。

Q: Agent 可以调用另一个 Agent 吗？

A: 可以。SDK 支持 Agent 嵌套调用（subagent），但需要在外层 Agent 的工具配置中显式声明可以调用哪些内层 Agent。

Q: 如何调试 Agent 路由是否正确？

A: 监听 subagent.started 事件，打印 event.agentName，确认每次请求确实路由到了预期的 Agent。如果路由不准，修改 Agent 的 description 字段，让它更精确地描述适用场景。