copilot-sdk

GitHub Copilot SDK

概述

GitHub Copilot SDK 是一个多平台 Agent 运行时，可将 Copilot 的 Agent 工作流嵌入应用程序。它提供与 Copilot CLI 背后相同的引擎，可通过编程方式调用，无需开发自定义编排功能。

状态： 技术预览版（适用于开发和测试）

支持的语言： TypeScript/Node.js、Python、Go、.NET

主要文档

• GitHub Copilot SDK 仓库
• 入门指南
• 包含示例的 Cookbook

特定语言的 SDK 文档

• Node.js/TypeScript SDK
• Python SDK
• Go SDK
• .NET SDK

CLI 和配置文档

• 关于 GitHub Copilot CLI
• 使用 GitHub Copilot CLI
• 创建自定义 Agent
• 自定义 Agent 配置参考
• 使用 MCP 增强 Agent 模式
• 支持的 AI 模型

---

先决条件

1. GitHub Copilot 订阅 - Pro、Pro+、Business 或 Enterprise
2. GitHub Copilot CLI - 已安装并完成身份验证（copilot --version）
3. 运行时： Node.js 18+、Python 3.8+、Go 1.21+ 或 .NET 8.0+

安装

语言	命令
TypeScript/Node.js	npm install @github/copilot-sdk
Python	pip install github-copilot-sdk
Go	go get github.com/github/copilot-sdk/go
.NET	dotnet add package GitHub.Copilot.SDK

架构

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

SDK 会自动管理 CLI 生命周期。支持通过 cliUrl / cli_url 连接外部服务。

---

快速开始（TypeScript）

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

const client = new CopilotClient();
await client.start();

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

// Register handler BEFORE send()
session.on((event) => {
  if (event.type === "assistant.message") {
    console.log(event.data.content);
  }
});

await session.send({ prompt: "What is 2 + 2?" });

await session.destroy();
await client.stop();

重要： 请在调用 send() 之前注册事件处理程序，以捕获所有事件。

如需查看所有语言的完整示例，请参阅 references/working-examples.md。

---

核心概念

客户端

主要入口点，用于管理 CLI 服务生命周期和会话创建。

操作： start()、stop()、createSession()、resumeSession()

配置： cliPath、cliUrl、port、useStdio、autoStart、autoRestart

会话

包含消息历史记录的独立对话上下文。

操作： send()、sendAndWait()、on()、abort()、getMessages()、destroy()

配置： model、streaming、tools、systemMessage

事件

处理期间的关键事件：

事件	用途
assistant.message	完整响应
assistant.message_delta	流式内容片段
session.idle	可处理下一个提示词
tool.execution_start/end	工具调用

如需了解完整的事件生命周期和 SessionEvent 结构，请参阅 references/event-system.md。

流式传输

• streaming: false（默认）- 内容一次性到达
• streaming: true - 内容通过 assistant.message_delta 分段到达

无论流式传输设置如何，最终的 assistant.message 始终会触发。

---

可用模型

完整列表请参阅支持的 AI 模型。

提供商	模型 ID	备注
OpenAI	gpt-4.1, gpt-5, gpt-5-mini	已包含
OpenAI	gpt-5.1, gpt-5.1-codex, gpt-5.2	高级版
Anthropic	claude-sonnet-4.5	高级版（CLI 默认）
Anthropic	claude-opus-4.5	高级版（3× 倍数）
Google	gemini-3-pro-preview	高级版

---

自定义工具

TypeScript（Zod）：

const tool = defineTool("lookup_issue", {
  description: "Fetch issue details",
  parameters: z.object({ id: z.string() }),
  handler: async ({ id }) => fetchIssue(id),
});

Python（Pydantic）：

@define_tool(description="Fetch issue details")
async def lookup_issue(params: IssueParams) -> dict:
    return fetch_issue(params.id)

如需查看所有语言的完整工具示例，请参阅 references/working-examples.md。

---

语言约定

概念	TypeScript	Python	Go	.NET
创建会话	createSession()	create_session()	CreateSession()	CreateSessionAsync()
增量内容	deltaContent	delta_content	DeltaContent	DeltaContent

完整的约定表请参阅 references/event-system.md。

---

CLI 配置

配置存储在 ~/.copilot/ 中：

• config.json - 常规配置
• mcp-config.json - MCP 服务定义

有关自定义 Agent 和 MCP 设置，请参阅 references/cli-agents-mcp.md。

---

故障排除

问题	解决方案
事件触发但内容为空	使用 event.data.content，而不是 event.content
处理程序始终不触发	在 send() 之前注册
Python 枚举问题	使用 event.type.value
Go 空指针	解引用前检查 != nil

有关调试技巧，请参阅 references/troubleshooting.md。

---

技能参考

本技能的详细文档：

• references/working-examples.md - 所有语言的完整示例、自定义工具
• references/event-system.md - 事件生命周期、SessionEvent 结构、语言约定
• references/troubleshooting.md - 常见问题、调试技巧
• references/cli-agents-mcp.md - CLI 配置、自定义 Agent、MCP 服务设置

---

其他资源

• SDK 示例
• SDK 发布版本
• Cookbook
• awesome-copilot