GitHub Copilot SDK: Build AI-Powered Applications Programmatically

GitHub Copilot isn't just for code completion in your editor anymore. The Copilot SDK lets you integrate Copilot's AI capabilities directly into your applications, enabling custom tools, workflow automation, and conversational AI features—all backed by GitHub's infrastructure and your existing Copilot subscription.

What This Skill Does

The copilot-sdk provides a programmatic interface to GitHub Copilot across four languages: Node.js/TypeScript, Python, Go, and .NET. It wraps the Copilot CLI via JSON-RPC, giving you session management for persistent conversations, custom tool definitions to extend Copilot's capabilities, streaming responses for real-time output, lifecycle hooks to intercept and customize behavior, MCP (Model Context Protocol) server integration for pre-built tools, and BYOK (Bring Your Own Key) support to use your own LLM providers.

The workflow is consistent across all languages: create a client, create a session (with optional configuration), send messages, and process responses. Sessions are persistent—they maintain conversation history and can be resumed later, making it perfect for multi-turn interactions and complex workflows.

The SDK handles authentication automatically, manages the Copilot CLI process for you, provides both synchronous and streaming APIs, and supports custom tools written in your application's language. You can build anything from simple chat interfaces to complex agentic systems.

Getting Started

First, install and authenticate the GitHub Copilot CLI:

# Install CLI (varies by OS, see GitHub docs)
brew install gh copilot-cli  # macOS

# Authenticate
copilot auth login

Then install the SDK for your language:

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

Here's the simplest possible usage in each language:

Node.js:

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: "Explain recursion in one sentence" });
console.log(response?.data.content);

await client.stop();

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": "Explain recursion in one sentence"})
    
    print(response.data.content)
    await client.stop()

asyncio.run(main())

The pattern is identical: create client, create session, send messages, clean up. This consistency makes it easy to switch between languages or reuse patterns.

Key Features

Persistent Sessions: Unlike one-off API calls, Copilot sessions maintain conversation history. Create a session, have a multi-turn conversation, resume it later—perfect for building conversational interfaces or long-running workflows.

Custom Tools: Define functions that Copilot can call to extend its capabilities. Want Copilot to check your database, call an API, or run system commands? Define a tool and Copilot will invoke it when appropriate.

Streaming Responses: Get real-time output as Copilot generates text, just like in the ChatGPT interface. This creates responsive UIs and enables early processing of partial results.

Lifecycle Hooks: Intercept key moments—before tool calls (implement permission systems), after tool execution (transform results), when users submit prompts (filter or modify), and on errors (custom handling). This gives you fine-grained control over behavior.

MCP Integration: Connect to Model Context Protocol servers for pre-built tool capabilities. Use filesystem access, GitHub integration, web search, and hundreds of community tools without writing code.

BYOK Support: Use your own OpenAI, Azure, Anthropic, or Ollama keys instead of your Copilot subscription. Perfect for prototyping, custom models, or cost optimization.

Session Persistence: Create sessions with custom IDs and resume them across application restarts. Combined with infinite sessions (auto-compaction), this enables truly long-running AI assistants.

Usage Examples

Define Custom Tools (Node.js):

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

// Define a weather tool
const getWeather = defineTool("get_weather", {
    description: "Get current weather for a city",
    parameters: {
        type: "object",
        properties: {
            city: { type: "string", description: "City name" }
        },
        required: ["city"]
    },
    handler: async ({ city }) => {
        // Call weather API...
        return {
            city,
            temperature: "72°F",
            condition: "sunny"
        };
    }
});

// Create session with tool
const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-4.1",
    tools: [getWeather]
});

const response = await session.sendAndWait({
    prompt: "What's the weather in San Francisco?"
});
// Copilot will call getWeather tool automatically

console.log(response?.data.content);
await client.stop();

Stream Responses in Real-Time:

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

// Listen for delta events
session.on("assistant.message_delta", (event) => {
    process.stdout.write(event.data.deltaContent);
});

session.on("session.idle", () => {
    console.log("\n[Complete]");
});

await session.sendAndWait({ prompt: "Write a haiku about coding" });

Implement Tool Permission Control with Hooks:

const session = await client.createSession({
    model: "gpt-4.1",
    hooks: {
        onPreToolUse: async (input) => {
            // Block dangerous commands
            if (["shell", "bash", "exec"].includes(input.toolName)) {
                return {
                    permissionDecision: "deny",
                    permissionDecisionReason: "Shell commands not allowed"
                };
            }
            
            // Modify arguments for allowed tools
            if (input.toolName === "fetch_url") {
                // Ensure only HTTPS URLs
                const url = input.toolArguments.url;
                if (!url.startsWith("https://")) {
                    return {
                        permissionDecision: "deny",
                        permissionDecisionReason: "Only HTTPS URLs allowed"
                    };
                }
            }
            
            return { permissionDecision: "allow" };
        }
    }
});

Integrate MCP Servers:

const session = await client.createSession({
    model: "gpt-4.1",
    mcpServers: {
        // Remote HTTP MCP server
        github: {
            type: "http",
            url: "https://api.githubcopilot.com/mcp/"
        },
        
        // Local MCP server (filesystem access)
        filesystem: {
            type: "local",
            command: "npx",
            args: ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
            tools: ["*"]  // Use all tools from this server
        }
    }
});

await session.sendAndWait({
    prompt: "List files in the current directory"
});
// Copilot uses filesystem MCP server to access files

Use BYOK with Custom Providers (Python):

session = await client.create_session({
    "model": "gpt-4o",
    "provider": {
        "type": "openai",
        "apiKey": os.environ["OPENAI_API_KEY"],
        "baseUrl": "https://api.openai.com/v1/"
    }
})

# Or use Anthropic Claude
session = await client.create_session({
    "model": "claude-3-5-sonnet-20241022",
    "provider": {
        "type": "anthropic",
        "apiKey": os.environ["ANTHROPIC_API_KEY"]
    }
})

# Or local Ollama (no key needed)
session = await client.create_session({
    "model": "llama3.1",
    "provider": {
        "type": "openai",
        "baseUrl": "http://localhost:11434/v1/",
        "wireApi": "completions"
    }
})

Resume Sessions Across Restarts:

// First run: create with custom ID
const session = await client.createSession({
    sessionId: "user-123-project-456",
    model: "gpt-4.1"
});

await session.sendAndWait({
    prompt: "I'm working on a web scraper. Help me design the architecture."
});

// Application restarts...

// Later: resume the same session
const resumed = await client.resumeSession("user-123-project-456");

await resumed.sendAndWait({
    prompt: "Continue from where we left off—what about error handling?"
});
// Copilot remembers the entire conversation context

Python Example with Custom Tools:

from copilot.tools import define_tool
from pydantic import BaseModel, Field

class SearchParams(BaseModel):
    query: str = Field(description="Search query")
    limit: int = Field(default=10, description="Max results")

@define_tool(description="Search the knowledge base")
async def search_kb(params: SearchParams) -> dict:
    # Search your database...
    return {
        "results": [
            {"title": "How to use API", "url": "/docs/api"},
            {"title": "Authentication guide", "url": "/docs/auth"}
        ]
    }

session = await client.create_session({
    "model": "gpt-4.1",
    "tools": [search_kb]
})

response = await session.send_and_wait({
    "prompt": "Find documentation about authentication"
})

Best Practices

Use Hooks for Security: Never trust LLMs with unrestricted tool access. Use onPreToolUse hooks to implement permission systems, validate arguments, and block dangerous operations. This is critical for production applications.

Set Appropriate Models: GPT-4.1 is more capable but slower and more expensive. For simple tasks, use GPT-3.5 or even local models via BYOK. Match model capability to task complexity.

Handle Streaming Gracefully: When using streaming, always handle both delta events and completion events. Buffer partial content if needed, and implement timeout logic for hung streams.

Persist Important Sessions: For user-facing applications, use custom session IDs and store them with user accounts. This enables "continue where we left off" experiences that feel magical.

Clean Up Resources: Always call client.stop() or use await using (.NET) / context managers (Python) to clean up the CLI process. Leaked processes accumulate and waste resources.

Test Tool Definitions Thoroughly: LLMs are probabilistic—they might call your tools in unexpected ways. Test edge cases, validate inputs defensively, and handle errors gracefully.

Monitor Token Usage: Each session consumes tokens from your Copilot subscription or BYOK budget. Implement infinite sessions with auto-compaction for long-running assistants to prevent context exhaustion.

Use MCP When Possible: Don't reinvent the wheel. Check the MCP marketplace for pre-built servers before writing custom tools. Community servers handle common use cases like filesystem access, web scraping, and API integration.

When to Use This Skill

Perfect for:

• Building conversational AI interfaces for applications


• Workflow automation requiring AI decision-making


• Code generation and analysis tools


• Documentation generation systems


• AI-powered CLI applications


• Internal tools for teams with Copilot subscriptions


• Prototyping agentic systems before production deployment

Consider alternatives for:

• Simple one-off completions (use OpenAI API directly)


• Applications without GitHub affiliation (Copilot branding may confuse users)


• Extremely high-volume workloads (consider dedicated LLM infrastructure)


• Real-time latency-critical applications (API latency via CLI adds overhead)

The Copilot SDK is ideal when you're already in the GitHub ecosystem, have Copilot subscriptions, or want to prototype AI features quickly without managing LLM infrastructure.

Related Skills

Explore the full GitHub Copilot SDK skill: /ai-assistant/copilot-sdk

Source

This skill is provided by GitHub/Microsoft via the official Copilot SDK.

---

Ready to bring Copilot's AI capabilities into your applications? The SDK makes it surprisingly straightforward.