copilot-sdk

•

2.1k2303 months ago

Build applications powered by GitHub Copilot using the Copilot SDK. Use when creating programmatic integrations with Copilot across Node.js/TypeScript, Python, Go, or .NET. Covers session management, custom tools, streaming, hooks, MCP servers, BYOK providers, session persistence, and custom agents. Requires GitHub Copilot CLI installed and a GitHub Copilot subscription (unless using BYOK).

Quick Install

npxskills add microsoft/skills--skill copilot-sdk

Instructions

GitHub Copilot SDK

Build applications that programmatically interact with GitHub Copilot. The SDK wraps the Copilot CLI via JSON-RPC, providing session management, custom tools, hooks, MCP server integration, and streaming across Node.js, Python, Go, and .NET.

Prerequisites

GitHub Copilot CLI installed and authenticated (copilot --version)
GitHub Copilot subscription (Individual, Business, or Enterprise) — not required for BYOK
Runtime: Node.js 18+ / Python 3.8+ / Go 1.21+ / .NET 8.0+

Installation

Language	Package	Install
Node.js	`@github/copilot-sdk`	`npm install @github/copilot-sdk`
Python	`github-copilot-sdk`	`pip install github-copilot-sdk`

Loading…

Related Skills

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,360

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,309

1password

Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.

365,915

himalaya

CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).

365,885

Tags & Topics

agent-skillsagentsazurefoundrymcpsdk

Your App → SDK Client → [stdio/TCP] → Copilot CLI → Model Provider
                                          ↕
                                     MCP Servers

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();

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())

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

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-4.1"})
response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "What is 2 + 2?"})
fmt.Println(*response.Data.Content)

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig { Model = "gpt-4.1" });
var response = await session.SendAndWaitAsync(new MessageOptions { Prompt = "What is 2 + 2?" });
Console.WriteLine(response?.Data.Content);

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

session.on("assistant.message_delta", (event) => {
    process.stdout.write(event.data.deltaContent);
});
session.on("session.idle", () => console.log());

await session.sendAndWait({ prompt: "Tell me a joke" });

from copilot.generated.session_events import SessionEventType

session = await client.create_session({"model": "gpt-4.1", "streaming": True})

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

session.on(handle_event)
await session.send_and_wait({"prompt": "Tell me a joke"})

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

const getWeather = defineTool("get_weather", {
    description: "Get the current weather for a city",
    parameters: {
        type: "object",
        properties: { city: { type: "string", description: "The city name" } },
        required: ["city"],
    },
    handler: async ({ city }) => ({ city, temperature: "72°F", condition: "sunny" }),
});

const session = await client.createSession({
    model: "gpt-4.1",
    tools: [getWeather],
});

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

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

@define_tool(description="Get the current weather for a city")
async def get_weather(params: GetWeatherParams) -> dict:
    return {"city": params.city, "temperature": "72°F", "condition": "sunny"}

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

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

getWeather := copilot.DefineTool("get_weather", "Get weather for a city",
    func(params WeatherParams, inv copilot.ToolInvocation) (WeatherResult, error) {
        return WeatherResult{City: params.City, Temperature: "72°F"}, nil
    },
)

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
    Model: "gpt-4.1",
    Tools: []copilot.Tool{getWeather},
})

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

var getWeather = AIFunctionFactory.Create(
    ([Description("The city name")] string city) => new { city, temperature = "72°F" },
    "get_weather", "Get the current weather for a city");

await using var session = await client.CreateSessionAsync(new SessionConfig {
    Model = "gpt-4.1", Tools = [getWeather],
});

Hook	Trigger	Use Case
`onPreToolUse`	Before tool executes	Permission control, argument modification
`onPostToolUse`	After tool executes	Result transformation, logging, redaction
`onUserPromptSubmitted`	User sends message	Prompt modification, filtering, context injection
`onSessionStart`	Session begins (new or resumed)	Add context, configure session
`onSessionEnd`	Session ends	Cleanup, analytics, metrics
`onErrorOccurred`	Error happens	Custom error handling, retry logic, monitoring

const session = await client.createSession({
    hooks: {
        onPreToolUse: async (input) => {
            if (["shell", "bash"].includes(input.toolName)) {
                return { permissionDecision: "deny", permissionDecisionReason: "Shell access not permitted" };
            }
            return { permissionDecision: "allow" };
        },
    },
});

Field	Type	Description
`permissionDecision`	`"allow"` \| `"deny"` \| `"ask"`	Whether to allow the tool call
`permissionDecisionReason`	string	Explanation for deny/ask
`modifiedArgs`	object	Modified arguments to pass
`additionalContext`	string	Extra context for conversation
`suppressOutput`	boolean	Hide tool output from conversation

hooks: {
    onPostToolUse: async (input) => {
        // Redact sensitive data from results
        if (typeof input.toolResult === "string") {
            let redacted = input.toolResult;
            for (const pattern of SENSITIVE_PATTERNS) {
                redacted = redacted.replace(pattern, "[REDACTED]");
            }
            if (redacted !== input.toolResult) {
                return { modifiedResult: redacted };
            }
        }
        return null; // Pass through unchanged
    },
}

hooks: {
    onUserPromptSubmitted: async (input) => {
        return {
            modifiedPrompt: `[User from engineering team] ${input.prompt}`,
            additionalContext: "Follow company coding standards.",
        };
    },
}

hooks: {
    onSessionStart: async (input, invocation) => {
        // input.source: "startup" | "resume" | "new"
        console.log(`Session ${invocation.sessionId} started (${input.source})`);
        return { additionalContext: "Project uses TypeScript and React." };
    },
    onSessionEnd: async (input, invocation) => {
        // input.reason: "complete" | "error" | "abort" | "timeout" | "user_exit"
        await recordMetrics({ sessionId: invocation.sessionId, reason: input.reason });
        return null;
    },
}

hooks: {
    onErrorOccurred: async (input) => {
        // input.errorContext: "model_call" | "tool_execution" | "system" | "user_input"
        // input.recoverable: boolean
        if (input.errorContext === "model_call" && input.error.includes("rate")) {
            return { errorHandling: "retry", retryCount: 3, userNotification: "Rate limited. Retrying..." };
        }
        return null; // Default error handling
    },
}

async def on_pre_tool_use(input_data, invocation):
    if input_data["toolName"] in ["shell", "bash"]:
        return {"permissionDecision": "deny", "permissionDecisionReason": "Not permitted"}
    return {"permissionDecision": "allow"}

session = await client.create_session({
    "hooks": {"on_pre_tool_use": on_pre_tool_use}
})

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
    Hooks: &copilot.SessionHooks{
        OnPreToolUse: func(input copilot.PreToolUseHookInput, inv copilot.HookInvocation) (*copilot.PreToolUseHookOutput, error) {
            return &copilot.PreToolUseHookOutput{PermissionDecision: "allow"}, nil
        },
    },
})

const session = await client.createSession({
    mcpServers: {
        filesystem: {
            type: "local",
            command: "npx",
            args: ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
            tools: ["*"],
            env: { DEBUG: "true" },
            cwd: "./servers",
            timeout: 30000,
        },
    },
});

const session = await client.createSession({
    mcpServers: {
        github: {
            type: "http",
            url: "https://api.githubcopilot.com/mcp/",
            headers: { Authorization: "Bearer ${TOKEN}" },
            tools: ["*"],
        },
    },
});

Field	Type	Required	Description
`type`	`"local"`	No	Defaults to local
`command`	string	Yes	Executable path
`args`	string[]	Yes	Command arguments
`env`	object	No	Environment variables
`cwd`	string	No	Working directory
`tools`	string[]	No	`["*"]` for all, `[]` for none
`timeout`	number	No	Timeout in milliseconds

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server

npx @modelcontextprotocol/inspector /path/to/your/mcp-server

const client = new CopilotClient({ githubToken: process.env.GITHUB_TOKEN });

const client = new CopilotClient({
    githubToken: userAccessToken,    // gho_ or ghu_ token from OAuth flow
    useLoggedInUser: false,          // Don't use stored CLI credentials
});

const client = new CopilotClient({ useLoggedInUser: false });

provider: { type: "openai", baseUrl: "https://api.openai.com/v1", apiKey: process.env.OPENAI_API_KEY }

provider: {
    type: "openai",
    baseUrl: "https://your-resource.openai.azure.com/openai/v1/",
    apiKey: process.env.FOUNDRY_API_KEY,
    wireApi: "responses",  // Use "responses" for GPT-5 series, "completions" for others
}

provider: {
    type: "azure",
    baseUrl: "https://my-resource.openai.azure.com",  // Just the host — no /openai/v1
    apiKey: process.env.AZURE_OPENAI_KEY,
    azure: { apiVersion: "2024-10-21" },
}

provider: { type: "anthropic", baseUrl: "https://api.anthropic.com", apiKey: process.env.ANTHROPIC_API_KEY }

provider: { type: "openai", baseUrl: "http://localhost:11434/v1" }

Field	Type	Description
`type`	`"openai"` \| `"azure"` \| `"anthropic"`	Provider type
`baseUrl`	string	Required. API endpoint URL
`apiKey`	string	API key (optional for local providers)
`bearerToken`	string	Bearer token auth (takes precedence over apiKey)
`wireApi`	`"completions"` \| `"responses"`	API format (default: `"completions"`)
`azure.apiVersion`	string	Azure API version (default: `"2024-10-21"`)

from azure.identity import DefaultAzureCredential
from copilot import CopilotClient, ProviderConfig, SessionConfig

credential = DefaultAzureCredential()
token = credential.get_token("https://cognitiveservices.azure.com/.default").token

session = await client.create_session(SessionConfig(
    model="gpt-4.1",
    provider=ProviderConfig(
        type="openai",
        base_url=f"{foundry_url}/openai/v1/",
        bearer_token=token,
        wire_api="responses",
    ),
))

// Create with explicit ID
const session = await client.createSession({
    sessionId: "user-123-task-456",
    model: "gpt-4.1",
});

// Resume later (even from a different client instance)
const resumed = await client.resumeSession("user-123-task-456");
await resumed.sendAndWait({ prompt: "What did we discuss?" });

const sessions = await client.listSessions();           // List all
const lastId = await client.getLastSessionId();          // Get most recent
await client.deleteSession("user-123-task-456");         // Delete from storage
await session.destroy();                                 // Destroy active session

Pattern	Example	Use Case
`user-{userId}-{taskId}`	`user-alice-pr-review-42`	Multi-user apps
`tenant-{tenantId}-{workflow}`	`tenant-acme-onboarding`	Multi-tenant SaaS
`{userId}-{taskType}-{timestamp}`	`alice-deploy-1706932800`	Time-based cleanup

Data	Persisted?	Notes
Conversation history	✅ Yes	Full message thread
Tool call results	✅ Yes	Cached for context
Agent planning state	✅ Yes	`plan.md` file
Session artifacts	✅ Yes	In `files/` directory
Provider/API keys	❌ No	Must re-provide on resume
In-memory tool state	❌ No	Design tools to be stateless

const session = await client.createSession({
    infiniteSessions: {
        enabled: true,
        backgroundCompactionThreshold: 0.80,  // Start background compaction at 80%
        bufferExhaustionThreshold: 0.95,       // Block and compact at 95%
    },
});

const session = await client.createSession({
    customAgents: [{
        name: "pr-reviewer",
        displayName: "PR Reviewer",
        description: "Reviews pull requests for best practices",
        prompt: "You are an expert code reviewer. Focus on security, performance, and maintainability.",
    }],
});

const session = await client.createSession({
    systemMessage: { content: "You are a helpful assistant. Always be concise." },
});

const session = await client.createSession({
    skillDirectories: ["./skills/code-review", "./skills/documentation"],
    disabledSkills: ["experimental-feature"],
});

const session = await client.createSession({
    skillDirectories: ["./skills/security"],
    customAgents: [{ name: "auditor", prompt: "Focus on OWASP Top 10." }],
    mcpServers: { postgres: { type: "local", command: "npx", args: ["-y", "@modelcontextprotocol/server-postgres"], tools: ["*"] } },
});

const session = await client.createSession({
    onPermissionRequest: async (request) => {
        if (request.kind === "shell") {
            return { approved: request.command.startsWith("git") };
        }
        return { approved: true };
    },
    onUserInputRequest: async (request) => {
        return { response: "yes" };
    },
});

session.on("assistant.usage", (event) => {
    console.log("Tokens:", { input: event.data.inputTokens, output: event.data.outputTokens });
});

const client = new CopilotClient(); // Auto-manages CLI process

copilot --headless --port 4321

const client = new CopilotClient({ cliUrl: "localhost:4321" });

const client = new CopilotClient({ cliPath: path.join(__dirname, "vendor", "copilot") });

services:
  copilot-cli:
    image: ghcr.io/github/copilot-cli:latest
    command: ["--headless", "--port", "4321"]
    environment:
      - COPILOT_GITHUB_TOKEN=${COPILOT_GITHUB_TOKEN}
    volumes:
      - session-data:/root/.copilot/session-state
  api:
    build: .
    environment:
      - CLI_URL=copilot-cli:4321
    depends_on: [copilot-cli]
volumes:
  session-data:

Option	Type	Default	Description
`cliPath`	string	Auto-detected	Path to Copilot CLI executable
`cliUrl`	string	—	URL of external CLI server
`githubToken`	string	—	GitHub token for auth
`useLoggedInUser`	boolean	`true`	Use stored CLI credentials
`logLevel`	string	`"none"`	`"none"` \| `"error"` \| `"warning"` \| `"info"` \| `"debug"`
`autoRestart`	boolean	`true`	Auto-restart CLI on crash
`useStdio`	boolean	`true`	Use stdio transport

Option	Type	Description
`model`	string	Model to use (e.g., `"gpt-4.1"`, `"claude-sonnet-4"`)
`sessionId`	string	Custom ID for resumable sessions
`streaming`	boolean	Enable streaming responses
`tools`	Tool[]	Custom tools
`mcpServers`	object	MCP server configurations
`hooks`	object	Session hooks
`provider`	object	BYOK provider config
`customAgents`	object[]	Custom agent definitions
`systemMessage`	object	System message override
`skillDirectories`	string[]	Directories to load skills from
`disabledSkills`	string[]	Skills to disable
`reasoningEffort`	string	Reasoning effort level
`availableTools`	string[]	Restrict available tools
`excludedTools`	string[]	Exclude specific tools
`infiniteSessions`	object	Auto-compaction config
`workingDirectory`	string	Working directory

const client = new CopilotClient({ logLevel: "debug" });

const client = new CopilotClient({ cliArgs: ["--log-dir", "/path/to/logs"] });

Issue	Cause	Solution
`CLI not found`	CLI not installed or not in PATH	Install CLI or set `cliPath`
`Not authenticated`	No valid credentials	Run `copilot auth login` or provide `githubToken`
`Session not found`	Using session after `destroy()`	Check `listSessions()` for valid IDs
`Connection refused`	CLI process crashed	Enable `autoRestart: true`, check port conflicts
MCP tools missing	Server init failure or tools not enabled	Set `tools: ["*"]`, test server independently

console.log("State:", client.getState());  // "connected" after start()
client.on("stateChange", (state) => console.log("Changed to:", state));

Language	Client	Session Create	Send	Resume	Stop
Node.js	`new CopilotClient()`	`client.createSession()`	`session.sendAndWait()`	`client.resumeSession()`	`client.stop()`
Python	`CopilotClient()`	`client.create_session()`	`session.send_and_wait()`	`client.resume_session()`	`client.stop()`
Go	`copilot.NewClient(nil)`	`client.CreateSession()`	`session.SendAndWait()`	`client.ResumeSession()`	`client.Stop()`
.NET	`new CopilotClient()`	`client.CreateSessionAsync()`	`session.SendAndWaitAsync()`	`client.ResumeSessionAsync()`	`client.DisposeAsync()`

Mode	Description	Use Case
Stdio (default)	CLI as subprocess via pipes	Local dev, single process
TCP	CLI as network server	Multi-client, backend services

Method	Description
`on(handler)`	Subscribe to all events; returns unsubscribe function
`on(eventType, handler)`	Subscribe to specific event type (Node.js only)

Pattern	Isolation	Resources	Best For
CLI per user	Complete	High	Multi-tenant SaaS, compliance
Shared CLI + session IDs	Logical	Low	Internal tools
Shared sessions	None	Low	Team collaboration (requires locking)

Field	Type	Required	Description
`type`	`"http"`	Yes	Server type
`url`	string	Yes	Server URL
`headers`	object	No	HTTP headers
`tools`	string[]	No	Tool filter
`timeout`	number	No	Timeout in ms

copilot-sdk

GitHub Copilot SDK

Prerequisites

Installation

Related Skills

skill-creator

skill-creator

1password

himalaya

GitHub Copilot SDK

Prerequisites

Installation

Architecture

Core Pattern: Client → Session → Message

Node.js / TypeScript

Python

Go

.NET

Streaming Responses

Node.js

Python

Event Subscription

Custom Tools

Node.js

Python

Go

.NET

Tool Requirements

Hooks

Pre-Tool Use Hook

Post-Tool Use Hook

User Prompt Submitted Hook

Session Lifecycle Hooks

Error Handling Hook

Python Hook Example

Go Hook Example

MCP Server Integration

Local Stdio Server

Remote HTTP Server

MCP Config Fields

MCP Debugging

Authentication

Methods (Priority Order)

Programmatic Token

OAuth GitHub App

Disable Auto-Login

BYOK (Bring Your Own Key)

Provider Configurations

Provider Config Reference

Azure Managed Identity with BYOK

BYOK Limitations

Session Persistence

Session Management

Resume Options

Session ID Best Practices

What Gets Persisted

Infinite Sessions

Custom Agents

System Message

Skills Integration

Permission & Input Handlers

Token Usage Tracking

Deployment Patterns

Local CLI (Default)

External CLI Server (Backend Services)

Bundled CLI (Desktop Apps)

Docker Compose

Session Isolation Patterns

Production Checklist

Client Configuration

Session Configuration

SDK vs CLI Feature Comparison

✅ Available in SDK

❌ CLI-Only Features

Debugging

Common Issues

Connection State

Key API Summary

References

Related Skills