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

• GitHub Copilot SDK Repository
• Getting Started Guide
• Cookbook with Recipes

Language-Specific SDK Docs

• Node.js/TypeScript SDK
• Python SDK
• Go SDK
• .NET SDK

CLI and Configuration Docs

• About GitHub Copilot CLI
• Using GitHub Copilot CLI
• Creating Custom Agents
• Custom Agents Configuration Reference
• Enhancing Agent Mode with MCP
• Supported AI Models

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+

Installation

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" });

// 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.

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:

For full event lifecycle and SessionEvent structure, see 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.

Available Models

See Supported AI Models for full list.

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

For full conventions table, see references/event-system.md.

CLI Configuration

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.

Troubleshooting

For debugging techniques, see 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

Additional Resources

• SDK Samples
• SDK Releases
• Cookbook
• awesome-copilot