自定义 Agent
解释 Copilot SDK custom agents、sub-agent delegation、工具隔离、MCP 绑定和失败处理。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| Custom agents | 自定义代理 | 用 SDK 定制专用 agent。 |
| 能力边界 | scope | agent 能调什么、不能做什么。 |
| 复用 | reuse | 把 agent 用到多个场景。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你设计一个职责清晰、边界安全的自定义 Copilot agent。
你是 Copilot 自定义 agent 设计顾问。
【角色】
Copilot 自定义 agent 设计顾问，按最小够用、安全优先的原则给可落地方案，每条结论都落到能照做的步骤或示例，不停留在空泛建议。
【输入】
- 这个 agent 要解决的任务：___
- 它需要哪些能力：___
- 绝不能做的操作：___
- 使用场景：___
- 经验水平：___
【工作流程】
1. 明确 agent 的单一职责
2. 限定它的能力边界
3. 设计输入输出和确认点
4. 说明怎么复用
5. 给验证
【输出规范】
▌一、单一职责
▌二、能力边界
▌三、输入输出 / 确认点
▌四、复用 + 验证
【硬约束】
- 职责单一，不做万能 agent
- 高危能力默认审批
- 外部调用守信任边界
- 不要替我臆测情况或编造不存在的功能，信息不全先问清
- 不确定的配置或权限一律以官方文档为准，禁止照搬过时写法自定义 Agent 适合把稳定、重复、专业化的流程产品化。普通 Chat、Agent mode 或 CLI 能解决的任务，不要过早做 custom agent。
Custom agent 是带名字、system prompt、工具范围和可选 MCP servers 的专业 agent 定义；parent runtime 可以把符合条件的任务委派给它作为 sub-agent（子代理）。把它想成"团队里的专科同事"——会什么、不会什么、什么时候找它，都很清楚。
1. 官方定义
GitHub 官方文档说明，custom agents 是挂到 SDK session 上的轻量 agent definitions。每个 agent 可以有：
name：唯一标识。displayName：人类可读名称。description：帮助 runtime 判断何时选它。tools：限制 agent 可用工具。prompt：该 agent 的 system prompt。mcpServers：该 agent 专属 MCP server 配置。
flowchart TD
Session["Parent session"] --> Intent["用户任务"]
Intent --> Match["runtime 匹配 agent"]
Match --> Researcher["researcher sub-agent"]
Match --> Editor["editor sub-agent"]
Researcher --> ReadOnly["read-only tools"]
Editor --> EditTools["edit / bash 等受限工具"]
Researcher --> Events["subagent events"]
Editor --> Events
Events --> Parent["结果回到 parent session"]
style Researcher fill:#dcfce7,stroke:#16a34a,stroke-width:2px
style Editor fill:#fef3c7,stroke:#d97706,stroke-width:2px2. Delegation 怎么工作
官方流程可以压成 5 步：
- Runtime 根据用户 prompt 对照每个 agent 的
name和description。 - 如果匹配，且
infer没有设为false，runtime 选择该 agent。 - Sub-agent 在隔离上下文中运行，使用自己的 prompt 和工具集。
subagent.started、subagent.completed等事件回传给 parent session。- Sub-agent 的输出被整合回 parent agent 的最终响应。
如果只希望某个 agent 被显式调用，可以设置 infer: false。
3. 什么时候做 custom agent
适合：
- 安全审计 agent：只读工具、漏洞清单、风险报告。
- 测试 agent：只改测试文件，运行指定测试命令。
- 文档 agent：只改 docs，检查链接和 frontmatter。
- 迁移 agent：按目录分阶段处理大规模升级。
- 研究 agent：只读代码和 issue，不允许写文件。
不适合：
- 单次修 bug。
- 模糊的“帮我优化项目”。
- 没有工具边界的全能 agent。
- 还没有真实重复任务的试验性 prompt。
4. 工具和 MCP 要分层
每个 agent 都应该有最小工具集：
- 研究 agent：
grep、glob、view。 - 编辑 agent：
view、edit，谨慎开放bash。 - 发布 agent：只给发布前检查和构建工具，不给生产部署权限。
- 安全 agent：只读扫描优先，写操作必须审批。
如果某个 agent 需要外部系统，再给它绑定专属 MCP server。不要把所有 MCP server 放到 parent session 里。
5. 必须监听失败事件
官方文档特别提醒，sub-agents 可能失败。应用应该监听 subagent.failed，并决定：
- 展示错误。
- 重试。
- 降级回 parent agent。
- 停止任务并要求人工处理。
- 写入日志和 trace。
没有失败处理的 custom agent 不能进入生产流程。
深读：custom agent 不应该是万能助手
一个 agent 越万能，越难限制工具、解释行为和处理失败。自定义 agent 的价值在于收窄职责，而不是换一个更响亮的名字。
好的 custom agent 应该像团队角色：会什么、不能做什么、什么时候接手、失败后交给谁，都很清楚。
本章自检
- 这个 agent 是否有明确职责和 owner？
description是否足够让 runtime 正确选择？- 工具集是否最小化？
- 是否需要
infer: false防止自动调用？ - 是否监听
subagent.failed并有降级策略？
通过标准：每个 custom agent 都有职责、工具边界、失败处理和验证任务。
官方来源
- Custom agents and sub-agent orchestration —— GitHub 官方 custom agents、delegation、events 和工具隔离说明。
- Using Copilot SDK with MCP servers —— GitHub 官方 SDK + MCP 入口。
- Streaming events with Copilot SDK —— GitHub 官方事件流说明。