/copilot-sdk

name: copilot-sdk
description: This skill helps with GitHub Copilot SDK work across Node.js/TypeScript, Python, Go, .NET, and Java. It covers setup, authentication, permissions, streaming events, custom tools, custom agents, MCP servers, hooks, skills, and session persistence.

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](https://github.com/github/copilot-sdk)
• [Documentation index](https://github.com/github/copilot-sdk/blob/main/docs/index.md)
• [Getting started guide](https://github.com/github/copilot-sdk/blob/main/docs/getting-started.md)
• [Setup guides](https://github.com/github/copilot-sdk/blob/main/docs/setup/index.md)
• [Local CLI setup](https://github.com/github/copilot-sdk/blob/main/docs/setup/local-cli.md)
• [Bundled CLI setup](https://github.com/github/copilot-sdk/blob/main/docs/setup/bundled-cli.md)
• [Backend services setup](https://github.com/github/copilot-sdk/blob/main/docs/setup/backend-services.md)
• [Scaling and multi-tenancy](https://github.com/github/copilot-sdk/blob/main/docs/setup/scaling.md)
• [Azure Managed Identity with BYOK](https://github.com/github/copilot-sdk/blob/main/docs/setup/azure-managed-identity.md)
• [Authentication](https://github.com/github/copilot-sdk/blob/main/docs/auth/index.md)
• [BYOK](https://github.com/github/copilot-sdk/blob/main/docs/auth/byok.md)
• [Features index](https://github.com/github/copilot-sdk/blob/main/docs/features/index.md)
• [Image input](https://github.com/github/copilot-sdk/blob/main/docs/features/image-input.md)
• [Steering and queueing](https://github.com/github/copilot-sdk/blob/main/docs/features/steering-and-queueing.md)
• [OpenTelemetry instrumentation](https://github.com/github/copilot-sdk/blob/main/docs/observability/opentelemetry.md)
• [Troubleshooting](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/debugging.md)
• [SDK/CLI compatibility](https://github.com/github/copilot-sdk/blob/main/docs/troubleshooting/compatibility.md)

Language-specific docs

• [Node.js / TypeScript README](https://github.com/github/copilot-sdk/blob/main/nodejs/README.md)
• [Python README](https://github.com/github/copilot-sdk/blob/main/python/README.md)
• [Go README](https://github.com/github/copilot-sdk/blob/main/go/README.md)
• [.NET README](https://github.com/github/copilot-sdk/blob/main/dotnet/README.md)
• [Java SDK repository](https://github.com/github/copilot-sdk-java)

Copilot CLI and GitHub Docs

• [About GitHub Copilot CLI](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli)
• [Using GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli)
• [Custom agents configuration reference](https://docs.github.com/en/copilot/reference/custom-agents-configuration)
• [Enhancing agent mode with MCP](https://docs.github.com/en/copilot/tutorials/enhance-agent-mode-with-mcp)
• [Supported models](https://docs.github.com/en/copilot/reference/ai-models/supported-models)

Recipes and examples

• [Copilot SDK cookbook](https://github.com/github/awesome-copilot/blob/main/cookbook/copilot-sdk/README.md)
• [Node.js samples](https://github.com/github/copilot-sdk/tree/main/nodejs/samples)
• [Go samples](https://github.com/github/copilot-sdk/tree/main/go/samples)
• [.NET samples](https://github.com/github/copilot-sdk/tree/main/dotnet/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 / TypeSc