Copilot Sdk

GitHub Copilot SDK

Build AI-powered applications that leverage Copilot's agentic workflows. The SDK exposes the same engine behind Copilot CLI—a production-tested agent runtime you can invoke programmatically.

Status: Technical Preview

When to Use This Skill

• Creating applications that need programmatic access to GitHub Copilot
• Building custom AI agents with tool integration
• Developing CLI tools or backends powered by Copilot
• Integrating Copilot capabilities into existing applications

Prerequisites

1. GitHub Copilot Subscription - Required for SDK usage
2. Copilot CLI - Must be installed and in PATH (installation guide)

Installation

Architecture

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

Quick Start Examples

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);
    } else if (event.type === "session.idle") {
        // Session finished processing
    }
});

await session.send({ prompt: "What is 2+2?" });
await session.destroy();
await client.stop();

Python

from copilot import CopilotClient

client = CopilotClient()
await client.start()

session = await client.create_session({"model": "gpt-5"})

def on_event(event):
    if event["type"] == "assistant.message":
        print(event["data"]["content"])

session.on(on_event)
await session.send({"prompt": "What is 2+2?"})
await session.destroy()
await client.stop()

Go

import copilot "github.com/github/copilot-sdk/go"

client := copilot.NewClient(&copilot.ClientOptions{LogLevel: "error"})
client.Start()
defer client.Stop()

session, _ := client.CreateSession(&copilot.SessionConfig{Model: "gpt-5"})
defer session.Destroy()

done := make(chan bool)
session.On(func(event copilot.SessionEvent) {
    if event.Type == "assistant.message" && event.Data.Content != nil {
        fmt.Println(*event.Data.Content)
    }
    if event.Type == "session.idle" {
        close(done)
    }
})

session.Send(copilot.MessageOptions{Prompt: "What is 2+2?"})
<-done

.NET

using GitHub.Copilot.SDK;

await using var client = new CopilotClient();
await client.StartAsync();

await using var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-5" });

var done = new TaskCompletionSource();
session.On(evt => {
    if (evt is AssistantMessageEvent msg) Console.WriteLine(msg.Data.Content);
    else if (evt is SessionIdleEvent) done.SetResult();
});

await session.SendAsync(new MessageOptions { Prompt = "What is 2+2?" });
await done.Task;

Event Types

Streaming

Enable real-time incremental responses:

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

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

Custom Tools

TypeScript (with Zod)

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

const session = await client.createSession({
    model: "gpt-5",
    tools: [
        defineTool("get_weather", {
            description: "Get current weather for a city",
            parameters: z.object({
                city: z.string().describe("City name"),
            }),
            handler: async ({ city }) => {
                return { temp: 72, condition: "sunny", city };
            },
        }),
    ],
});

Python

from copilot import define_tool

@define_tool("get_weather", "Get current weather for a city")
async def get_weather(city: str) -> dict:
    return {"temp": 72, "condition": "sunny", "city": city}

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

.NET

using Microsoft.Extensions.AI;
using System.ComponentModel;

var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-5",
    Tools = [
        AIFunctionFactory.Create(
            ([Description("City name")] string city) => new { Temp = 72, Condition = "sunny", City = city },
            "get_weather",
            "Get current weather for a city"),
    ]
});

Advanced Features

Multiple Sessions

const session1 = await client.createSession({ model: "gpt-5" });
const session2 = await client.createSession({ model: "claude-sonnet-4.5" });
// Sessions are independent

File Attachments

await session.send({
    prompt: "Analyze this file",
    attachments: [{ type: "file", path: "/path/to/file.ts", displayName: "My File" }],
});

Image Support

await session.send({
    prompt: "What's in this image?",
    attachments: [{ type: "base64", base64Content: imageBase64, mediaType: "image/png" }],
});

Session Persistence

// Save
const metadata = await session.getMetadata();
fs.writeFileSync("session.json", JSON.stringify(metadata));

// Resume
const saved = JSON.parse(fs.readFileSync("session.json"));
const resumed = await client.resumeSession({ sessionId: saved.id });

Bring Your Own Key (BYOK)

const session = await client.createSession({
    provider: { type: "openai", baseUrl: "https://api.openai.com/v1", apiKey: "your-key" },
});

MCP Server Integration

const session = await client.createSession({
    model: "gpt-5",
    mcpServers: [{
        type: "local",
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
    }],
});

Best Practices

1. Client Reuse - Use a singleton CopilotClient; avoid creating new instances repeatedly
2. Session Cleanup - Always call session.destroy() when done (use try/finally or disposable patterns)
3. Error Handling - Handle 429 (rate limit) with retry-after logic; log diagnostics
4. Streaming - Enable streaming for better UX with incremental responses
5. Tool Design - Keep handlers fast; return JSON-serializable values; provide clear parameter descriptions

Error Handling

try {
    await session.send({ prompt: "Hello" });
} catch (error) {
    if (error.code === 429) {
        // Rate limited - retry with backoff
    }
    console.error("Error:", error.message);
}

Default Capabilities

The SDK operates with all first-party tools enabled by default:

• File system operations
• Git operations
• Web requests

Customize via SDK client options.

Billing

• Each prompt counts toward your premium request quota
• Free tier available with limited usage
• See Requests in GitHub Copilot

Resources

• Getting Started Tutorial
• Cookbook - Practical Recipes
• Node.js/TypeScript Reference
• Python Reference
• Go Reference
• .NET Reference
• GitHub Issues