copilot-sdk
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseGitHub Copilot SDK
GitHub Copilot SDK
Build applications that programmatically interact with GitHub Copilot. The SDK wraps the Copilot CLI via JSON-RPC, providing session management, custom tools, hooks, MCP server integration, and streaming across Node.js, Python, Go, and .NET.
构建可与GitHub Copilot进行程序化交互的应用程序。该SDK通过JSON-RPC封装Copilot CLI,提供会话管理、自定义工具、钩子、MCP服务器集成功能,并支持在Node.js、Python、Go和.NET中实现流式响应。
Prerequisites
前提条件
- GitHub Copilot CLI installed and authenticated (to verify)
copilot --version - GitHub Copilot subscription (Individual, Business, or Enterprise) — not required for BYOK
- Runtime: Node.js 18+ / Python 3.8+ / Go 1.21+ / .NET 8.0+
- 已安装并完成身份验证的GitHub Copilot CLI(运行验证)
copilot --version - GitHub Copilot订阅(个人版、商业版或企业版)——使用BYOK时无需订阅
- 运行环境要求:Node.js 18+ / Python 3.8+ / Go 1.21+ / .NET 8.0+
Installation
安装
| Language | Package | Install |
|---|---|---|
| Node.js | | |
| Python | | |
| Go | | |
| .NET | | |
| 语言 | 包 | 安装命令 |
|---|---|---|
| Node.js | | |
| Python | | |
| Go | | |
| .NET | | |
Core Pattern: Client → Session → Message
核心模式:客户端 → 会话 → 消息
All SDK usage follows this pattern: create a client, create a session, send messages.
所有SDK的使用都遵循此模式:创建客户端、创建会话、发送消息。
Node.js / TypeScript
Node.js / TypeScript
typescript
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();typescript
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();Python
Python
python
import asyncio
from copilot import CopilotClient
async def main():
client = CopilotClient()
await client.start()
session = await client.create_session({"model": "gpt-4.1"})
response = await session.send_and_wait({"prompt": "What is 2 + 2?"})
print(response.data.content)
await client.stop()
asyncio.run(main())python
import asyncio
from copilot import CopilotClient
async def main():
client = CopilotClient()
await client.start()
session = await client.create_session({"model": "gpt-4.1"})
response = await session.send_and_wait({"prompt": "What is 2 + 2?"})
print(response.data.content)
await client.stop()
asyncio.run(main())Go
Go
go
client := copilot.NewClient(nil)
if err := client.Start(ctx); err != nil { log.Fatal(err) }
defer client.Stop()
session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"})
response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "What is 2 + 2?"})
fmt.Println(*response.Data.Content)go
client := copilot.NewClient(nil)
if err := client.Start(ctx); err != nil { log.Fatal(err) }
defer client.Stop()
session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"})
response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "What is 2 + 2?"})
fmt.Println(*response.Data.Content).NET
.NET
csharp
await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-4.1" });
var response = await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 2 + 2?" });
Console.WriteLine(response?.Data.Content);csharp
await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-4.1" });
var response = await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 2 + 2?" });
Console.WriteLine(response?.Data.Content);Streaming Responses
流式响应
Enable real-time output by setting and subscribing to delta events.
streaming: truetypescript
const session = await client.createSession({ model: "gpt-4.1", streaming: true });
session.on("assistant.message_delta", (event) => {
process.stdout.write(event.data.deltaContent);
});
session.on("session.idle", () => console.log());
await session.sendAndWait({ prompt: "Tell me a joke" });Python equivalent:
python
from copilot.generated.session_events import SessionEventType
session = await client.create_session({"model": "gpt-4.1", "streaming": True})
def handle_event(event):
if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
sys.stdout.write(event.data.delta_content)
sys.stdout.flush()
session.on(handle_event)
await session.send_and_wait({"prompt": "Tell me a joke"})通过设置并订阅delta事件,实现实时输出。
streaming: truetypescript
const session = await client.createSession({ model: "gpt-4.1", streaming: true });
session.on("assistant.message_delta", (event) => {
process.stdout.write(event.data.deltaContent);
});
session.on("session.idle", () => console.log());
await session.sendAndWait({ prompt: "Tell me a joke" });Python 等效实现:
python
from copilot.generated.session_events import SessionEventType
session = await client.create_session({"model": "gpt-4.1", "streaming": True})
def handle_event(event):
if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
sys.stdout.write(event.data.delta_content)
sys.stdout.flush()
session.on(handle_event)
await session.send_and_wait({"prompt": "Tell me a joke"})Event Subscription
事件订阅
| Method | Description |
|---|---|
| Subscribe to all events; returns unsubscribe function |
| Subscribe to specific event type (Node.js only) |
| 方法 | 描述 |
|---|---|
| 订阅所有事件;返回取消订阅函数 |
| 订阅特定事件类型(仅Node.js支持) |
Custom Tools
自定义工具
Define tools that Copilot can call to extend its capabilities.
定义Copilot可调用的工具以扩展其功能。
Node.js
Node.js
typescript
import { CopilotClient, defineTool } from "@github/copilot-sdk";
const getWeather = defineTool("get_weather", {
description: "Get the current weather for a city",
parameters: {
type: "object",
properties: { city: { type: "string", description: "The city name" } },
required: ["city"],
},
handler: async ({ city }) => ({ city, temperature: "72°F", condition: "sunny" }),
});
const session = await client.createSession({
model: "gpt-4.1",
tools: [getWeather],
});typescript
import { CopilotClient, defineTool } from "@github/copilot-sdk";
const getWeather = defineTool("get_weather", {
description: "Get the current weather for a city",
parameters: {
type: "object",
properties: { city: { type: "string", description: "The city name" } },
required: ["city"],
},
handler: async ({ city }) => ({ city, temperature: "72°F", condition: "sunny" }),
});
const session = await client.createSession({
model: "gpt-4.1",
tools: [getWeather],
});Python
Python
python
from copilot.tools import define_tool
from pydantic import BaseModel, Field
class GetWeatherParams(BaseModel):
city: str = Field(description="The city name")
@define_tool(description="Get the current weather for a city")
async def get_weather(params: GetWeatherParams) -> dict:
return {"city": params.city, "temperature": "72°F", "condition": "sunny"}
session = await client.create_session({"model": "gpt-4.1", "tools": [get_weather]})python
from copilot.tools import define_tool
from pydantic import BaseModel, Field
class GetWeatherParams(BaseModel):
city: str = Field(description="The city name")
@define_tool(description="Get the current weather for a city")
async def get_weather(params: GetWeatherParams) -> dict:
return {"city": params.city, "temperature": "72°F", "condition": "sunny"}
session = await client.create_session({"model": "gpt-4.1", "tools": [get_weather]})Go
Go
go
type WeatherParams struct {
City string `json:"city" jsonschema:"The city name"`
}
getWeather := copilot.DefineTool("get_weather", "Get weather for a city",
func(params WeatherParams, inv copilot.ToolInvocation) (WeatherResult, error) {
return WeatherResult{City: params.City, Temperature: "72°F"}, nil
},
)
session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
Model: "gpt-4.1",
Tools: []copilot.Tool{getWeather},
})go
type WeatherParams struct {
City string `json:"city" jsonschema:"The city name"`
}
getWeather := copilot.DefineTool("get_weather", "Get weather for a city",
func(params WeatherParams, inv copilot.ToolInvocation) (WeatherResult, error) {
return WeatherResult{City: params.City, Temperature: "72°F"}, nil
},
)
session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
Model: "gpt-4.1",
Tools: []copilot.Tool{getWeather},
}).NET
.NET
csharp
var getWeather = AIFunctionFactory.Create(
([Description("The city name")] string city) => new { city, temperature = "72°F" },
"get_weather", "Get the current weather for a city");
await using var session = await client.CreateSessionAsync(new SessionConfig {
Model = "gpt-4.1", Tools = [getWeather],
});csharp
var getWeather = AIFunctionFactory.Create(
([Description("The city name")] string city) => new { city, temperature = "72°F" },
"get_weather", "Get the current weather for a city");
await using var session = await client.CreateSessionAsync(new SessionConfig {
Model = "gpt-4.1", Tools = [getWeather],
});Hooks
钩子
Intercept and customize session behavior at key lifecycle points.
| Hook | Trigger | Use Case |
|---|---|---|
| Before tool executes | Permission control, argument modification |
| After tool executes | Result transformation, logging |
| User sends message | Prompt modification, filtering |
| Session begins | Add context, configure session |
| Session ends | Cleanup, analytics |
| Error happens | Custom error handling, retry logic |
在关键生命周期节点拦截并自定义会话行为。
| 钩子 | 触发时机 | 适用场景 |
|---|---|---|
| 工具执行前 | 权限控制、参数修改 |
| 工具执行后 | 结果转换、日志记录 |
| 用户发送消息时 | 提示词修改、内容过滤 |
| 会话开始时 | 添加上下文、配置会话 |
| 会话结束时 | 清理资源、数据分析 |
| 发生错误时 | 自定义错误处理、重试逻辑 |
Example: Tool Permission Control
示例:工具权限控制
typescript
const session = await client.createSession({
hooks: {
onPreToolUse: async (input) => {
if (["shell", "bash"].includes(input.toolName)) {
return { permissionDecision: "deny", permissionDecisionReason: "Shell access not permitted" };
}
return { permissionDecision: "allow" };
},
},
});typescript
const session = await client.createSession({
hooks: {
onPreToolUse: async (input) => {
if (["shell", "bash"].includes(input.toolName)) {
return { permissionDecision: "deny", permissionDecisionReason: "Shell access not permitted" };
}
return { permissionDecision: "allow" };
},
},
});Pre-Tool Use Output
工具执行前输出字段
| Field | Type | Description |
|---|---|---|
| | Whether to allow the tool call |
| string | Explanation for deny/ask |
| object | Modified arguments to pass |
| string | Extra context for conversation |
| boolean | Hide tool output from conversation |
| 字段 | 类型 | 描述 |
|---|---|---|
| | 是否允许工具调用 |
| string | 拒绝/询问的原因说明 |
| object | 要传递的修改后参数 |
| string | 对话的额外上下文 |
| boolean | 隐藏工具输出不显示在对话中 |
MCP Server Integration
MCP服务器集成
Connect to MCP servers for pre-built tool capabilities.
连接到MCP服务器以使用预构建的工具功能。
Remote HTTP Server
远程HTTP服务器
typescript
const session = await client.createSession({
mcpServers: {
github: { type: "http", url: "https://api.githubcopilot.com/mcp/" },
},
});typescript
const session = await client.createSession({
mcpServers: {
github: { type: "http", url: "https://api.githubcopilot.com/mcp/" },
},
});Local Stdio Server
本地标准输入输出服务器
typescript
const session = await client.createSession({
mcpServers: {
filesystem: {
type: "local",
command: "npx",
args: ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
tools: ["*"],
},
},
});typescript
const session = await client.createSession({
mcpServers: {
filesystem: {
type: "local",
command: "npx",
args: ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
tools: ["*"],
},
},
});MCP Config Fields
MCP配置字段
| Field | Type | Description |
|---|---|---|
| | Server transport type |
| string | Executable path (local) |
| string[] | Command arguments (local) |
| string | Server URL (http) |
| string[] | |
| object | Environment variables |
| string | Working directory (local) |
| number | Timeout in milliseconds |
| 字段 | 类型 | 描述 |
|---|---|---|
| | 服务器传输类型 |
| string | 可执行文件路径(本地服务器) |
| string[] | 命令参数(本地服务器) |
| string | 服务器URL(HTTP服务器) |
| string[] | |
| object | 环境变量 |
| string | 工作目录(本地服务器) |
| number | 超时时间(毫秒) |
Authentication
身份验证
Methods (Priority Order)
验证方式(优先级顺序)
- Explicit token — in constructor
githubToken - Environment variables — →
COPILOT_GITHUB_TOKEN→GH_TOKENGITHUB_TOKEN - Stored OAuth — From
copilot auth login - GitHub CLI — credentials
gh auth
- 显式令牌 — 构造函数中的参数
githubToken - 环境变量 — →
COPILOT_GITHUB_TOKEN→GH_TOKENGITHUB_TOKEN - 存储的OAuth凭证 — 来自命令
copilot auth login - GitHub CLI凭证 — 命令保存的凭证
gh auth
Programmatic Token
程序化令牌设置
typescript
const client = new CopilotClient({ githubToken: process.env.GITHUB_TOKEN });typescript
const client = new CopilotClient({ githubToken: process.env.GITHUB_TOKEN });BYOK (Bring Your Own Key)
BYOK(自带密钥)
Use your own API keys — no Copilot subscription required.
typescript
const session = await client.createSession({
model: "gpt-5.2-codex",
provider: {
type: "openai",
baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
wireApi: "responses",
apiKey: process.env.FOUNDRY_API_KEY,
},
});| Provider | Type | Notes |
|---|---|---|
| OpenAI | | OpenAI API and compatible endpoints |
| Azure OpenAI | | Native Azure endpoints (don't include |
| Azure AI Foundry | | OpenAI-compatible Foundry endpoints |
| Anthropic | | Claude models |
| Ollama | | Local models, no API key needed |
Wire API: Use for GPT-5 series, (default) for others.
"responses""completions"使用您自己的API密钥——无需Copilot订阅。
typescript
const session = await client.createSession({
model: "gpt-5.2-codex",
provider: {
type: "openai",
baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
wireApi: "responses",
apiKey: process.env.FOUNDRY_API_KEY,
},
});| 提供商 | 类型 | 说明 |
|---|---|---|
| OpenAI | | OpenAI API及兼容端点 |
| Azure OpenAI | | 原生Azure端点(请勿包含 |
| Azure AI Foundry | | 兼容OpenAI的Foundry端点 |
| Anthropic | | Claude系列模型 |
| Ollama | | 本地模型,无需API密钥 |
Wire API: GPT-5系列使用,其他模型使用默认值。
"responses""completions"Session Persistence
会话持久化
Resume sessions across restarts by providing your own session ID.
typescript
// Create with explicit ID
const session = await client.createSession({
sessionId: "user-123-task-456",
model: "gpt-4.1",
});
// Resume later
const resumed = await client.resumeSession("user-123-task-456");
await resumed.sendAndWait({ prompt: "What did we discuss?" });Session management:
typescript
const sessions = await client.listSessions(); // List all
await client.deleteSession("user-123-task-456"); // Delete
await session.destroy(); // Destroy activeBYOK sessions: Must re-provide config on resume (keys are not persisted).
provider通过提供自定义会话ID,可在重启后恢复会话。
typescript
// 使用显式ID创建会话
const session = await client.createSession({
sessionId: "user-123-task-456",
model: "gpt-4.1",
});
// 后续恢复会话
const resumed = await client.resumeSession("user-123-task-456");
await resumed.sendAndWait({ prompt: "What did we discuss?" });会话管理:
typescript
const sessions = await client.listSessions(); // 列出所有会话
await client.deleteSession("user-123-task-456"); // 删除会话
await session.destroy(); // 销毁活跃会话BYOK会话注意事项: 恢复时必须重新提供配置(密钥不会被持久化)。
providerInfinite Sessions
无限会话
For long-running workflows that may exceed context limits:
typescript
const session = await client.createSession({
infiniteSessions: {
enabled: true,
backgroundCompactionThreshold: 0.80,
bufferExhaustionThreshold: 0.95,
},
});适用于可能超出上下文限制的长期运行工作流:
typescript
const session = await client.createSession({
infiniteSessions: {
enabled: true,
backgroundCompactionThreshold: 0.80,
bufferExhaustionThreshold: 0.95,
},
});Custom Agents
自定义Agent
Define specialized AI personas:
typescript
const session = await client.createSession({
customAgents: [{
name: "pr-reviewer",
displayName: "PR Reviewer",
description: "Reviews pull requests for best practices",
prompt: "You are an expert code reviewer. Focus on security, performance, and maintainability.",
}],
});定义专用的AI角色:
typescript
const session = await client.createSession({
customAgents: [{
name: "pr-reviewer",
displayName: "PR Reviewer",
description: "Reviews pull requests for best practices",
prompt: "You are an expert code reviewer. Focus on security, performance, and maintainability.",
}],
});System Message
系统消息
Control AI behavior and personality:
typescript
const session = await client.createSession({
systemMessage: { content: "You are a helpful assistant. Always be concise." },
});控制AI的行为和个性:
typescript
const session = await client.createSession({
systemMessage: { content: "You are a helpful assistant. Always be concise." },
});Skills Integration
技能集成
Load skill directories to extend Copilot's capabilities:
typescript
const session = await client.createSession({
skillDirectories: ["./skills/code-review", "./skills/documentation"],
disabledSkills: ["experimental-feature"],
});加载技能目录以扩展Copilot的功能:
typescript
const session = await client.createSession({
skillDirectories: ["./skills/code-review", "./skills/documentation"],
disabledSkills: ["experimental-feature"],
});Permission & Input Handlers
权限与输入处理器
Handle tool permissions and user input requests programmatically:
typescript
const session = await client.createSession({
onPermissionRequest: async (request) => {
// Auto-approve git commands only
if (request.kind === "shell") {
return { approved: request.command.startsWith("git") };
}
return { approved: true };
},
onUserInputRequest: async (request) => {
// Handle ask_user tool calls
return { response: "yes" };
},
});程序化处理工具权限和用户输入请求:
typescript
const session = await client.createSession({
onPermissionRequest: async (request) => {
// 仅自动批准Git命令
if (request.kind === "shell") {
return { approved: request.command.startsWith("git") };
}
return { approved: true };
},
onUserInputRequest: async (request) => {
// 处理ask_user工具调用
return { response: "yes" };
},
});External CLI Server
外部CLI服务器
Connect to a separately running CLI instead of auto-managing the process:
bash
copilot --headless --port 4321typescript
const client = new CopilotClient({ cliUrl: "localhost:4321" });连接到独立运行的CLI,而非自动管理进程:
bash
copilot --headless --port 4321typescript
const client = new CopilotClient({ cliUrl: "localhost:4321" });Client Configuration
客户端配置
| Option | Type | Description |
|---|---|---|
| string | Path to Copilot CLI executable |
| string | URL of external CLI server |
| string | GitHub token for auth |
| boolean | Use stored CLI credentials (default: true) |
| string | |
| boolean | Auto-restart CLI on crash (default: true) |
| boolean | Use stdio transport (default: true) |
| 选项 | 类型 | 描述 |
|---|---|---|
| string | Copilot CLI可执行文件的路径 |
| string | 外部CLI服务器的URL |
| string | 用于身份验证的GitHub令牌 |
| boolean | 使用存储的CLI凭证(默认值:true) |
| string | |
| boolean | CLI崩溃时自动重启(默认值:true) |
| boolean | 使用标准输入输出传输(默认值:true) |
Session Configuration
会话配置
| Option | Type | Description |
|---|---|---|
| string | Model to use (e.g., |
| string | Custom ID for resumable sessions |
| boolean | Enable streaming responses |
| Tool[] | Custom tools |
| object | MCP server configurations |
| object | Session hooks |
| object | BYOK provider config |
| object[] | Custom agent definitions |
| object | System message override |
| string[] | Directories to load skills from |
| string[] | Skills to disable |
| string | Reasoning effort level |
| string[] | Restrict available tools |
| string[] | Exclude specific tools |
| object | Auto-compaction config |
| string | Working directory |
| 选项 | 类型 | 描述 |
|---|---|---|
| string | 使用的模型(例如: |
| string | 用于恢复会话的自定义ID |
| boolean | 启用流式响应 |
| Tool[] | 自定义工具 |
| object | MCP服务器配置 |
| object | 会话钩子 |
| object | BYOK提供商配置 |
| object[] | 自定义Agent定义 |
| object | 系统消息覆盖配置 |
| string[] | 加载技能的目录路径 |
| string[] | 要禁用的技能 |
| string | 推理力度级别 |
| string[] | 限制可用工具范围 |
| string[] | 排除特定工具 |
| object | 自动压缩配置 |
| string | 工作目录 |
Debugging
调试
Enable debug logging to troubleshoot issues:
typescript
const client = new CopilotClient({ logLevel: "debug" });Common issues:
- → Install CLI or set
CLI not foundcliPath - → Run
Not authenticatedor providecopilot auth logingithubToken - → Don't use session after
Session not founddestroy() - → Check CLI process, enable
Connection refusedautoRestart
启用调试日志以排查问题:
typescript
const client = new CopilotClient({ logLevel: "debug" });常见问题:
- → 安装CLI或设置
CLI not found参数cliPath - → 运行
Not authenticated或提供copilot auth logingithubToken - → 会话调用
Session not found后请勿再使用destroy() - → 检查CLI进程状态,启用
Connection refusedautoRestart
Key API Summary
核心API汇总
| Language | Client | Session Create | Send | Stop |
|---|---|---|---|---|
| Node.js | | | | |
| Python | | | | |
| Go | | | | |
| .NET | | | | |
| 语言 | 客户端创建 | 会话创建 | 消息发送 | 停止客户端 |
|---|---|---|---|---|
| Node.js | | | | |
| Python | | | | |
| Go | | | | |
| .NET | | | | |
References
参考资料
When to Use
适用场景
This skill is applicable to execute the workflow or actions described in the overview.
本技能适用于执行概述中描述的工作流或操作。