---
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="/zh-Hant/docs/github-copilot/official/09-sdk-and-custom-agents/sdk-hooks" />
  <Card title="可觀測性" description="用 trace 觀察 sub-agent 和 tool call。" href="/zh-Hant/docs/github-copilot/official/09-sdk-and-custom-agents/observability" />
</Cards>
