---
title: "SDK 與自定義 Agent"
description: "按 GitHub 官方 SDK 文件梳理 Copilot SDK、custom agents、hooks 和 OpenTelemetry 可觀測性。"
verifiedAt: "2026-05-06"
---

Copilot SDK 不是普通 API wrapper（API 包裝層）。它讓你把 Copilot 變成應用裡的 agent runtime（代理執行時）：建立 session、註冊工具、監聽事件、定義 custom agents、插入 hooks、接入 OpenTelemetry。

這一組解決一個判斷：什麼時候繼續用 IDE Chat / Agent mode 就夠，什麼時候應該做成 SDK 應用或自定義 agent。

> [!WARNING]
> GitHub 官方文件標註 Copilot SDK 目前處於 public preview。生產化前必須保留版本、日誌、回復和許可權邊界。

## 1. 能力地圖

```mermaid
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:2px
```

## 2. 本組頁面

<Cards>
  <Card title="Copilot SDK 入門" description="理解 public preview、CLI 認證、CopilotClient、session 和 streaming。" href="/zh-Hant/docs/github-copilot/official/09-sdk-and-custom-agents/sdk-getting-started" />
  <Card title="自定義 Agent" description="用 customAgents 定義專業 agent，並理解 sub-agent delegation。" href="/zh-Hant/docs/github-copilot/official/09-sdk-and-custom-agents/custom-agents" />
  <Card title="SDK Hooks" description="用 hooks 做許可權、審計、上下文注入和錯誤處理。" href="/zh-Hant/docs/github-copilot/official/09-sdk-and-custom-agents/sdk-hooks" />
  <Card title="可觀測性" description="用 OpenTelemetry、trace context 和 tool spans 觀察 agent 行為。" href="/zh-Hant/docs/github-copilot/official/09-sdk-and-custom-agents/observability" />
</Cards>

## 3. 什麼時候值得上 SDK

適合：

- 把 Copilot 嵌進自己的產品或內部平臺。
- 控制工具、許可權、事件、hooks 和 trace。
- 構建專業 agent，而不是隻寫 prompt。
- 把 agent 行為接入審計、監控和業務日誌。

暫時不要：

- 只是讓 Copilot 改一個儲存庫。
- 只是團隊內部多寫幾條規則。
- 沒有 owner、日誌、許可權邊界和回復。
- 還沒有證明預設 Copilot 入口不夠用。

## 4. 推薦落地順序

1. 先用 IDE Agent mode 或 Copilot CLI 跑通流程。
2. 再把穩定重複任務抽象成 SDK session。
3. 註冊最小工具集，不要先接生產寫介面。
4. 用 hooks 限制工具和記錄事件。
5. 接 OpenTelemetry，再小範圍試點。
6. 最後才做 custom agents 和 sub-agent orchestration。

<details>
<summary>深讀：SDK 化會放大工程責任</summary>

預設 Copilot 出錯時，通常是一個開發者會話的問題。SDK 應用出錯時，可能影響使用者、佇列、工具、內部 API 和成本。

因此 SDK 應用必須按產品工程治理：許可權、日誌、告警、回復、版本和成本都要跟上。
</details>

## 本組自檢

1. 是否證明預設入口不夠用？
2. 是否知道 SDK 應用會呼叫哪些工具和外部系統？
3. 是否有 hooks 攔截危險工具和記錄事件？
4. 是否有 trace 可以定位 session、tool call 和失敗？

透過標準：SDK 應用不是 demo，而是有許可權、觀測、試點和回復的受控 agent。

## 官方來源

- [Getting started with Copilot SDK](https://docs.github.com/en/copilot/how-tos/copilot-sdk/sdk-getting-started) —— GitHub 官方 SDK quickstart。
- [Custom agents and sub-agent orchestration](https://docs.github.com/en/copilot/how-tos/copilot-sdk/use-copilot-sdk/custom-agents) —— GitHub 官方 custom agents 和 sub-agent 流程。
- [Quickstart for hooks](https://docs.github.com/en/copilot/how-tos/copilot-sdk/use-hooks/quickstart) —— GitHub 官方 SDK hooks。
- [OpenTelemetry instrumentation for Copilot SDK](https://docs.github.com/en/copilot/how-tos/copilot-sdk/observability/opentelemetry) —— GitHub 官方可觀測性說明。

## 接下來去哪

<Cards>
  <Card title="Copilot SDK 入門" description="先跑通最小 session。" href="/zh-Hant/docs/github-copilot/official/09-sdk-and-custom-agents/sdk-getting-started" />
  <Card title="實戰 Playbooks" description="SDK 之前也要會判斷真實任務是否值得產品化。" href="/zh-Hant/docs/github-copilot/official/10-practical-playbooks" />
</Cards>
