---
title: "自定义 Agent"
description: "解释 Copilot SDK custom agents、sub-agent delegation、工具隔离、MCP 绑定和失败处理。"
verifiedAt: "2026-05-06"
---

自定义 Agent 适合把稳定、重复、专业化的流程产品化。普通 Chat、Agent mode 或 CLI 能解决的任务，不要过早做 custom agent。

> [!IMPORTANT]
> 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 配置。

```mermaid
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 不能进入生产流程。

<details>
<summary>深读：custom agent 不应该是万能助手</summary>

一个 agent 越万能，越难限制工具、解释行为和处理失败。自定义 agent 的价值在于收窄职责，而不是换一个更响亮的名字。

好的 custom agent 应该像团队角色：会什么、不能做什么、什么时候接手、失败后交给谁，都很清楚。
</details>

## 本章自检

1. 这个 agent 是否有明确职责和 owner？
2. `description` 是否足够让 runtime 正确选择？
3. 工具集是否最小化？
4. 是否需要 `infer: false` 防止自动调用？
5. 是否监听 `subagent.failed` 并有降级策略？

通过标准：每个 custom agent 都有职责、工具边界、失败处理和验证任务。

## 官方来源

- [Custom agents and sub-agent orchestration](https://docs.github.com/en/copilot/how-tos/copilot-sdk/use-copilot-sdk/custom-agents) —— GitHub 官方 custom agents、delegation、events 和工具隔离说明。
- [Using Copilot SDK with MCP servers](https://docs.github.com/en/copilot/how-tos/copilot-sdk/use-copilot-sdk/mcp-servers) —— GitHub 官方 SDK + MCP 入口。
- [Streaming events with Copilot SDK](https://docs.github.com/en/copilot/how-tos/copilot-sdk/use-copilot-sdk/streaming-events) —— GitHub 官方事件流说明。

## 接下来去哪

<Cards>
  <Card title="SDK Hooks" description="用 hooks 给 custom agents 增加权限和审计边界。" href="/docs/github-copilot/official/09-sdk-and-custom-agents/sdk-hooks" />
  <Card title="可观测性" description="用 trace 观察 sub-agent 和 tool call。" href="/docs/github-copilot/official/09-sdk-and-custom-agents/observability" />
</Cards>
