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:

• Prefer the official docs index and the language-specific README over memory.
• Treat the top-level SDK README plus docs/ as the source of truth for shared behavior.
• Call out preview status when stability or breaking changes matter.
• Avoid hardcoding model lists when runtime discovery via listModels() is available.
• 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

| SDK | Install |

| --- | --- |

| Node.js / TypeScript | npm install @github/copilot-sdk |

| Python | pip install github-copilot-sdk |

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

| .NET | dotnet add package GitHub.Copilot.SDK |

| Java | Maven/Gradle package com.github:copilot-sdk-java |

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:

• Create/start the client.
• Create a session with a permission handler.
• Register event handlers before send() if you need streaming or progress.
• Send with send() or sendAndWait().
• Wait for session.idle or the returned final message.
• 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.

Custom tools

• Node uses defineTool(...) with Zod or raw JSON Schema.
• Python uses @define_tool with Pydantic models.
• Go prefers DefineTool(...).
• .NET uses AIFunctionFactory.Create(...).
• Overriding built-ins always requires explicit opt-in:
• TypeScript: overridesBuiltInTool: true
• Python: overrides_built_in_tool=True
• Go: OverridesBuiltInTool = true
• .NET: AdditionalProperties["is_override"] = true
• Custom tools can also opt into skipPermission.

Custom agents, MCP, hooks, and skills

• customAgents lets you define sub-agents per session.
• mcpServers attaches local or remote MCP servers.
• Hooks provide control points such as onPreToolUse, onPostToolUse, onUserPromptSubmitted, and lifecycle/error hooks.
• Skills are loaded with skillDirectories; disable selectively with disabledSkills.

See references/cli-agents-mcp.md.

Attachments, commands, and interaction

• Sessions can send file, directory, and image attachments.
• Image input supports both file and blob attachments, and vision should be checked through model capabilities.
• In-flight messaging supports mode: "immediate" for steering and mode: "enqueue" for queueing.
• The SDK can register custom slash commands.
• Apps can answer user questions with onUserInputRequest.
• Rich UI prompts are available through elicitation handlers and session.ui when the connected client supports them.

Telemetry and observability

• The SDK supports OpenTelemetry configuration through TelemetryConfig.
• Trace context propagation is built in, with Node using an explicit onGetTraceContext callback for outbound propagation.

Persistence and long-running work

• Use a stable sessionId for resumable sessions.
• Use infiniteSessions for long-running workflows that may need compaction.
• Session state is stored under ~/.copilot/session-state/ unless configuration overrides it.

SDK vs. CLI-only features

• The SDK exposes programmatic surfaces for sessions, models, plans, mode switching, workspace files, custom agents, hooks, MCP, skills, and telemetry.
• Many terminal UX features remain CLI-only, such as most slash-command workflows, interactive pickers, and export/share commands.
• When translating a CLI workflow into app code, check the compatibility guide before assuming a slash command has an SDK equivalent.

Language conventions

| Concept | TypeScript | Python | Go | .NET | Java |

| --- | --- | --- | --- | --- | --- |

| Create session | createSession() | create_session() | CreateSession() | CreateSessionAsync() | createSession() |

| Resume session | resumeSession() | resume_session() | ResumeSession() | ResumeSessionAsync() | resumeSession() |

| Final content | event.data.content | event.data.content | *event.Data.Content | evt.Data.Content | event.getData().content() |

| Delta content | event.data.deltaContent | event.data.delta_content | *event.Data.DeltaContent | evt.Data.DeltaContent | event.getData().deltaContent() |

| Skills field | skillDirectories | skill_directories | SkillDirectories | SkillDirectories | setSkillDirectories(...) |

Common gotchas

• The SDK is public preview, so older examples drift quickly.
• Hardcoded model tables get stale; prefer runtime discovery.
• destroy() still appears in older examples but disconnect() is the current method.
• A missing permission handler causes confusion fast; treat it as required for real sessions.
• assistant.message and assistant.message_delta use event.data.*, not top-level event.content.
• Streaming/event subscriptions should be attached before send().
• Session resumption without a caller-provided sessionId is awkward to operationalize.

Local reference files in this skill

• references/working-examples.md - current starter examples, including tools and resume patterns
• references/event-system.md - event names, lifecycle, and language access patterns
• references/cli-agents-mcp.md - custom agents, skills, MCP, headless CLI, and config locations
• references/troubleshooting.md - common failures, debug logging, auth, permissions, and transport issues