自定义 Agent

自定义 Agent 适合把稳定、重复、专业化的流程产品化。普通 Chat、Agent mode 或 CLI 能解决的任务，不要过早做 custom 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:2px

2. Delegation 怎么工作

官方流程可以压成 5 步：

1. Runtime 根据用户 prompt 对照每个 agent 的 name 和 description。
2. 如果匹配，且 infer 没有设为 false，runtime 选择该 agent。
3. Sub-agent 在隔离上下文中运行，使用自己的 prompt 和工具集。
4. subagent.started、subagent.completed 等事件回传给 parent session。
5. 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 应该像团队角色：会什么、不能做什么、什么时候接手、失败后交给谁，都很清楚。

本章自检

1. 这个 agent 是否有明确职责和 owner？
2. description 是否足够让 runtime 正确选择？
3. 工具集是否最小化？
4. 是否需要 infer: false 防止自动调用？
5. 是否监听 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 官方事件流说明。

接下来去哪