copilot-sdk

Files (5)

• SKILL.md
• cli-agents-mcp.md · references/
• event-system.md · references/
• troubleshooting.md · references/
• working-examples.md · references/

SKILL.md (first lines)

# 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:

```bash
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` |

From intellectronica/agent-skills, CC0-1.0.

More from intellectronica/agent-skills