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.

Your App tools Β· hooks Β· state permissions Β· UI SDK Client CopilotClient CopilotSession typed events Copilot CLI agent loop tool dispatch compaction model routing auth LLM calls happen here JSON-RPC stdio / TCP events flow back out the same pipe β€” that is your entire observability surface

What you own vs. what the runtime owns

ConcernWho implements itYour lever
The tool-use loopCopilot CLINothing β€” you observe turns
Each LLM API callCopilot CLImodel, reasoningEffort, capi.autoTier
Tool executionEither β€” CLI built-ins, or your handlerstools: [defineTool(...)]
Approval of an actionYour handler decides, CLI enforcesonPermissionRequest, hooks.onPreToolUse
Context window managementCopilot CLIinfiniteSessions.backgroundCompactionThreshold
PersistenceCopilot CLIsessionId, sessionFs, baseDirectory
AuthenticationCopilot CLIgitHubToken, BYOK provider, mode: "empty"
Telemetry plumbingCopilot CLI exportstelemetry: { otlpEndpoint }
Design consequence: because the CLI owns the loop, "production-grade" in this SDK means configuration and interception, not re-implementation. Nearly every serious capability is expressed as one of four things: a session option, a hook, a permission decision, or an RPC call on 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.

Note the 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:

CallReturnsUse when
session.send({ prompt })Immediately, with a message IDFire-and-forget, or you are driving the UI from events
session.sendAndWait({ prompt })Wait for session.idle, then the final assistant messageRequest/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"),
});
A trap that costs an afternoon: extra args like --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 withKey config
HobbyistBundled CLI (default)Nothing β€” new CopilotClient()
Internal app devGitHub OAuth + backend servicesgitHubToken, useLoggedInUser: false
ISV / productBYOK or OAuthprovider: { type, endpoint, apiKey }
Platform devBackend services + multi-tenancymode: "empty", per-session tokens, sessionFs
Containerised / serverlessExternal headless CLIRuntimeConnection.forUri(...), baseDirectory
Token angle: the CLI's default 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:

CapabilityTSNotable 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?

Further Reading