官方教程中文版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 官方认证说明。