---
title: "Copilot SDK 入門"
description: "說明 Copilot SDK 的 public preview 邊界、認證方式、安裝、session、sendAndWait 和 streaming。"
verifiedAt: "2026-05-06"
---

Copilot SDK 入門的重點不是 hello world，而是理解執行邊界：SDK 透過 Copilot CLI 認證和連線 Copilot，用 `CopilotClient` 建立 session，然後傳送 prompt、監聽事件、管理生命週期——SDK 不會自己管 token，也不會自己管會話狀態。

> [!NOTE]
> GitHub 官方文件說明，Copilot SDK 當前是 public preview。教程中的程式碼結構要跟官方文件核對，生產化前要鎖版本並準備回復。

## 1. 官方 quickstart 關鍵點

官方 quickstart 的基礎事實：

- Copilot SDK 可用於所有 Copilot plans。
- 當前處於 public preview。
- Node.js 需要 18 或更高版本。
- 認證依賴已安裝並認證的 GitHub Copilot CLI。
- JavaScript/TypeScript 包是 `@github/copilot-sdk`。
- 示例透過 `CopilotClient`、`createSession`、`sendAndWait` 傳送第一條訊息。

```mermaid
flowchart TD
    Node["Node.js 18+"] --> CLI["安裝並認證 Copilot CLI"]
    CLI --> Package["@github/copilot-sdk"]
    Package --> Client["new CopilotClient"]
    Client --> Session["createSession"]
    Session --> Send["sendAndWait / streaming"]
    Send --> Stop["client.stop"]

    style CLI fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Session fill:#dbeafe,stroke:#2563eb,stroke-width:2px
```

## 2. 最小程式碼結構

```ts
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();

const session = await client.createSession({
  model: "gpt-4.1",
});

const response = await session.sendAndWait({
  prompt: "What is 2 + 2?",
});

console.log(response?.data.content);
await client.stop();
```

這段程式碼裡要理解 3 個物件：

- `CopilotClient()`：管理和 Copilot CLI 的連線。
- `createSession()`：建立一次會話，並指定模型等配置。
- `sendAndWait()`：傳送 prompt 並等待完整響應。

## 3. 什麼時候用 streaming

長回答或互動式 UI 不應該一直等待完整響應。官方 quickstart 展示了 streaming session，並監聽事件：

- `assistant.message_delta`：響應增量。
- `session.idle`：響應結束，會話可接收下一條訊息。

適合 streaming：

- Web UI 即時輸出。
- 長文件生成。
- 批次任務進度展示。
- 使用者需要看到 agent 正在工作。

後臺 job 更需要 trace、日誌和可重試狀態，不一定需要逐字 streaming。

## 4. 入門時先別做的事

不要一上來就：

- 接生產寫介面。
- 註冊大量工具。
- 寫複雜 custom agents。
- 把 SDK 示例直接部署成服務。
- 忽略 `client.stop()` 和會話生命週期。

先做最小閉環：啟動、認證、建立 session、傳送 prompt、收到響應、停止 client、記錄日誌。

## 5. 從 demo 到工程

要進入團隊試點，至少補齊：

1. 配置：模型、超時、重試、環境變數。
2. 許可權：工具 allowlist、敏感操作審批。
3. 日誌：session id、user id、prompt metadata、tool call。
4. 成本：模型和 premium request 口徑。
5. 可觀測性：OpenTelemetry 或內部 tracing。
6. 回復：關閉 SDK 入口，退回預設 Copilot。

<details>
<summary>深讀：為什麼 SDK 依賴 CLI 認證很重要</summary>

官方 quickstart 要求先安裝並認證 Copilot CLI。這樣 SDK 可以複用 GitHub account 和 Copilot access，而不是讓你在程式碼裡硬編碼 token。

這也意味著 SDK 應用的部署方式要認真設計：本地 CLI、後端服務、GitHub OAuth、Azure Managed Identity 等路徑不能混用。
</details>

## 本章自檢

1. 是否確認 Node.js 版本和 Copilot CLI 認證？
2. 是否知道當前 SDK 仍是 public preview？
3. 是否能解釋 `client`、`session`、`sendAndWait` 的職責？
4. 是否決定什麼時候用 streaming？
5. 是否有停止 client 和記錄錯誤的路徑？

透過標準：最小 demo 能跑，但不會被誤當成生產架構。

## 官方來源

- [Getting started with Copilot SDK](https://docs.github.com/en/copilot/how-tos/copilot-sdk/sdk-getting-started) —— GitHub 官方 quickstart。
- [Choosing a setup path for Copilot SDK](https://docs.github.com/en/copilot/how-tos/copilot-sdk/set-up-copilot-sdk/choosing-a-setup-path) —— GitHub 官方部署路徑選擇。
- [Authenticating with the Copilot SDK](https://docs.github.com/en/copilot/how-tos/copilot-sdk/authenticate-copilot-sdk) —— GitHub 官方認證說明。

## 接下來去哪

<Cards>
  <Card title="SDK Hooks" description="在加工具前，先學會攔截和審計行為。" href="/zh-Hant/docs/github-copilot/official/09-sdk-and-custom-agents/sdk-hooks" />
  <Card title="自定義 Agent" description="當一個 session 不夠表達專業分工時，再看 custom agents。" href="/zh-Hant/docs/github-copilot/official/09-sdk-and-custom-agents/custom-agents" />
</Cards>
