---
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="/docs/github-copilot/official/09-sdk-and-custom-agents/sdk-hooks" />
  <Card title="自定义 Agent" description="当一个 session 不够表达专业分工时，再看 custom agents。" href="/docs/github-copilot/official/09-sdk-and-custom-agents/custom-agents" />
</Cards>
