自定義 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 官方事件流說明。

接下來去哪