GitHub Copilot SDK

Overview

The GitHub Copilot SDK is a multi-platform agent runtime that embeds Copilot's agentic workflows into applications. It exposes the same engine behind Copilot CLI, enabling programmatic invocation without requiring custom orchestration development.

Critical Constraint (TypeScript / Node.js):

• The Copilot SDK for Node.js is ESM-only
• Projects MUST use ECMAScript Modules
• CommonJS (

  require

  ,

  module.exports

  ) is not supported

Status: Technical Preview (suitable for development and testing)

Supported Languages: TypeScript/Node.js (ESM only), Python, Go, .NET

Primary Documentation

• GitHub Copilot SDK Repository
• Getting Started Guide
• Cookbook with Recipes

Language-Specific SDK Docs

• Node.js/TypeScript SDK
• Python SDK
• Go SDK
• .NET SDK

CLI and Configuration Docs

• About GitHub Copilot CLI
• Using GitHub Copilot CLI
• Creating Custom Agents
• Custom Agents Configuration Reference
• Enhancing Agent Mode with MCP
• Supported AI Models

Prerequisites

1. GitHub Copilot Subscription - Pro, Pro+, Business, or Enterprise

2. GitHub Copilot CLI - Installed and authenticated (

   copilot --version

   )

3. Runtime:

   • Node.js 18+ (ESM required)
   • Python 3.8+
   • Go 1.21+
   • .NET 8.0+

4. TypeScript / Node.js Project Requirements

   • package.json

     MUST include:

     {
       "type": "module"
     }
     

   • Use

     import

     /

     export

   • Do NOT use

     require()

     or

     module.exports

Installation

npm install @github/copilot-sdk

pip install github-copilot-sdk

go get github.com/github/copilot-sdk/go

dotnet add package GitHub.Copilot.SDK

Architecture

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

The SDK manages CLI lifecycle automatically. External server connections supported via

cliUrl

cli_url

Quick Start (TypeScript – ESM REQUIRED)

// package.json MUST include: { "type": "module" }

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

const client = new CopilotClient();
await client.start();

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

// Register handler BEFORE send()
session.on((event) => {
  if (event.type === "assistant.message") {
    console.log(event.data.content);
  }
});

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

await session.destroy();
await client.stop();

Critical:

• ESM only (

  import

  )
• No CommonJS
• Register event handlers before calling

  send()

For complete examples in all languages, see

references/working-examples.md

Core Concepts

Client

Main entry point. Manages CLI server lifecycle and session creation.

Operations:

start()

stop()

createSession()

resumeSession()

Config:

cliPath

cliUrl

port

useStdio

autoStart

autoRestart

Session

Individual conversation context with message history.

Operations:

send()

sendAndWait()

on()

abort()

getMessages()

destroy()

Config:

model

streaming

tools

systemMessage

Events

Key events during processing:

assistant.message

assistant.message_delta

session.idle

tool.execution_start/end

For full event lifecycle and SessionEvent structure, see

references/event-system.md

Streaming

• streaming: false

  (default) - Content arrives all at once

• streaming: true

  - Content arrives incrementally via

  assistant.message_delta

Final

assistant.message

Available Models

See Supported AI Models for full list.

gpt-4.1

gpt-5

gpt-5-mini

gpt-5.1

gpt-5.1-codex

gpt-5.2

claude-sonnet-4.5

claude-opus-4.5

gemini-3-pro-preview

Custom Tools

TypeScript (ESM + Zod):

const tool = defineTool("lookup_issue", {
  description: "Fetch issue details",
  parameters: z.object({ id: z.string() }),
  handler: async ({ id }) => fetchIssue(id),
});

Python (Pydantic):

@define_tool(description="Fetch issue details")
async def lookup_issue(params: IssueParams) -> dict:
    return fetch_issue(params.id)

For complete tool examples in all languages, see

references/working-examples.md

Language Conventions

createSession()

create_session()

CreateSession()

CreateSessionAsync()

deltaContent

delta_content

DeltaContent

DeltaContent

For full conventions table, see

references/event-system.md

CLI Configuration

Config stored in

~/.copilot/

• config.json

  - General configuration

• mcp-config.json

  - MCP server definitions

For custom agents and MCP setup, see

references/cli-agents-mcp.md

Troubleshooting

"type": "module"

event.data.content

event.content

send()

event.type.value

!= nil

For debugging techniques, see

references/troubleshooting.md

Skill References

Detailed documentation in this skill:

• references/working-examples.md

  - Complete examples for all languages, custom tools

• references/event-system.md

  - Event lifecycle, SessionEvent structure, language conventions

• references/troubleshooting.md

  - Common issues, debugging techniques

• references/cli-agents-mcp.md

  - CLI configuration, custom agents, MCP server setup

Additional Resources

• SDK Samples
• SDK Releases
• Cookbook
• awesome-copilot