Architecture

How the Copilot SDK connects your application to GitHub Copilot.

System Overview

┌────────────────────────────────────────────────────────────────────────────┐
│                              YOUR APPLICATION                              │
├────────────────────────────────────────────────────────────────────────────┤
│                                                                            │
│  ┌──────────────────┐         ┌──────────────────┐                        │
│  │  CopilotClient   │─────────│  CopilotSession  │ (1 client : N sessions)│
│  │                  │         │                  │                        │
│  │  - spawn CLI     │         │  - send messages │                        │
│  │  - manage conn   │         │  - receive events│                        │
│  │  - create sess   │         │  - handle tools  │                        │
│  └────────┬─────────┘         └──────────────────┘                        │
│           │                                                                │
│           │ JSON-RPC over stdio (or TCP)                                   │
│           │                                                                │
├───────────┼────────────────────────────────────────────────────────────────┤
│           ▼                                                                │
│  ┌──────────────────┐                                                      │
│  │   Copilot CLI    │  (spawned as subprocess, or external server)         │
│  │                  │                                                      │
│  │  - auth mgmt     │                                                      │
│  │  - model routing │                                                      │
│  │  - API calls     │                                                      │
│  └────────┬─────────┘                                                      │
│           │                                                                │
└───────────┼────────────────────────────────────────────────────────────────┘
            │
            │ HTTPS
            ▼
     ┌──────────────────┐
     │  GitHub Copilot  │  (cloud service)
     │     Service      │
     │                  │
     │  - LLM inference │
     │  - tool routing  │
     └──────────────────┘

Component Deep Dive

CopilotClient

The client is your connection manager. One client per application is typical.

Responsibilities:

• Spawn the Copilot CLI as a child process (or connect to an external server)
• Maintain the JSON-RPC connection
• Handle authentication handshake
• Create and track sessions
• Clean up resources on shutdown

Lifecycle:

create() → [use sessions] → close()

Key configuration:

const client = await CopilotClient.create({
  agent: {
    name: "my-agent",        // Identifies your agent
    version: "1.0.0"
  },
  // Optional: custom CLI path, TCP connection, etc.
});

CopilotSession

Sessions are independent conversations. Each session:

• Has its own message history
• Can have a unique system prompt
• Tracks its own tool calls
• Runs concurrently with other sessions

Lifecycle:

createSession() → [turn loop] → stopSession()

A “turn” is one request-response cycle:

Your message → [streaming events] → [tool calls] → Final response

The Turn Loop

When you send a message, here’s what happens:

1. Your app calls session.send("What's the weather?")

2. SDK sends JSON-RPC request to CLI

3. CLI calls Copilot API with your message + tool definitions

4. Copilot streams back:
   - turnStart event
   - textDelta events (response tokens)
   - toolCall events (if tools needed)
   - turnEnd event

5. If tool called:
   a. Your tool handler executes
   b. Result sent back to Copilot
   c. Copilot continues (may call more tools or finish)

6. Turn completes when Copilot stops generating

JSON-RPC Protocol

The SDK uses JSON-RPC 2.0 for communication. You don’t need to understand the protocol to use the SDK, but it helps for debugging.

Request (SDK → CLI):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session.send",
  "params": {
    "sessionId": "abc123",
    "content": "Hello!"
  }
}

Notification (CLI → SDK, for events):

{
  "jsonrpc": "2.0",
  "method": "session.event",
  "params": {
    "sessionId": "abc123",
    "event": {
      "type": "textDelta",
      "delta": "Hi there"
    }
  }
}

Connection Modes

stdio (default)

• SDK spawns CLI as subprocess
• Communication via stdin/stdout
• Simplest setup, recommended for most cases

TCP

• Connect to externally running CLI server
• Useful for: shared CLI instance, debugging, remote connections

// TCP connection example
const client = await CopilotClient.create({
  agent: { name: "my-agent", version: "1.0.0" },
  connection: {
    type: "tcp",
    host: "localhost",
    port: 8080
  }
});

Resource Management

The SDK manages resources automatically, but you should still clean up:

// Always close when done
try {
  const client = await CopilotClient.create({ ... });
  // ... use client ...
} finally {
  await client.close();
}

What close() does:

• Stops all active sessions
• Terminates the CLI subprocess (if spawned)
• Closes the JSON-RPC connection
• Releases all resources

Error Handling

Errors can occur at multiple levels:

See the Error Handling cookbook recipe for patterns.

Next: Sessions