GitHub Copilot SDK

Embed Copilot's agentic workflows in any application using Python, TypeScript, Go, or .NET.

Overview

The GitHub Copilot SDK exposes the same engine behind Copilot CLI: a production-tested agent runtime you can invoke programmatically. No need to build your own orchestration - you define agent behavior, Copilot handles planning, tool invocation, file edits, and more.

Prerequisites

1. GitHub Copilot CLI installed and authenticated (Installation guide)
2. Language runtime: Node.js 18+, Python 3.8+, Go 1.21+, or .NET 8.0+

Verify CLI: copilot --version

Installation

Node.js/TypeScript

bash
1mkdir copilot-demo && cd copilot-demo
2npm init -y --init-type module
3npm install @github/copilot-sdk tsx

Python

bash
1pip install github-copilot-sdk

Go

bash
1mkdir copilot-demo && cd copilot-demo
2go mod init copilot-demo
3go get github.com/github/copilot-sdk/go

.NET

bash
1dotnet new console -n CopilotDemo && cd CopilotDemo
2dotnet add package GitHub.Copilot.SDK

Quick Start

TypeScript

typescript
1import { CopilotClient, approveAll } from "@github/copilot-sdk";
2
3const client = new CopilotClient();
4const session = await client.createSession({
5    onPermissionRequest: approveAll,
6    model: "gpt-4.1",
7});
8
9const response = await session.sendAndWait({ prompt: "What is 2 + 2?" });
10console.log(response?.data.content);
11
12await client.stop();
13process.exit(0);

Run: npx tsx index.ts

Python

python
1import asyncio
2from copilot import CopilotClient, PermissionHandler
3
4async def main():
5    client = CopilotClient()
6    await client.start()
7
8    session = await client.create_session({
9        "on_permission_request": PermissionHandler.approve_all,
10        "model": "gpt-4.1",
11    })
12    response = await session.send_and_wait({"prompt": "What is 2 + 2?"})
13
14    print(response.data.content)
15    await client.stop()
16
17asyncio.run(main())

Go

go
1package main
2
3import (
4    "fmt"
5    "log"
6    "os"
7    copilot "github.com/github/copilot-sdk/go"
8)
9
10func main() {
11    client := copilot.NewClient(nil)
12    if err := client.Start(); err != nil {
13        log.Fatal(err)
14    }
15    defer client.Stop()
16
17    session, err := client.CreateSession(&copilot.SessionConfig{
18        OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
19        Model:               "gpt-4.1",
20    })
21    if err != nil {
22        log.Fatal(err)
23    }
24
25    response, err := session.SendAndWait(copilot.MessageOptions{Prompt: "What is 2 + 2?"}, 0)
26    if err != nil {
27        log.Fatal(err)
28    }
29
30    fmt.Println(*response.Data.Content)
31    os.Exit(0)
32}

.NET (C#)

csharp
1using GitHub.Copilot.SDK;
2
3await using var client = new CopilotClient();
4await using var session = await client.CreateSessionAsync(new SessionConfig
5{
6    OnPermissionRequest = PermissionHandler.ApproveAll,
7    Model = "gpt-4.1",
8});
9
10var response = await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 2 + 2?" });
11Console.WriteLine(response?.Data.Content);

Run: dotnet run

Streaming Responses

Enable real-time output for better UX:

TypeScript

typescript
1import { CopilotClient, approveAll, SessionEvent } from "@github/copilot-sdk";
2
3const client = new CopilotClient();
4const session = await client.createSession({
5    onPermissionRequest: approveAll,
6    model: "gpt-4.1",
7    streaming: true,
8});
9
10session.on((event: SessionEvent) => {
11    if (event.type === "assistant.message_delta") {
12        process.stdout.write(event.data.deltaContent);
13    }
14    if (event.type === "session.idle") {
15        console.log(); // New line when done
16    }
17});
18
19await session.sendAndWait({ prompt: "Tell me a short joke" });
20
21await client.stop();
22process.exit(0);

Python

python
1import asyncio
2import sys
3from copilot import CopilotClient, PermissionHandler
4from copilot.generated.session_events import SessionEventType
5
6async def main():
7    client = CopilotClient()
8    await client.start()
9
10    session = await client.create_session({
11        "on_permission_request": PermissionHandler.approve_all,
12        "model": "gpt-4.1",
13        "streaming": True,
14    })
15
16    def handle_event(event):
17        if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
18            sys.stdout.write(event.data.delta_content)
19            sys.stdout.flush()
20        if event.type == SessionEventType.SESSION_IDLE:
21            print()
22
23    session.on(handle_event)
24    await session.send_and_wait({"prompt": "Tell me a short joke"})
25    await client.stop()
26
27asyncio.run(main())

Go

go
1session, err := client.CreateSession(&copilot.SessionConfig{
2	OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
3    Model:     "gpt-4.1",
4    Streaming: true,
5})
6
7session.On(func(event copilot.SessionEvent) {
8    if event.Type == "assistant.message_delta" {
9        fmt.Print(*event.Data.DeltaContent)
10    }
11    if event.Type == "session.idle" {
12        fmt.Println()
13    }
14})
15
16_, err = session.SendAndWait(copilot.MessageOptions{Prompt: "Tell me a short joke"}, 0)

.NET

csharp
1await using var session = await client.CreateSessionAsync(new SessionConfig
2{
3    OnPermissionRequest = PermissionHandler.ApproveAll,
4    Model = "gpt-4.1",
5    Streaming = true,
6});
7
8session.On(ev =>
9{
10    if (ev is AssistantMessageDeltaEvent deltaEvent)
11        Console.Write(deltaEvent.Data.DeltaContent);
12    if (ev is SessionIdleEvent)
13        Console.WriteLine();
14});
15
16await session.SendAndWaitAsync(new MessageOptions { Prompt = "Tell me a short joke" });

Custom Tools

Define tools that Copilot can invoke during reasoning. When you define a tool, you tell Copilot:

1. What the tool does (description)
2. What parameters it needs (schema)
3. What code to run (handler)

TypeScript (JSON Schema)

typescript
1import { CopilotClient, approveAll, defineTool, SessionEvent } from "@github/copilot-sdk";
2
3const getWeather = defineTool("get_weather", {
4    description: "Get the current weather for a city",
5    parameters: {
6        type: "object",
7        properties: {
8            city: { type: "string", description: "The city name" },
9        },
10        required: ["city"],
11    },
12    handler: async (args: { city: string }) => {
13        const { city } = args;
14        // In a real app, call a weather API here
15        const conditions = ["sunny", "cloudy", "rainy", "partly cloudy"];
16        const temp = Math.floor(Math.random() * 30) + 50;
17        const condition = conditions[Math.floor(Math.random() * conditions.length)];
18        return { city, temperature: `${temp}°F`, condition };
19    },
20});
21
22const client = new CopilotClient();
23const session = await client.createSession({
24    onPermissionRequest: approveAll,
25    model: "gpt-4.1",
26    streaming: true,
27    tools: [getWeather],
28});
29
30session.on((event: SessionEvent) => {
31    if (event.type === "assistant.message_delta") {
32        process.stdout.write(event.data.deltaContent);
33    }
34});
35
36await session.sendAndWait({
37    prompt: "What's the weather like in Seattle and Tokyo?",
38});
39
40await client.stop();
41process.exit(0);

Python (Pydantic)

python
1import asyncio
2import random
3import sys
4from copilot import CopilotClient, PermissionHandler
5from copilot.tools import define_tool
6from copilot.generated.session_events import SessionEventType
7from pydantic import BaseModel, Field
8
9class GetWeatherParams(BaseModel):
10    city: str = Field(description="The name of the city to get weather for")
11
12@define_tool(description="Get the current weather for a city")
13async def get_weather(params: GetWeatherParams) -> dict:
14    city = params.city
15    conditions = ["sunny", "cloudy", "rainy", "partly cloudy"]
16    temp = random.randint(50, 80)
17    condition = random.choice(conditions)
18    return {"city": city, "temperature": f"{temp}°F", "condition": condition}
19
20async def main():
21    client = CopilotClient()
22    await client.start()
23
24    session = await client.create_session({
25        "on_permission_request": PermissionHandler.approve_all,
26        "model": "gpt-4.1",
27        "streaming": True,
28        "tools": [get_weather],
29    })
30
31    def handle_event(event):
32        if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
33            sys.stdout.write(event.data.delta_content)
34            sys.stdout.flush()
35
36    session.on(handle_event)
37
38    await session.send_and_wait({
39        "prompt": "What's the weather like in Seattle and Tokyo?"
40    })
41
42    await client.stop()
43
44asyncio.run(main())

Go

go
1type WeatherParams struct {
2    City string `json:"city" jsonschema:"The city name"`
3}
4
5type WeatherResult struct {
6    City        string `json:"city"`
7    Temperature string `json:"temperature"`
8    Condition   string `json:"condition"`
9}
10
11getWeather := copilot.DefineTool(
12    "get_weather",
13    "Get the current weather for a city",
14    func(params WeatherParams, inv copilot.ToolInvocation) (WeatherResult, error) {
15        conditions := []string{"sunny", "cloudy", "rainy", "partly cloudy"}
16        temp := rand.Intn(30) + 50
17        condition := conditions[rand.Intn(len(conditions))]
18        return WeatherResult{
19            City:        params.City,
20            Temperature: fmt.Sprintf("%d°F", temp),
21            Condition:   condition,
22        }, nil
23    },
24)
25
26session, _ := client.CreateSession(&copilot.SessionConfig{
27	OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
28    Model:     "gpt-4.1",
29    Streaming: true,
30    Tools:     []copilot.Tool{getWeather},
31})

.NET (Microsoft.Extensions.AI)

csharp
1using GitHub.Copilot.SDK;
2using Microsoft.Extensions.AI;
3using System.ComponentModel;
4
5var getWeather = AIFunctionFactory.Create(
6    ([Description("The city name")] string city) =>
7    {
8        var conditions = new[] { "sunny", "cloudy", "rainy", "partly cloudy" };
9        var temp = Random.Shared.Next(50, 80);
10        var condition = conditions[Random.Shared.Next(conditions.Length)];
11        return new { city, temperature = $"{temp}°F", condition };
12    },
13    "get_weather",
14    "Get the current weather for a city"
15);
16
17await using var session = await client.CreateSessionAsync(new SessionConfig
18{
19    OnPermissionRequest = PermissionHandler.ApproveAll,
20    Model = "gpt-4.1",
21    Streaming = true,
22    Tools = [getWeather],
23});

How Tools Work

When Copilot decides to call your tool:

1. Copilot sends a tool call request with the parameters
2. The SDK runs your handler function
3. The result is sent back to Copilot
4. Copilot incorporates the result into its response

Copilot decides when to call your tool based on the user's question and your tool's description.

Interactive CLI Assistant

Build a complete interactive assistant:

TypeScript

typescript
1import { CopilotClient, approveAll, defineTool, SessionEvent } from "@github/copilot-sdk";
2import * as readline from "readline";
3
4const getWeather = defineTool("get_weather", {
5    description: "Get the current weather for a city",
6    parameters: {
7        type: "object",
8        properties: {
9            city: { type: "string", description: "The city name" },
10        },
11        required: ["city"],
12    },
13    handler: async ({ city }) => {
14        const conditions = ["sunny", "cloudy", "rainy", "partly cloudy"];
15        const temp = Math.floor(Math.random() * 30) + 50;
16        const condition = conditions[Math.floor(Math.random() * conditions.length)];
17        return { city, temperature: `${temp}°F`, condition };
18    },
19});
20
21const client = new CopilotClient();
22const session = await client.createSession({
23    onPermissionRequest: approveAll,
24    model: "gpt-4.1",
25    streaming: true,
26    tools: [getWeather],
27});
28
29session.on((event: SessionEvent) => {
30    if (event.type === "assistant.message_delta") {
31        process.stdout.write(event.data.deltaContent);
32    }
33});
34
35const rl = readline.createInterface({
36    input: process.stdin,
37    output: process.stdout,
38});
39
40console.log("Weather Assistant (type 'exit' to quit)");
41console.log("Try: 'What's the weather in Paris?'\n");
42
43const prompt = () => {
44    rl.question("You: ", async (input) => {
45        if (input.toLowerCase() === "exit") {
46            await client.stop();
47            rl.close();
48            return;
49        }
50
51        process.stdout.write("Assistant: ");
52        await session.sendAndWait({ prompt: input });
53        console.log("\n");
54        prompt();
55    });
56};
57
58prompt();

Python

python
1import asyncio
2import random
3import sys
4from copilot import CopilotClient, PermissionHandler
5from copilot.tools import define_tool
6from copilot.generated.session_events import SessionEventType
7from pydantic import BaseModel, Field
8
9class GetWeatherParams(BaseModel):
10    city: str = Field(description="The name of the city to get weather for")
11
12@define_tool(description="Get the current weather for a city")
13async def get_weather(params: GetWeatherParams) -> dict:
14    conditions = ["sunny", "cloudy", "rainy", "partly cloudy"]
15    temp = random.randint(50, 80)
16    condition = random.choice(conditions)
17    return {"city": params.city, "temperature": f"{temp}°F", "condition": condition}
18
19async def main():
20    client = CopilotClient()
21    await client.start()
22
23    session = await client.create_session({
24        "on_permission_request": PermissionHandler.approve_all,
25        "model": "gpt-4.1",
26        "streaming": True,
27        "tools": [get_weather],
28    })
29
30    def handle_event(event):
31        if event.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
32            sys.stdout.write(event.data.delta_content)
33            sys.stdout.flush()
34
35    session.on(handle_event)
36
37    print("Weather Assistant (type 'exit' to quit)")
38    print("Try: 'What's the weather in Paris?'\n")
39
40    while True:
41        try:
42            user_input = input("You: ")
43        except EOFError:
44            break
45
46        if user_input.lower() == "exit":
47            break
48
49        sys.stdout.write("Assistant: ")
50        await session.send_and_wait({"prompt": user_input})
51        print("\n")
52
53    await client.stop()
54
55asyncio.run(main())

MCP Server Integration

Connect to MCP (Model Context Protocol) servers for pre-built tools. Connect to GitHub's MCP server for repository, issue, and PR access:

TypeScript

typescript
1const session = await client.createSession({
2    onPermissionRequest: approveAll,
3    model: "gpt-4.1",
4    mcpServers: {
5        github: {
6            type: "http",
7            url: "https://api.githubcopilot.com/mcp/",
8        },
9    },
10});

Python

python
1session = await client.create_session({
2    "on_permission_request": PermissionHandler.approve_all,
3    "model": "gpt-4.1",
4    "mcp_servers": {
5        "github": {
6            "type": "http",
7            "url": "https://api.githubcopilot.com/mcp/",
8        },
9    },
10})

Go

go
1session, _ := client.CreateSession(&copilot.SessionConfig{
2	OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
3    Model: "gpt-4.1",
4    MCPServers: map[string]copilot.MCPServerConfig{
5        "github": {
6            "type": "http",
7            "url": "https://api.githubcopilot.com/mcp/",
8        },
9    },
10})

.NET

csharp
1await using var session = await client.CreateSessionAsync(new SessionConfig
2{
3    OnPermissionRequest = PermissionHandler.ApproveAll,
4    Model = "gpt-4.1",
5    McpServers = new Dictionary<string, McpServerConfig>
6    {
7        ["github"] = new McpServerConfig
8        {
9            Type = "http",
10            Url = "https://api.githubcopilot.com/mcp/",
11        },
12    },
13});

Custom Agents

Define specialized AI personas for specific tasks:

TypeScript

typescript
1const session = await client.createSession({
2    onPermissionRequest: approveAll,
3    model: "gpt-4.1",
4    customAgents: [{
5        name: "pr-reviewer",
6        displayName: "PR Reviewer",
7        description: "Reviews pull requests for best practices",
8        prompt: "You are an expert code reviewer. Focus on security, performance, and maintainability.",
9    }],
10});

Python

python
1session = await client.create_session({
2    "on_permission_request": PermissionHandler.approve_all,
3    "model": "gpt-4.1",
4    "custom_agents": [{
5        "name": "pr-reviewer",
6        "display_name": "PR Reviewer",
7        "description": "Reviews pull requests for best practices",
8        "prompt": "You are an expert code reviewer. Focus on security, performance, and maintainability.",
9    }],
10})

System Message

Customize the AI's behavior and personality:

TypeScript

typescript
1const session = await client.createSession({
2    onPermissionRequest: approveAll,
3    model: "gpt-4.1",
4    systemMessage: {
5        content: "You are a helpful assistant for our engineering team. Always be concise.",
6    },
7});

Python

python
1session = await client.create_session({
2    "on_permission_request": PermissionHandler.approve_all,
3    "model": "gpt-4.1",
4    "system_message": {
5        "content": "You are a helpful assistant for our engineering team. Always be concise.",
6    },
7})

External CLI Server

Run the CLI in server mode separately and connect the SDK to it. Useful for debugging, resource sharing, or custom environments.

Start CLI in Server Mode

bash
1copilot --server --port 4321

Connect SDK to External Server

TypeScript

typescript
1const client = new CopilotClient({
2    cliUrl: "localhost:4321"
3});
4
5const session = await client.createSession({
6    onPermissionRequest: approveAll,
7    model: "gpt-4.1",
8});

Python

python
1client = CopilotClient({
2    "cli_url": "localhost:4321"
3})
4await client.start()
5
6session = await client.create_session({
7    "on_permission_request": PermissionHandler.approve_all,
8    "model": "gpt-4.1",
9})

Go

go
1client := copilot.NewClient(&copilot.ClientOptions{
2    CLIUrl: "localhost:4321",
3})
4
5if err := client.Start(); err != nil {
6    log.Fatal(err)
7}
8
9session, _ := client.CreateSession(&copilot.SessionConfig{
10	OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
11	Model:               "gpt-4.1",
12})

.NET

csharp
1using var client = new CopilotClient(new CopilotClientOptions
2{
3    CliUrl = "localhost:4321"
4});
5
6await using var session = await client.CreateSessionAsync(new SessionConfig
7{
8    OnPermissionRequest = PermissionHandler.ApproveAll,
9    Model = "gpt-4.1",
10});

Note: When cliUrl is provided, the SDK will not spawn or manage a CLI process - it only connects to the existing server.

Event Types

Client Configuration

Session Configuration

Session Persistence

Save and resume conversations across restarts:

Create with Custom ID

typescript
1const session = await client.createSession({
2    onPermissionRequest: approveAll,
3    sessionId: "user-123-conversation",
4    model: "gpt-4.1"
5});

Resume Session

typescript
1const session = await client.resumeSession("user-123-conversation", { onPermissionRequest: approveAll });
2await session.send({ prompt: "What did we discuss earlier?" });

List and Delete Sessions

typescript
1const sessions = await client.listSessions();
2await client.deleteSession("old-session-id");

Error Handling

typescript
1try {
2    const client = new CopilotClient();
3    const session = await client.createSession({
4        onPermissionRequest: approveAll,
5        model: "gpt-4.1",
6    });
7    const response = await session.sendAndWait(
8        { prompt: "Hello!" },
9        30000 // timeout in ms
10    );
11} catch (error) {
12    if (error.code === "ENOENT") {
13        console.error("Copilot CLI not installed");
14    } else if (error.code === "ECONNREFUSED") {
15        console.error("Cannot connect to Copilot server");
16    } else {
17        console.error("Error:", error.message);
18    }
19} finally {
20    await client.stop();
21}

Graceful Shutdown

typescript
1process.on("SIGINT", async () => {
2    console.log("Shutting down...");
3    await client.stop();
4    process.exit(0);
5});

Common Patterns

Multi-turn Conversation

typescript
1const session = await client.createSession({
2    onPermissionRequest: approveAll,
3    model: "gpt-4.1",
4});
5
6await session.sendAndWait({ prompt: "My name is Alice" });
7await session.sendAndWait({ prompt: "What's my name?" });
8// Response: "Your name is Alice"

File Attachments

typescript
1await session.send({
2    prompt: "Analyze this file",
3    attachments: [{
4        type: "file",
5        path: "./data.csv",
6        displayName: "Sales Data"
7    }]
8});

Abort Long Operations

typescript
1const timeoutId = setTimeout(() => {
2    session.abort();
3}, 60000);
4
5session.on((event) => {
6    if (event.type === "session.idle") {
7        clearTimeout(timeoutId);
8    }
9});

Available Models

Query available models at runtime:

typescript
1const models = await client.getModels();
2// Returns: ["gpt-4.1", "gpt-4o", "claude-sonnet-4.5", ...]

Best Practices

1. Always cleanup: Use try-finally or defer to ensure client.stop() is called
2. Set timeouts: Use sendAndWait with timeout for long operations
3. Handle events: Subscribe to error events for robust error handling
4. Use streaming: Enable streaming for better UX on long responses
5. Persist sessions: Use custom session IDs for multi-turn conversations
6. Define clear tools: Write descriptive tool names and descriptions

Architecture

Your Application
       |
  SDK Client
       | JSON-RPC
  Copilot CLI (server mode)
       |
  GitHub (models, auth)

The SDK manages the CLI process lifecycle automatically. All communication happens via JSON-RPC over stdio or TCP.

Resources

• GitHub Repository: https://github.com/github/copilot-sdk
• Getting Started Tutorial: https://github.com/github/copilot-sdk/blob/main/docs/tutorials/first-app.md
• GitHub MCP Server: https://github.com/github/github-mcp-server
• MCP Servers Directory: https://github.com/modelcontextprotocol/servers
• Cookbook: https://github.com/github/copilot-sdk/tree/main/cookbook
• Samples: https://github.com/github/copilot-sdk/tree/main/samples

Status

This SDK is in Technical Preview and may have breaking changes. Not recommended for production use yet.