Back to Details

copilot-sdk

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

GitHub Copilot SDK

GitHub Copilot SDK

Overview

概述

The GitHub Copilot SDK is a multi-platform agent runtime that embeds Copilot's agentic workflows into applications. It exposes the same engine behind Copilot CLI, enabling programmatic invocation without requiring custom orchestration development.
Status: Technical Preview (suitable for development and testing)
Supported Languages: TypeScript/Node.js, Python, Go, .NET
GitHub Copilot SDK是一个跨平台的Agent运行时，可将Copilot的Agent工作流嵌入到应用程序中。它公开了Copilot CLI背后的同款引擎，无需开发自定义编排即可实现程序化调用。
**状态：**技术预览版（适用于开发和测试）
支持的语言： TypeScript/Node.js、Python、Go、.NET

Primary Documentation

主要文档

Language-Specific SDK Docs

各语言专属SDK文档

CLI and Configuration Docs

CLI与配置文档

Prerequisites

前提条件

  1. GitHub Copilot Subscription - Pro, Pro+, Business, or Enterprise
  2. GitHub Copilot CLI - Installed and authenticated (
    copilot --version
    )
  3. Runtime: Node.js 18+, Python 3.8+, Go 1.21+, or .NET 8.0+
  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+

Installation

安装

LanguageCommand
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
语言命令
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

Architecture

架构

Application → SDK Client → JSON-RPC → Copilot CLI (server mode)
The SDK manages CLI lifecycle automatically. External server connections supported via 
cliUrl
/ 
cli_url
.
Application → SDK Client → JSON-RPC → Copilot CLI (server mode)
SDK会自动管理CLI生命周期。通过
cliUrl
/ 
cli_url
支持外部服务器连接。

Quick Start (TypeScript)

快速开始（TypeScript）

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();
Critical: Register event handlers before calling 
send()
to capture all events.
For complete examples in all languages, see 
references/working-examples.md
.
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
。

Core Concepts

核心概念

Client

客户端

Main entry point. Manages CLI server lifecycle and session creation.
Operations: 
start()
, 
stop()
, 
createSession()
, 
resumeSession()
Config: 
cliPath
, 
cliUrl
, 
port
, 
useStdio
, 
autoStart
, 
autoRestart
主要入口点。管理CLI服务器生命周期和会话创建。
操作： 
start()
、
stop()
、
createSession()
、
resumeSession()
配置： 
cliPath
、
cliUrl
、
port
、
useStdio
、
autoStart
、
autoRestart

Session

会话

Individual conversation context with message history.
Operations: 
send()
, 
sendAndWait()
, 
on()
, 
abort()
, 
getMessages()
, 
destroy()
Config: 
model
, 
streaming
, 
tools
, 
systemMessage
带有消息历史的独立对话上下文。
操作： 
send()
、
sendAndWait()
、
on()
、
abort()
、
getMessages()
、
destroy()
配置： 
model
、
streaming
、
tools
、
systemMessage

Events

事件

Key events during processing:
EventPurpose
assistant.message
Complete response
assistant.message_delta
Streaming chunk
session.idle
Ready for next prompt
tool.execution_start/end
Tool invocations
For full event lifecycle and SessionEvent structure, see 
references/event-system.md
.
处理过程中的关键事件：
事件用途
assistant.message
完整响应
assistant.message_delta
流式响应片段
session.idle
准备好接收下一个提示
tool.execution_start/end
工具调用
如需完整的事件生命周期和SessionEvent结构，请查看
references/event-system.md
。

Streaming

流式传输

  • streaming: false
    (default) - Content arrives all at once
  • streaming: true
    - Content arrives incrementally via 
    assistant.message_delta
Final 
assistant.message
always fires regardless of streaming setting.
  • streaming: false
    （默认）- 内容一次性返回
  • streaming: true
    - 内容通过
    assistant.message_delta
    增量返回
无论流式传输设置如何，最终的
assistant.message
事件始终会触发。

Available Models

可用模型

See Supported AI Models for full list.
ProviderModel IDNotes
OpenAI
gpt-4.1
, 
gpt-5
, 
gpt-5-mini
Included
OpenAI
gpt-5.1
, 
gpt-5.1-codex
, 
gpt-5.2
Premium
Anthropic
claude-sonnet-4.5
Premium (CLI default)
Anthropic
claude-opus-4.5
Premium (3× multiplier)
Google
gemini-3-pro-preview
Premium
完整列表请查看支持的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
高级版

Custom Tools

自定义工具

TypeScript (Zod):
typescript
const tool = defineTool("lookup_issue", {
  description: "Fetch issue details",
  parameters: z.object({ id: z.string() }),
  handler: async ({ id }) => fetchIssue(id),
});
Python (Pydantic):
python
@define_tool(description="Fetch issue details")
async def lookup_issue(params: IssueParams) -> dict:
    return fetch_issue(params.id)
For complete tool examples in all languages, see 
references/working-examples.md
.
TypeScript（Zod）：
typescript
const tool = defineTool("lookup_issue", {
  description: "Fetch issue details",
  parameters: z.object({ id: z.string() }),
  handler: async ({ id }) => fetchIssue(id),
});
Python（Pydantic）：
python
@define_tool(description="Fetch issue details")
async def lookup_issue(params: IssueParams) -> dict:
    return fetch_issue(params.id)
如需所有语言的完整工具示例，请查看
references/working-examples.md
。

Language Conventions

语言约定

ConceptTypeScriptPythonGo.NET
Create session
createSession()
create_session()
CreateSession()
CreateSessionAsync()
Delta content
deltaContent
delta_content
DeltaContent
DeltaContent
For full conventions table, see 
references/event-system.md
.
概念TypeScriptPythonGo.NET
创建会话
createSession()
create_session()
CreateSession()
CreateSessionAsync()
增量内容
deltaContent
delta_content
DeltaContent
DeltaContent
如需完整的约定表格，请查看
references/event-system.md
。

CLI Configuration

CLI配置

Config stored in 
~/.copilot/
:
  • config.json
    - General configuration
  • mcp-config.json
    - MCP server definitions
For custom agents and MCP setup, see 
references/cli-agents-mcp.md
.
配置存储在
~/.copilot/
目录下：
  • config.json
    - 通用配置
  • mcp-config.json
    - MCP服务器定义
如需自定义Agent和MCP设置，请查看
references/cli-agents-mcp.md
。

Troubleshooting

故障排除

ProblemSolution
Events fire but content emptyUse 
event.data.content
, not 
event.content
Handler never firesRegister before 
send()
Python enum issuesUse 
event.type.value
Go nil pointerCheck 
!= nil
before dereferencing
For debugging techniques, see 
references/troubleshooting.md
.
问题解决方案
事件触发但内容为空使用
event.data.content
而非
event.content
处理程序从未触发在调用
send()
之前注册处理程序
Python枚举问题使用
event.type.value
Go空指针问题解引用前检查
!= nil
如需调试技巧，请查看
references/troubleshooting.md
。

Skill References

技能参考

Detailed documentation in this skill:
  • references/working-examples.md
    - Complete examples for all languages, custom tools
  • references/event-system.md
    - Event lifecycle, SessionEvent structure, language conventions
  • references/troubleshooting.md
    - Common issues, debugging techniques
  • references/cli-agents-mcp.md
    - CLI configuration, custom agents, MCP server setup
本技能中的详细文档：
  • references/working-examples.md
    - 所有语言的完整示例、自定义工具
  • references/event-system.md
    - 事件生命周期、SessionEvent结构、语言约定
  • references/troubleshooting.md
    - 常见问题、调试技巧
  • references/cli-agents-mcp.md
    - CLI配置、自定义Agent、MCP服务器设置

Additional Resources

额外资源