官方教程中文版SDK 與自定義 Agent
SDK 與自定義 Agent
按 GitHub 官方 SDK 文件梳理 Copilot SDK、custom agents、hooks 和 OpenTelemetry 可觀測性。
Copilot SDK 不是普通 API wrapper（API 包裝層）。它讓你把 Copilot 變成應用裡的 agent runtime（代理執行時）：建立 session、註冊工具、監聽事件、定義 custom agents、插入 hooks、接入 OpenTelemetry。
這一組解決一個判斷：什麼時候繼續用 IDE Chat / Agent mode 就夠，什麼時候應該做成 SDK 應用或自定義 agent。
GitHub 官方文件標註 Copilot SDK 目前處於 public preview。生產化前必須保留版本、日誌、回復和許可權邊界。
1. 能力地圖
flowchart TD
Need["業務需要 AI agent"] --> Simple{"預設 Copilot 入口能解決?"}
Simple -->|是| Default["IDE / CLI / Cloud Agent"]
Simple -->|否| SDK["Copilot SDK"]
SDK --> Session["Session"]
SDK --> Tools["Tools / MCP"]
SDK --> Agents["Custom agents"]
SDK --> Hooks["Hooks"]
SDK --> Trace["OpenTelemetry"]
Agents --> Sub["Sub-agent delegation"]
Hooks --> Control["許可權 / 審計 / 錯誤處理"]
style SDK fill:#dbeafe,stroke:#2563eb,stroke-width:2px
style Hooks fill:#fef3c7,stroke:#d97706,stroke-width:2px
style Trace fill:#dcfce7,stroke:#16a34a,stroke-width:2px2. 本組頁面
Copilot SDK 入門
理解 public preview、CLI 認證、CopilotClient、session 和 streaming。
自定義 Agent
用 customAgents 定義專業 agent，並理解 sub-agent delegation。
SDK Hooks
用 hooks 做許可權、審計、上下文注入和錯誤處理。
可觀測性
用 OpenTelemetry、trace context 和 tool spans 觀察 agent 行為。
3. 什麼時候值得上 SDK
適合：
- 把 Copilot 嵌進自己的產品或內部平臺。
- 控制工具、許可權、事件、hooks 和 trace。
- 構建專業 agent，而不是隻寫 prompt。
- 把 agent 行為接入審計、監控和業務日誌。
暫時不要：
- 只是讓 Copilot 改一個儲存庫。
- 只是團隊內部多寫幾條規則。
- 沒有 owner、日誌、許可權邊界和回復。
- 還沒有證明預設 Copilot 入口不夠用。
4. 推薦落地順序
- 先用 IDE Agent mode 或 Copilot CLI 跑通流程。
- 再把穩定重複任務抽象成 SDK session。
- 註冊最小工具集，不要先接生產寫介面。
- 用 hooks 限制工具和記錄事件。
- 接 OpenTelemetry，再小範圍試點。
- 最後才做 custom agents 和 sub-agent orchestration。
深讀：SDK 化會放大工程責任
預設 Copilot 出錯時，通常是一個開發者會話的問題。SDK 應用出錯時，可能影響使用者、佇列、工具、內部 API 和成本。
因此 SDK 應用必須按產品工程治理：許可權、日誌、告警、回復、版本和成本都要跟上。
本組自檢
- 是否證明預設入口不夠用？
- 是否知道 SDK 應用會呼叫哪些工具和外部系統？
- 是否有 hooks 攔截危險工具和記錄事件？
- 是否有 trace 可以定位 session、tool call 和失敗？
透過標準：SDK 應用不是 demo，而是有許可權、觀測、試點和回復的受控 agent。
官方來源
- Getting started with Copilot SDK —— GitHub 官方 SDK quickstart。
- Custom agents and sub-agent orchestration —— GitHub 官方 custom agents 和 sub-agent 流程。
- Quickstart for hooks —— GitHub 官方 SDK hooks。
- OpenTelemetry instrumentation for Copilot SDK —— GitHub 官方可觀測性說明。