官方教程中文版SDK 與自定義 Agent
Copilot SDK 入門
說明 Copilot SDK 的 public preview 邊界、認證方式、安裝、session、sendAndWait 和 streaming。
Copilot SDK 入門的重點不是 hello world，而是理解執行邊界：SDK 透過 Copilot CLI 認證和連線 Copilot，用 CopilotClient 建立 session，然後傳送 prompt、監聽事件、管理生命週期——SDK 不會自己管 token，也不會自己管會話狀態。
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傳送第一條訊息。
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:2px2. 最小程式碼結構
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 到工程
要進入團隊試點，至少補齊：
- 配置：模型、超時、重試、環境變數。
- 許可權：工具 allowlist、敏感操作審批。
- 日誌：session id、user id、prompt metadata、tool call。
- 成本：模型和 premium request 口徑。
- 可觀測性：OpenTelemetry 或內部 tracing。
- 回復：關閉 SDK 入口，退回預設 Copilot。
深讀：為什麼 SDK 依賴 CLI 認證很重要
官方 quickstart 要求先安裝並認證 Copilot CLI。這樣 SDK 可以複用 GitHub account 和 Copilot access，而不是讓你在程式碼裡硬編碼 token。
這也意味著 SDK 應用的部署方式要認真設計：本地 CLI、後端服務、GitHub OAuth、Azure Managed Identity 等路徑不能混用。
本章自檢
- 是否確認 Node.js 版本和 Copilot CLI 認證？
- 是否知道當前 SDK 仍是 public preview？
- 是否能解釋
client、session、sendAndWait的職責？ - 是否決定什麼時候用 streaming？
- 是否有停止 client 和記錄錯誤的路徑？
透過標準：最小 demo 能跑，但不會被誤當成生產架構。
官方來源
- Getting started with Copilot SDK —— GitHub 官方 quickstart。
- Choosing a setup path for Copilot SDK —— GitHub 官方部署路徑選擇。
- Authenticating with the Copilot SDK —— GitHub 官方認證說明。