# What Is the GitHub Copilot SDK? A Complete Developer Guide

> Explore the GitHub Copilot SDK, a powerful toolkit enabling developers to integrate AI code generation into their applications using language-specific libraries for Node.js Python Go Rust .NET and Java.

- Repository: [GitHub/copilot-sdk](https://github.com/github/copilot-sdk)
- Tags: getting-started
- Published: 2026-06-06

---

**The GitHub Copilot SDK is a family of language-specific libraries (Node.js/TypeScript, Python, Go, Rust, .NET, and Java) that let you embed the same agentic AI engine that powers the Copilot CLI directly inside your own applications.**

The GitHub Copilot SDK, hosted at `github/copilot-sdk`, provides stable client libraries that abstract the complexity of orchestrating AI sessions. Instead of building custom AI infrastructure, developers can leverage these production-ready APIs to manage conversation context, stream responses, and register custom tools using idiomatic patterns in their preferred programming language.

## GitHub Copilot SDK Architecture

The GitHub Copilot SDK operates on a common architecture across all supported languages. Your application communicates with a Copilot CLI process through **JSON-RPC** messages, abstracting the complexity of the AI runtime.

### JSON-RPC Communication Protocol

Every SDK follows this communication pattern:
- The SDK starts the Copilot CLI in server mode (or connects to an external instance)
- It opens a communication channel over standard I/O
- High-level client APIs translate method calls into JSON-RPC requests

```

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

```

According to the source code in [`nodejs/src/client.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/client.ts), the `CopilotClient` class manages this lifecycle, handling process spawning and connection management automatically for most languages.

### Bundled vs. External CLI

Language support varies by deployment model as documented in [`docs/setup/bundled-cli.md`](https://github.com/github/copilot-sdk/blob/main/docs/setup/bundled-cli.md):
- **Node.js, Python, and .NET**: The CLI is bundled automatically with the SDK
- **Go, Rust, and Java**: You must have the Copilot CLI available on your system PATH or run it in server mode separately

## Session Management and Workflow

The GitHub Copilot SDK uses a session-based architecture defined in [`nodejs/src/session.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/session.ts). A **session** represents a persistent conversation context with specific configuration for model selection, streaming behavior, tools, and authentication.

### Creating and Configuring Sessions

To begin interacting with the AI, instantiate a client and create a session using the `createSession` method:

```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);   // → 4

await client.stop();

```

The `createSession` method accepts configuration for model selection, streaming preferences, custom tools, and permission handlers. In [`nodejs/src/index.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/index.ts), the public export surface exposes these classes along with type definitions for session events.

### Streaming and Event Handling

For real-time applications, the SDK supports event-driven streaming. You can listen for `assistant.message_delta` events to receive incremental output as the model generates text, and `session.idle` events to detect when processing completes.

The session object exposes an `on` method for registering event handlers. As shown in the Python implementation, you process events by checking the `SessionEventType`:

```python
def handler(ev):
    if ev.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
        sys.stdout.write(ev.data.delta_content)
        sys.stdout.flush()
    if ev.type == SessionEventType.SESSION_IDLE:
        print()

session.on(handler)

```

## Authentication Options

The GitHub Copilot SDK supports multiple authentication strategies to accommodate different deployment scenarios. According to the repository's README, you can authenticate using:
- **GitHub OAuth tokens** obtained through standard OAuth flows
- **Environment variables** for CI/CD automation
- **BYOK (Bring Your Own Key)** for enterprise scenarios requiring custom API key management

Authentication configuration is passed during session creation or set globally on the client instance.

## Extensibility: Custom Tools and Agents

One of the SDK's most powerful features is the ability to define **custom tools**—functions that Copilot can invoke during conversation to retrieve data or perform actions.

### Defining Tools with JSON Schema

Tools are defined with a JSON schema for parameter validation and a handler function for execution. In Python, the `@define_tool` decorator creates a callable tool that the AI can reference:

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

class GetWeatherParams(BaseModel):
    city: str = Field(description="City name")

@define_tool(description="Get the current weather for a city")
async def get_weather(p: GetWeatherParams) -> dict:
    # placeholder implementation

    return {"city": p.city, "temperature": "64°F", "condition": "sunny"}

```

The `PermissionHandler` class allows automatic approval or denial of tool invocations, as demonstrated by `PermissionHandler.approve_all` in the example above.

### MCP Server Integration

The SDK supports the Model Context Protocol (MCP), allowing you to connect to external servers for repository-aware tools. You can also implement custom agents and override system messages through the extensibility hooks documented in [`docs/features/custom-agents.md`](https://github.com/github/copilot-sdk/blob/main/docs/features/custom-agents.md).

## Implementation Examples by Language

### TypeScript and Node.js

The Node.js SDK, exported from [`nodejs/src/index.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/index.ts), provides a promise-based API. The `CopilotClient` class handles CLI lifecycle management, while the session manages tool invocation callbacks:

```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);   // → 4

await client.stop();

```

### Python Async Patterns

The Python SDK supports async/await patterns for non-blocking I/O with full streaming support:

```python
import asyncio, sys
from copilot import CopilotClient
from copilot.session import PermissionHandler
from copilot.tools import define_tool
from copilot.session_events import SessionEventType
from pydantic import BaseModel, Field

class GetWeatherParams(BaseModel):
    city: str = Field(description="City name")

@define_tool(description="Get the current weather for a city")
async def get_weather(p: GetWeatherParams) -> dict:
    # placeholder implementation

    return {"city": p.city, "temperature": "64°F", "condition": "sunny"}

async def main():
    client = CopilotClient()
    await client.start()
    session = await client.create_session(
        on_permission_request=PermissionHandler.approve_all,
        model="gpt-4.1",
        streaming=True,
        tools=[get_weather],
    )

    # Print streamed chunks

    def handler(ev):
        if ev.type == SessionEventType.ASSISTANT_MESSAGE_DELTA:
            sys.stdout.write(ev.data.delta_content)
            sys.stdout.flush()
        if ev.type == SessionEventType.SESSION_IDLE:
            print()

    session.on(handler)
    await session.send_and_wait("What's the weather in Seattle?")
    await client.stop()

asyncio.run(main())

```

### Go Structures and Handlers

The Go SDK uses struct tags for JSON schema generation and explicit error handling. The `copilot.DefineTool` function accepts a name, description, and handler closure:

```go
package main

import (
    "context"
    "fmt"
    "log"
    "math/rand"

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

type WeatherParams struct {
    City string `json:"city" jsonschema:"The city name"`
}

type WeatherResult struct {
    City        string `json:"city"`
    Temperature string `json:"temperature"`
    Condition   string `json:"condition"`
}

func main() {
    ctx := context.Background()
    client := copilot.NewClient(nil)
    if err := client.Start(ctx); err != nil { log.Fatal(err) }
    defer client.Stop()

    getWeather := copilot.DefineTool(
        "get_weather",
        "Get the current weather for a city",
        func(p WeatherParams, _ copilot.ToolInvocation) (WeatherResult, error) {
            conditions := []string{"sunny", "cloudy", "rainy", "partly cloudy"}
            temp := rand.Intn(30) + 50
            condition := conditions[rand.Intn(len(conditions))]
            return WeatherResult{
                City: p.City, Temperature: fmt.Sprintf("%d°F", temp), Condition: condition,
            }, nil
        },
    )

    session, err := client.CreateSession(ctx, &copilot.SessionConfig{
        Model:     "gpt-4.1",
        Streaming: copilot.Bool(true),
        Tools:     []copilot.Tool{getWeather},
    })
    if err != nil { log.Fatal(err) }

    session.On(func(ev copilot.SessionEvent) {
        switch d := ev.Data.(type) {
        case *copilot.AssistantMessageDeltaData:
            fmt.Print(d.DeltaContent)
        case *copilot.SessionIdleData:
            fmt.Println()
        }
    })

    _, err = session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Weather in Tokyo?"})
    if err != nil { log.Fatal(err) }
}

```

## Summary

- **The GitHub Copilot SDK** provides language-specific libraries for embedding Copilot's AI engine into custom applications across Node.js, Python, Go, Rust, .NET, and Java.
- **Architecture** relies on JSON-RPC communication between your application and a Copilot CLI process, with the `CopilotClient` class managing connections as implemented in [`nodejs/src/client.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/client.ts).
- **Session management** follows a consistent pattern: create a session with `createSession`, send prompts via `sendAndWait` or streaming handlers, and register custom tools using `define_tool`.
- **Authentication** supports GitHub OAuth tokens, environment variables, and BYOK strategies for flexible deployment.
- **File locations** for core logic include [`nodejs/src/session.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/session.ts) for event handling and [`nodejs/src/index.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/index.ts) for the public API surface.

## Frequently Asked Questions

### What languages does the GitHub Copilot SDK support?

The GitHub Copilot SDK officially supports Node.js/TypeScript, Python, Go, Rust, .NET, and Java. Each implementation provides idiomatic APIs that map to the same underlying JSON-RPC protocol, ensuring consistent behavior across languages while respecting platform-specific patterns like Python's async/await or Go's struct tags.

### How does the GitHub Copilot SDK handle authentication?

The SDK supports three primary authentication methods: GitHub OAuth tokens for user-specific access, environment variables for automated CI/CD pipelines, and Bring Your Own Key (BYOK) for enterprises requiring custom API key management. Authentication credentials can be passed during session creation or configured globally on the client instance.

### What is the difference between bundled and external CLI modes?

Node.js, Python, and .NET SDKs bundle the Copilot CLI automatically, handling process lifecycle internally through the `CopilotClient` class. Go, Rust, and Java implementations require you to install the Copilot CLI separately and ensure it exists on your system PATH, or run it explicitly in server mode before connecting your application.

### Can I create custom tools with the GitHub Copilot SDK?

Yes. The SDK allows you to define custom tools using JSON schema for parameter validation and handler functions for execution. These tools enable Copilot to invoke external functions during conversations, such as querying databases or calling APIs, with support for MCP servers to extend functionality further as documented in [`docs/features/custom-agents.md`](https://github.com/github/copilot-sdk/blob/main/docs/features/custom-agents.md).