什麼是 GitHub Copilot SDK？

  • 8 分鐘

GitHub Copilot SDK 是一個多平台工具包（目前處於技術預覽階段），允許你將 AI 代理執行時嵌入到自己的應用程式中。 SDK 將 GitHub Copilot CLI 背後的引擎作為可程式化介面，讓你的應用程式能理解自然語言指令、規劃行動，並呼叫工具執行這些指令。 你不需要從零開始建造所有基礎設施。

為什麼要使用 SDK 來管理 AI 代理？

從零開始打造一個功能完整的 AI 代理非常複雜。 你需要跨回合管理對話狀態，決定何時呼叫哪個外部 API，確保 AI 回應保持在邊界內，管理多個 AI 模型以執行不同任務，並實施安全措施。 從零開始建立代理式工作流程，基本上是在你進入商業邏輯之前，就已經建構了一個迷你平台。

GitHub Copilot SDK 透過提供預先建置且經過生產測試的代理引擎，消除了這種複雜性。 SDK 負責認證、模型管理、聊天會話和串流。 你專注於在這些建構基礎之上開發的內容——例如你的專屬領域工具和商業邏輯。

架構概觀

GitHub Copilot SDK 與 GitHub Copilot CLI 通訊，後者以伺服器模式作為本地進程運行。 SDK 會自動管理 CLI 的流程生命週期。 所有 SDK 語言都共享相同的架構。

架構遵循以下流程：

Your Application → SDK Client → (JSON-RPC) → Copilot CLI (server mode)

你透過你選擇的程式語言中的客戶端函式庫與 SDK 互動。 SDK 負責通訊協定，所以你用簡單的方法呼叫，而不是原始訊息。

語言支援

SDK 提供四種程式語言的慣用語函式庫：

語言 Package
Node.js（TypeScript） npm install @github/copilot-sdk
Python pip install github-copilot-sdk
Go go get github.com/github/copilot-sdk/go
.NET （C#） dotnet add package GitHub.Copilot.SDK

無論你是在用 TypeScript 建置網頁應用程式，還是用 C# 建置後端服務，都能整合相同的 AI 代理功能。

主要功能

SDK 內建多項功能，簡化 AI 代理的建置。

生產等級代理程式迴圈

SDK 提供了與 GitHub Copilot CLI 相同的經過驗證的執行迴圈。 此執行迴圈管理多回合對話、呼叫工具，並反覆迭代直到任務完成。 你不需要寫程式規劃和協調邏輯。

工具編排

你可以定義自訂工具，讓 AI 代理人在推理過程中根據需要調用。 當你註冊一個工具（例如 lookupCustomer(id)），代理人的 AI 模型就能判斷何時呼叫它。 SDK 負責接線，讓 AI 能在執行時透過實際函式呼叫，以結構化的方式呼叫你的工具，而不是靠程式碼猜測。

在 .NET 中，工具是使用AIFunctionFactory從Microsoft.Extensions.AI套件中定義的。 每個工具包含名稱、描述、參數結構及處理函式。

多模型彈性

SDK 並不綁定於單一 AI 模型。 它支援多個 AI 模型，並允許動態模型路由。 例如，在同一應用程式中，你可以用更快的模型來處理簡單任務，用更強大的模型來處理複雜推理。

即時串流

SDK 支援串流回應，也就是說當 AI 產生輸出時，你可以將它串流到你的應用程式。 例如，你可以串流代幣，在聊天介面中顯示輸入指示或部分答案。 這種行為讓體驗更具互動性和反應性。

驗證和安全性

SDK 支援多種認證方法：

  • GitHub 登入使用者：重新使用在 Copilot CLI 登入時儲存的 OAuth 憑證。
  • OAuth GitHub App：從你的 GitHub OAuth 應用程式傳遞使用者代幣。
  • 環境變數：使用 COPILOT_GITHUB_TOKEN、 GH_TOKEN或 GITHUB_TOKEN。
  • 自備金鑰（BYOK）：使用自有 API 金鑰，服務如 OpenAI、Azure AI Foundry 或 Anthropic，無需 GitHub 認證。

除非你使用 BYOK 選項，否則必須訂閱 GitHub Copilot。

內容管理

SDK 會自動管理會話中的對話紀錄。 它會追蹤先前的訊息和工具輸出，讓 AI 模型擁有所需的上下文，以實現連貫的多回合互動。 對於長會話，SDK 提供 無限會話 功能，當上下文視窗接近限制時自動壓縮上下文，防止令牌溢位錯誤。

核心概念

了解 SDK 的核心概念有助於你更有效地使用它。

客戶

這個 CopilotClient 類別負責管理與 Copilot CLI 伺服器的連線。 你為你的應用程式建立一個客戶端實例，並用它來建立會話。 用戶端負責啟動與停止 CLI 程序、建立通訊通道，並管理會話生命週期。

設定選項包括 AutoStart （在建立第一個會話時自動啟動 CLI 伺服器）、 LogLevel （控制記錄冗長度）、 CliPath （指定 CLI 執行檔的自訂路徑）、以及 GithubToken （直接提供 GitHub 令牌，而非依賴環境變數或 CLI 登入）。

Session

A CopilotSession 代表單一的對話或任務情境。 每個會話都有自己的對話歷史、模型設定、工具定義及系統提示詞。 你可以用 CreateSessionAsync從客戶端建立會話，發送訊息給他們，並透過事件驅動模型接收回應。

主要的會話設定選項包括：

  • 模型：用於使用的 AI 模型（例如）。 gpt-4.1
  • SystemMessage：透過 SystemMessageConfig 一個物件 Mode （Append 或 Replace）和 Content 字串來定義代理的角色與行為。
  • 工具：代理可呼叫的自訂工具定義。
  • InfiniteSessions：通過InfiniteSessionConfig 對象來控制自動上下文壓縮。 啟用後，你可以設定 BackgroundCompactionThreshold （觸發背景壓縮的上下文視窗使用百分比）以及 BufferExhaustionThreshold （SDK 強制壓縮以防止令牌溢位的百分比）。

Tools

工具是你在會話中註冊的功能，讓 AI 代理人在推理時能呼叫它們。 每個工具都有名稱、描述、參數和處理功能。 當 AI 模型決定使用某個工具時，SDK 會攔截請求，呼叫你的處理器，並將結果回饋給模型以供進一步推理。

在 .NET 中，你可以用 AIFunctionFactory.Create 中的 Microsoft.Extensions.AI 方法定義工具：

AIFunctionFactory.Create(
    async ([Description("The order ID number")] int orderId) =>
        await GetOrderDetailsAsync(orderId),
    "get_order_details",
    "Look up the status and details of a specific order.")

活動

SDK 採用事件驅動的通訊模型。 當你向會話發送訊息時，SDK 會在處理過程中觸發事件：

  • AssistantMessageEvent：AI 模型產生了完整的回應。
  • AssistantMessageDeltaEvent：AI 模型在串流過程中產生了部分回應令牌。 這個 Data.DeltaContent 屬性包含了增量文字，你可以即時顯示。
  • SessionIdleEvent：會話已完成處理（包括所有工具呼叫）。
  • SessionErrorEvent：處理過程中發生錯誤。
  • ToolExecutionStartEvent 與 ToolExecutionCompleteEvent：一個工具被呼叫。

你訂閱這些事件是為了捕捉客服的回應並處理錯誤。 對於非直播情境，請使用 AssistantMessageEvent 來收集完整的回應。 對於串流場景（例如在聊天介面中顯示輸入指示器），可以使用 AssistantMessageDeltaEvent 即時渲染標記。

工作階段掛勾

SDK 提供了鉤子，讓你能攔截並修改代理在關鍵點的行為：

  • OnPreToolUse：在執行前攔截工具呼叫。 你的處理器會回傳一個 PermissionDecision 值——Allow 繼續通話、 Deny 阻擋通話，或 Ask 提示使用者確認。
  • OnPostToolUse：執行後處理結果，有助於在結果到達模型前記錄或修改。
  • OnUserPromptSubmitted：在處理前攔截並修改使用者提示。
  • OnErrorOccurred：透過回傳 ErrorHandling 一個值來處理錯誤——例如Retry 再次嘗試操作、 Skip 繼續無結果，或 Abort 停止處理。
  • OnSessionStart：當會話開始時執行，對初始化任務很有用。
  • OnSessionEnd：會話結束時執行，方便清理或記錄。

這些掛鉤能讓你實施權限控制、記錄及安全護欄。

.NET 開發的前提條件

要在 .NET 應用程式中使用 GitHub Copilot SDK，您的環境需要：

  • .NET 8.0 或更新版本。
  • GitHub Copilot CLI，已安裝並可在你的系統 PATH 中使用。
  • 一個有有效 Copilot 訂閱的 GitHub 帳號（或你自己的 API 金鑰用於 BYOK）。
  • GitHub.Copilot.SDK NuGet 套件。
  • Microsoft.Extensions.AI NuGet 套件（用於使用 AIFunctionFactory 定義工具）。

總結

GitHub Copilot SDK 提供了一個強大且準備好的生產環境平台，讓你能在應用程式中建置 AI 代理。 透過抽象化代理協調、工具整合與情境管理的複雜性，SDK 讓您專注於定義代理的能力與商業邏輯。 GitHub Copilot SDK 支援多語言、即時串流及靈活的認證選項，是為多種應用程式增添 AI 代理功能的多功能選擇。