GitHub Copilot SDK - Comprehensive Skill

Overview

The GitHub Copilot SDK enables developers to embed Copilot's agentic workflows programmatically in their applications. It exposes the same engine behind Copilot CLI as a production-tested agent runtime you can invoke from code.

When to Use the Copilot SDK

Use the Copilot SDK when:

• Building applications that need Copilot's AI capabilities

• Implementing custom AI assistants with tool-calling abilities

• Creating integrations that leverage Copilot's code understanding

• Connecting to MCP (Model Context Protocol) servers for standardized tools

• Need streaming responses in custom UIs

Don't use when:

• GitHub Copilot CLI is sufficient (use CLI directly)

• No programmatic integration needed (use Copilot in VS Code)

• Building simple chat without tools (use standard LLM API)

Language Support

SDK Installation

Node.js/TypeScript 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

Prerequisites

• GitHub Copilot CLI installed and authenticated

• Active Copilot subscription (free tier available with limits)

Quick Start

Minimal Example (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();

Minimal Example (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())

Add Streaming

const session = await client.createSession({ model: "gpt-4.1", streaming: true, });

session.on((event) => { if (event.type === "assistant.message_delta") { process.stdout.write(event.data.deltaContent); } });

await session.sendAndWait({ prompt: "Tell me a joke" });

Add Custom Tool

import { defineTool } from "@github/copilot-sdk";

const getWeather = defineTool("get_weather", { description: "Get weather for a city", parameters: { type: "object", properties: { city: { type: "string", description: "City name" }, }, required: ["city"], }, handler: async ({ city }) => ({ city, temperature: ${Math.floor(Math.random() * 30) + 50}°F, condition: "sunny", }), });

const session = await client.createSession({ model: "gpt-4.1", tools: [getWeather], });

Core Concepts

Architecture

Your Application → SDK Client → JSON-RPC → Copilot CLI (server mode)

The SDK manages the CLI process lifecycle automatically or connects to an external CLI server.

Key Components

• CopilotClient: Entry point - manages connection to Copilot CLI

• Session: Conversation context with model, tools, and history

• Tools: Custom functions Copilot can invoke

• Events: Streaming responses and tool call notifications

• MCP Integration: Connect to Model Context Protocol servers

Session Configuration

const session = await client.createSession({ model: "gpt-4.1", // Model to use streaming: true, // Enable streaming tools: [myTool], // Custom tools mcpServers: { // MCP server connections github: { type: "http", url: "https://api.githubcopilot.com/mcp/", }, }, systemMessage: { // Custom system prompt content: "You are a helpful assistant.", }, customAgents: [ { // Custom agent personas name: "code-reviewer", displayName: "Code Reviewer", description: "Reviews code for best practices", prompt: "Focus on security and performance.", }, ], });

Navigation Guide

When to Read Supporting Files

reference.md - Read when you need:

• Complete API reference for all 4 languages

• All method signatures with parameters and return types

• Session configuration options

• Event types and handling

• External CLI server connection

examples.md - Read when you need:

• Working copy-paste code for all 4 languages

• Error handling patterns

• Multiple sessions management

• Interactive assistant implementation

• Custom agent definition examples

patterns.md - Read when you need:

• Production-ready architectural patterns

• Streaming UI integration

• MCP server integration patterns

• Rate limiting and retry patterns

• Structured output extraction

drift-detection.md - Read when you need:

• Understanding how this skill stays current

• Validation workflow

• Update procedures

Quick Reference

Common Event Types

Event Type (TS/Go) Python Enum

assistant.message_delta

SessionEventType.ASSISTANT_MESSAGE_DELTA

session.idle

SessionEventType.SESSION_IDLE

tool.invocation

SessionEventType.TOOL_EXECUTION_START

tool.result

SessionEventType.TOOL_EXECUTION_COMPLETE

Python: Import from copilot.generated.session_events import SessionEventType

Default Tools

The SDK operates in --allow-all mode by default, enabling:

• File system operations

• Git operations

• Web requests

• All first-party Copilot tools

Integration with Amplihack

Use the Copilot SDK to build custom agents within amplihack:

Create Copilot-powered agent for specific domain

from copilot import CopilotClient

async def create_code_review_agent(): client = CopilotClient() await client.start() session = await client.create_session({ "model": "gpt-4.1", "streaming": True, "systemMessage": { "content": "You are an expert code reviewer." } }) return session

Next Steps

• Start Simple: Basic send/receive with default model

• Add Streaming: Real-time responses for better UX

• Add Tools: Custom functions for your domain

• Connect MCP: Use GitHub MCP server for repo access

• Build UI: Integrate into your application

For complete API details, see reference.md . For working code in all languages, see examples.md . For production patterns, see patterns.md .