| name | copilot-sdk |
| description | This skill provides guidance for creating agents and applications with the GitHub Copilot SDK. IMPORTANT - When using the SDK with TypeScript/Node.js, the project MUST use ESM (ECMAScript Modules). CommonJS (require/module.exports) is NOT supported. It should be used when the user wants to create, modify, or work on software that uses the GitHub Copilot SDK in TypeScript (ESM only), Python, Go, or .NET. The skill covers SDK usage patterns, ESM-based project configuration, CLI configuration, custom tools, MCP servers, and custom agents. |
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.
Critical Constraint (TypeScript / Node.js):
- The Copilot SDK for Node.js is ESM-only
- Projects MUST use ECMAScript Modules
- CommonJS (
require, module.exports) is not supported
Status: Technical Preview (suitable for development and testing)
Supported Languages: TypeScript/Node.js (ESM only), Python, Go, .NET
Primary Documentation
Language-Specific SDK Docs
CLI and Configuration Docs
Prerequisites
-
GitHub Copilot Subscription - Pro, Pro+, Business, or Enterprise
-
GitHub Copilot CLI - Installed and authenticated (copilot --version)
-
Runtime:
- Node.js 18+ (ESM required)
- Python 3.8+
- Go 1.21+
- .NET 8.0+
-
TypeScript / Node.js Project Requirements
package.json MUST include:
{
"type": "module"
}
- Use
import / export
- Do NOT use
require() or module.exports
Installation
| Language | Command |
|---|
| TypeScript/Node.js (ESM) | 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 (ESM) → SDK Client → JSON-RPC → Copilot CLI (server mode)
The SDK manages CLI lifecycle automatically. External server connections supported via cliUrl / cli_url.
Quick Start (TypeScript – ESM REQUIRED)
import { CopilotClient } from "@github/copilot-sdk";
const client = new CopilotClient();
await client.start();
const session = await client.createSession({ model: "gpt-5" });
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:
- ESM only (
import)
- No CommonJS
- Register event handlers before calling
send()
For complete examples in all languages, see 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
Session
Individual conversation context with message history.
Operations: send(), sendAndWait(), on(), abort(), getMessages(), destroy()
Config: 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.
Streaming
streaming: false (default) - Content arrives all at oncestreaming: true - Content arrives incrementally via assistant.message_delta
Final assistant.message always fires regardless of streaming setting.
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 |
Custom Tools
TypeScript (ESM + 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)
For complete tool examples in all languages, see references/working-examples.md.
Language Conventions
| Concept | TypeScript (ESM) | 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.
CLI Configuration
Config stored in ~/.copilot/:
config.json - General configurationmcp-config.json - MCP server definitions
For custom agents and MCP setup, see references/cli-agents-mcp.md.
Troubleshooting
| Problem | Solution |
|---|
| Import errors | Ensure ESM ("type": "module") |
| 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.
Skill References
Detailed documentation in this skill:
references/working-examples.md - Complete examples for all languages, custom toolsreferences/event-system.md - Event lifecycle, SessionEvent structure, language conventionsreferences/troubleshooting.md - Common issues, debugging techniquesreferences/cli-agents-mcp.md - CLI configuration, custom agents, MCP server setup
Additional Resources
