copilot-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

前提条件

GitHub Copilot Subscription - Pro, Pro+, Business, or Enterprise
GitHub Copilot CLI - Installed and authenticated (
```
copilot --version
```
)
Runtime: Node.js 18+, Python 3.8+, Go 1.21+, or .NET 8.0+

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

Installation

安装

Language	Command
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:

Event	Purpose
`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.

Provider	Model ID	Notes
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

语言约定

Concept	TypeScript	Python	Go	.NET
Create session	`createSession()`	`create_session()`	`CreateSession()`	`CreateSessionAsync()`
Delta content	`deltaContent`	`delta_content`	`DeltaContent`	`DeltaContent`

For full conventions table, see

references/event-system.md

概念	TypeScript	Python	Go	.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

故障排除

Problem	Solution
Events fire but content empty	Use `event.data.content` , not `event.content`
Handler never fires	Register before `send()`
Python enum issues	Use `event.type.value`
Go nil pointer	Check `!= 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服务器设置

copilot-sdk

Original

Translation

GitHub Copilot SDK

GitHub Copilot SDK

Overview

概述

Primary Documentation

主要文档

Language-Specific SDK Docs

各语言专属SDK文档

CLI and Configuration Docs

CLI与配置文档

Prerequisites

前提条件

Installation

安装

Architecture

架构

Quick Start (TypeScript)

快速开始（TypeScript）

Core Concepts

核心概念

Client

客户端

Session

会话

Events

事件

Streaming

流式传输

Available Models

可用模型

Custom Tools

自定义工具

Language Conventions

语言约定

CLI Configuration

CLI配置

Troubleshooting

故障排除

Skill References

技能参考

Additional Resources

额外资源