| name | copilot-sdk |
| description | This skill provides guidance for creating agents and applications with the GitHub Copilot SDK. It should be used when the user wants to create, modify, or work on software that uses the GitHub Copilot SDK in TypeScript, Python, Go, or .NET. The skill covers SDK usage patterns, 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.
Status: Technical Preview (suitable for development and testing)
Supported Languages: TypeScript/Node.js, 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+, Python 3.8+, Go 1.21+, or .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 |
Architecture
Application → 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)
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: Register event handlers before calling send() to capture all events.
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 (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 | 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 |
|---|
| 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
