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.