Foundations: What the Copilot SDK Actually Is
Lesson 1: Foundations β What the Copilot SDK Actually Is
The single most expensive misunderstanding in this SDK is thinking it is an agent framework. It is not. The GitHub Copilot SDK is a typed transport layer that speaks JSON-RPC to the Copilot CLI, and the CLI is the thing that actually runs the agent: it owns the tool-use loop, prompt assembly, context compaction, model routing, and authentication. Your job is to configure it, observe it, and β critically β to hand it the tools, guardrails, and state it needs.
Once that split clicks, every design decision in the rest of this course becomes obvious. If the CLI owns the loop, you do not write a loop. If the CLI owns permissions, you do not write an authorisation layer β you return a decision. If the CLI owns compaction, you do not build a summariser β you set a threshold.
What you own vs. what the runtime owns
| Concern | Who implements it | Your lever |
|---|---|---|
| The tool-use loop | Copilot CLI | Nothing β you observe turns |
| Each LLM API call | Copilot CLI | model, reasoningEffort, capi.autoTier |
| Tool execution | Either β CLI built-ins, or your handlers | tools: [defineTool(...)] |
| Approval of an action | Your handler decides, CLI enforces | onPermissionRequest, hooks.onPreToolUse |
| Context window management | Copilot CLI | infiniteSessions.backgroundCompactionThreshold |
| Persistence | Copilot CLI | sessionId, sessionFs, baseDirectory |
| Authentication | Copilot CLI | gitHubToken, BYOK provider, mode: "empty" |
| Telemetry plumbing | Copilot CLI exports | telemetry: { otlpEndpoint } |
session.rpc.
Install and your first agent
mkdir copilot-demo
cd copilot-demo
npm init -y --init-type module
npm install @github/copilot-sdk tsx
The Node.js SDK bundles the Copilot CLI, so there is no separate install step β but if you are on Go, Java, or Rust you install the CLI yourself, and copilot --version is the smoke test. Now the whole first agent:
import { CopilotClient } from "@github/copilot-sdk";
const client = new CopilotClient();
const session = await client.createSession({ model: "auto" });
const response = await session.sendAndWait({ prompt: "What is 2 + 2?" });
console.log(response?.data.content);
await client.stop();
process.exit(0);
Run it with npx tsx index.ts. Five lines and you have a working agent β because everything hard is in the CLI.
process.exit(0). The client holds an open JSON-RPC connection to the CLI child process. Without an explicit stop-and-exit your script will hang. This is the single most common "the docs example doesn't work" report.
The two objects you will live in
CopilotClient is the process/connection-level object. It owns the transport to the CLI, authentication defaults, and telemetry. CopilotSession is the conversation-level object: it owns your tools, hooks, permission handler, model, and the event stream.
import { CopilotClient, RuntimeConnection } from "@github/copilot-sdk";
// Client: process + transport + auth + telemetry. Usually ONE per process.
const client = new CopilotClient({
mode: "empty", // safe baseline for servers
telemetry: { otlpEndpoint: "http://localhost:4318" },
connection: RuntimeConnection.forUri(process.env.COPILOT_RUNTIME_URL!),
});
await client.start();
// Session: conversation + tools + hooks + permissions. MANY per process.
const session = await client.createSession({
sessionId: `user-${user.id}-${crypto.randomUUID()}`,
model: "gpt-5.4",
streaming: true,
onPermissionRequest: approveAll,
tools: [lookupOrder],
});
Two methods do almost all the work of talking to an agent:
| Call | Returns | Use when |
|---|---|---|
session.send({ prompt }) | Immediately, with a message ID | Fire-and-forget, or you are driving the UI from events |
session.sendAndWait({ prompt }) | Wait for session.idle, then the final assistant message | Request/response, scripts, batch jobs |
sendAndWait is a convenience over one specific event. You will learn in Lesson 2 exactly which event, and why session.idle β not session.task_complete β is the one you can rely on.
The connection layer is a first-class design choice
Where the CLI runs is the biggest architectural decision you make, and it is expressed as a single connection option:
// Mode A: SDK spawns and owns the CLI process (default, stdio)
const client = new CopilotClient();
// Mode B: SDK spawns the CLI with extra arguments
const client = new CopilotClient({
connection: RuntimeConnection.forStdio({
args: ["--plugin-dir", "./plugins/code-reviewer"],
}),
});
// Mode C: connect to an already-running headless CLI server
const client = new CopilotClient({
connection: RuntimeConnection.forUri("http://127.0.0.1:8080"),
});
--plugin-dir are only forwarded when the SDK spawns the CLI. If you connect with forUri, the SDK is a client of someone else's process β you must pass those flags on the command line that started the runtime server. Silent no-op otherwise.
Five setup paths, one decision tree
The official setup guides are organised by who you are, which is a useful way to think about it:
| You are⦠| Start with | Key config |
|---|---|---|
| Hobbyist | Bundled CLI (default) | Nothing β new CopilotClient() |
| Internal app dev | GitHub OAuth + backend services | gitHubToken, useLoggedInUser: false |
| ISV / product | BYOK or OAuth | provider: { type, endpoint, apiKey } |
| Platform dev | Backend services + multi-tenancy | mode: "empty", per-session tokens, sessionFs |
| Containerised / serverless | External headless CLI | RuntimeConnection.forUri(...), baseDirectory |
mode: "copilot-cli" exposes a large ambient tool set β file reads, search, shell, its own built-in skills. Every one of those tool definitions sits in the system prompt on every single LLM call. Switching a server deployment to mode: "empty" and an explicit availableTools allowlist is simultaneously your biggest security win and your biggest prompt-token saving.
TypeScript is the reference implementation
Six SDKs exist β Node/TypeScript, Python, Go, .NET, Java, Rust β and they all speak the same JSON-RPC protocol, so behaviour is consistent across them. But TypeScript is where the surface is richest and best documented, and several capabilities land there first:
| Capability | TS | Notable gaps elsewhere |
|---|---|---|
| Tool definitions with Zod | β | Python uses Pydantic, Go struct tags, etc. |
session.setTools() (live tool replacement) | β | Experimental; Java needs @AllowCopilotExperimental, .NET raises GHCP001 |
Fleet mode (session.rpc.fleet.start) | β | No verified Java binding on the audited branch |
| BYOK / custom providers | β | API keys never persist β must re-provide on resume |
Session filesystem (sessionFs) | β | No verified public Java option |
Everything in this course is TypeScript. Where a capability is experimental or missing in another language, it is stated explicitly rather than quietly translated.
Version-pinning is a real requirement
The SDK and the CLI are a pair. The SDK's typed events, RPC namespaces, and hook shapes are generated from the runtime's schema. Fleet mode, tool replacement, and the diagnostics API are all marked experimental specifically because the wire contract can move. Pin both in package.json, and treat an SDK upgrade as a runtime upgrade with a release note to read.
π§ Knowledge Check
1. Where does the agent's tool-use loop actually execute?
2. You connect with RuntimeConnection.forUri(url) and pass args: ["--plugin-dir", "./plugins/x"]. What happens?
3. Which session option is the safest baseline for a shared multi-user server, and why?