Copilot SDK

GitHub Copilot SDK

Overview

The GitHub Copilot SDK exposes the same Copilot CLI agent runtime over JSON-RPC, so apps can drive Copilot programmatically instead of building their own orchestration layer.

Status: Public preview
SDKs: Node.js/TypeScript, Python, Go, .NET, Java
Architecture: Application -> SDK client -> JSON-RPC -> Copilot CLI

How to use this skill

When helping with the Copilot SDK:

1. Prefer the official docs index and the language-specific README over memory.
2. Treat the top-level SDK README plus docs/ as the source of truth for shared behavior.
3. Call out preview status when stability or breaking changes matter.
4. Avoid hardcoding model lists when runtime discovery via listModels() is available.
5. Watch for stale guidance around permissions, lifecycle methods, and event names.

Current source of truth

Core SDK docs

• GitHub Copilot SDK repository
• Documentation index
• Getting started guide
• Setup guides
• Local CLI setup
• Bundled CLI setup
• Backend services setup
• Scaling and multi-tenancy
• Azure Managed Identity with BYOK
• Authentication
• BYOK
• Features index
• Image input
• Steering and queueing
• OpenTelemetry instrumentation
• Troubleshooting
• SDK/CLI compatibility

Language-specific docs

• Node.js / TypeScript README
• Python README
• Go README
• .NET README
• Java SDK repository

Copilot CLI and GitHub Docs

• About GitHub Copilot CLI
• Using GitHub Copilot CLI
• Custom agents configuration reference
• Enhancing agent mode with MCP
• Supported models

Recipes and examples

• Copilot SDK cookbook
• Node.js samples
• Go samples
• .NET samples

High-value facts

Authentication and prerequisites

• A GitHub Copilot subscription is required for normal SDK use.
• BYOK is supported and does not require GitHub Copilot authentication.
• Node.js, Python, and .NET bundle the Copilot CLI automatically.
• Go can use an installed CLI or embed/bundle one with the go tool bundler workflow.
• Java currently lives in github/copilot-sdk-java and expects the CLI to be installed separately.
• Azure Managed Identity / Entra auth is supported as a documented BYOK pattern by passing short-lived bearer tokens from DefaultAzureCredential.

Permissions

• The SDK uses a deny-by-default permission model.
• In practice, create/resume flows should provide an explicit permission handler such as:
  • TypeScript: approveAll
  • Python: PermissionHandler.approve_all
  • Go: copilot.PermissionHandler.ApproveAll
  • .NET: PermissionHandler.ApproveAll
  • Java: PermissionHandler.APPROVE_ALL

Session lifecycle

• Preferred cleanup method: disconnect()
• Deprecated cleanup method: destroy()
• To resume sessions reliably, provide your own sessionId when creating them.
• BYOK provider configuration must be provided again when resuming because keys are not persisted.

Transport and deployment

• Default transport is stdio with an SDK-managed CLI process.
• You can connect to an external headless CLI server via cliUrl.
• Current external server docs use:

copilot --headless --port 4321

Models

• Do not hardcode model support unless the user specifically needs a fixed list.
• Prefer client.listModels() and the official supported-models page.
• reasoningEffort exists for models that support it.

Installation

Setup and deployment choices

Pick the setup that matches the application shape:

• Local CLI - simplest path for personal tools and development.
• Bundled CLI - ship a CLI binary with your app for desktop/distributable tooling.
• Backend services - run the CLI in headless mode and connect with cliUrl.
• Scaling and multi-tenancy - shared CLI vs CLI-per-user, shared storage, and session locking.
• Azure Managed Identity - use BYOK with short-lived bearer tokens instead of static API keys when Azure auth is the real requirement.

Quick start pattern

Use the same mental model in every language:

1. Create/start the client.
2. Create a session with a permission handler.
3. Register event handlers before send() if you need streaming or progress.
4. Send with send() or sendAndWait().
5. Wait for session.idle or the returned final message.
6. disconnect() the session and stop/dispose the client.

TypeScript example

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

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

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

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

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

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

Core capabilities to remember

Client and session APIs

Common operations across SDKs:

• Client lifecycle: start(), stop(), forceStop()
• Session lifecycle: createSession(), resumeSession(), disconnect()
• Messaging: send(), sendAndWait(), abort(), getMessages()
• Discovery: listModels(), listSessions(), getStatus() / ping()

Events and streaming

• Final assistant output arrives in assistant.message.
• Streaming text arrives in assistant.message_delta.
• session.idle is the reliable "turn complete" signal.
• The event system now includes reasoning, tool progress, permission, elicitation, sub-agent, and skill events.

See references/event-system.md.