# API Structure of the GitHub Copilot SDK: Multi-Language Architecture and JSON-RPC Protocol

> Explore the GitHub Copilot SDK API structure. Understand its multi-language architecture, JSON-RPC protocol, and key features like session management and tool definitions.

- Repository: [GitHub/copilot-sdk](https://github.com/github/copilot-sdk)
- Tags: api-reference
- Published: 2026-07-20

---

**The GitHub Copilot SDK exposes a layered API structure built around language-specific client libraries that communicate with a backing AI engine via JSON-RPC, supporting session management, tool definitions, hooks, and optional MCP server integration across Node.js, Python, Go, Rust, .NET, and Java.**

The `github/copilot-sdk` repository provides a comprehensive framework for embedding Copilot-powered AI agents into applications. The API structure abstracts large language model interactions through standardized protocols while offering language-specific conveniences for tool registration, lifecycle hooks, and state persistence.

## Core Architectural Components

### SDK Client Library

The **SDK Client Library** serves as the language-specific entry point for all operations. It creates session objects, defines tools, registers hooks, and manages event streaming. Each implementation follows similar patterns across supported languages:

- **Node.js**: [`nodejs/src/session.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/session.ts) exports the `Copilot` class and `Session` interface
- **Python**: [`python/copilot_sdk/session.py`](https://github.com/github/copilot-sdk/blob/main/python/copilot_sdk/session.py) provides the session manager
- **Go**: [`go/session.go`](https://github.com/github/copilot-sdk/blob/main/go/session.go) implements the session lifecycle
- **Rust**: [`rust/src/session.rs`](https://github.com/github/copilot-sdk/blob/main/rust/src/session.rs) handles the async session runtime
- **.NET**: [`dotnet/src/Session.cs`](https://github.com/github/copilot-sdk/blob/main/dotnet/src/Session.cs) provides the managed session wrapper
- **Java**: [`java/src/main/java/com/github/copilot/Session.java`](https://github.com/github/copilot-sdk/blob/main/java/src/main/java/com/github/copilot/Session.java) offers the JVM-compatible implementation

### JSON-RPC Transport Layer

All SDK clients communicate with the AI backend through a **JSON-RPC Transport** layer. This transport serializes requests (including `MessageOptions` and tool calls) and deserializes responses (tool results and streaming events) over STDIO or TCP connections. The transport implementations reside in:

- [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts)
- [`go/rpc.go`](https://github.com/github/copilot-sdk/blob/main/go/rpc.go)
- [`rust/src/generated/rpc.rs`](https://github.com/github/copilot-sdk/blob/main/rust/src/generated/rpc.rs)

The transport layer remains agnostic to the underlying language while maintaining strict type contracts between the client and the Copilot CLI or custom backend.

### Session State Management

The **Session State** component persists conversation history, token usage metrics, and temporary files across interactions. The SDK provides three storage backends:

- **In-memory**: Volatile storage for ephemeral sessions
- **Filesystem**: Plain file persistence via [`nodejs/src/sessionFsProvider.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/sessionFsProvider.ts) and [`go/session_fs_provider.go`](https://github.com/github/copilot-sdk/blob/main/go/session_fs_provider.go)
- **SQLite**: Durable database storage via [`nodejs/src/sessionFsProvider.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/sessionFsProvider.ts) (Node.js) and equivalent providers in other languages

### Tool Definition Layer

The **Tool Definition Layer** allows developers to declare functions that the LLM can invoke during conversations. Tools are described using input/output schemas (Zod for Node.js, JSON Schema for Python) and registered through:

- [`nodejs/src/toolSet.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/toolSet.ts)
- [`python/copilot_sdk/toolset.py`](https://github.com/github/copilot-sdk/blob/main/python/copilot_sdk/toolset.py)
- [`go/toolset.go`](https://github.com/github/copilot-sdk/blob/main/go/toolset.go)

The SDK automatically generates type-safe definitions from schema declarations or accepts manually-written signatures for advanced use cases.

### Hook System

The **Hook System** provides interception points throughout the session lifecycle. Located in `nodejs/src/hooks/*`, [`python/copilot_sdk/hooks.py`](https://github.com/github/copilot-sdk/blob/main/python/copilot_sdk/hooks.py), and [`go/hooks.go`](https://github.com/github/copilot-sdk/blob/main/go/hooks.go), this system enables applications to:

- Approve, deny, or modify tool calls via `preToolUse` hooks
- Transform tool results via `postToolUse` hooks
- Intercept user prompts via `userPromptSubmitted` hooks
- Monitor session lifecycle events

### MCP Server Integration

The SDK optionally connects to **Model-Context-Protocol (MCP) Servers** for extended capabilities or custom model backends. The MCP client implementation in [`nodejs/src/mcpServer.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/mcpServer.ts) and [`go/mcp_server.go`](https://github.com/github/copilot-sdk/blob/main/go/mcp_server.go) allows the SDK to delegate specific skills or inference tasks to external services.

### Telemetry and Observability

Built-in **OpenTelemetry instrumentation** captures request/response metrics, errors, and custom spans across all RPC traffic. Implementation files include:

- [`nodejs/src/telemetry.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/telemetry.ts)
- [`go/telemetry.go`](https://github.com/github/copilot-sdk/blob/main/go/telemetry.go)
- [`rust/src/telemetry.rs`](https://github.com/github/copilot-sdk/blob/main/rust/src/telemetry.rs)

## Request Lifecycle and Data Flow

The API structure orchestrates the following execution flow:

1. **Initialization**: The application imports the SDK, instantiates the client (e.g., `new Copilot()`), and configures authentication via GitHub OAuth, BYOK, or custom tokens.

2. **Configuration**: Developers register tools with schemas and attach hooks to lifecycle events.

3. **Connection**: The SDK launches the Copilot CLI binary (via [`nodejs/src/ffiRuntimeHost.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/ffiRuntimeHost.ts) or language equivalents) and establishes a JSON-RPC channel over STDIO or TCP.

4. **Interaction**: Applications send prompts using `session.send({ prompt })`, which transmits the request over the RPC layer.

5. **Tool Invocation**: When the model requests tool execution, the SDK marshals parameters, invokes the user-defined handler, and returns results over RPC. Hooks can modify this round-trip at `preToolUse` and `postToolUse` stages.

6. **Persistence**: Session state saves to the configured backend (filesystem or SQLite) via `session.save()`, enabling resumption of long-running conversations.

7. **Telemetry**: All RPC traffic and internal events export through OpenTelemetry pipelines for observability.

## Implementation Examples

### Creating Sessions and Defining Tools

This TypeScript example demonstrates session initialization, tool registration, and hook attachment:

```typescript
import { Copilot } from '@github/copilot-sdk';

// Initialize the SDK (authentication auto-detected from environment)
const copilot = new Copilot();

// Define a translation tool with JSON schema
copilot.tools.define({
  name: 'translate',
  description: 'Translate English text to French.',
  input_schema: { 
    type: 'object', 
    properties: { text: { type: 'string' } }, 
    required: ['text'] 
  },
  async handler({ text }) {
    return `🗣️ ${text} → Français`;
  },
});

// Register pre-tool hook for logging
copilot.hooks.preToolUse(async (event) => {
  console.log('🔧 Tool requested:', event.tool_name, event.args);
  return event; // Return unchanged to allow execution
});

// Start session and send prompt
const session = await copilot.startSession();
const response = await session.send({ prompt: 'How do I say “hello” in French?' });
console.log('🤖 Copilot:', response.content);

```

### Persisting Session State with SQLite

Configure durable storage for session resumption across application restarts:

```typescript
import { Copilot } from '@github/copilot-sdk';
import { SqliteSessionFsProvider } from '@github/copilot-sdk/session-fs';

const copilot = new Copilot({
  sessionFsProvider: new SqliteSessionFsProvider({ dbPath: './session.db' })
});

const session = await copilot.startSession({ sessionId: 'my-app-session' });
await session.send({ prompt: 'Explain the architecture of the Copilot SDK.' });
await session.save(); // Persists history and token usage

```

### Connecting to MCP Servers

Integrate with custom model backends via the Model-Context-Protocol:

```typescript
import { Copilot } from '@github/copilot-sdk';

const copilot = new Copilot({
  mcp: {
    url: 'http://localhost:8080',
    timeoutMs: 10_000,
  }
});

const session = await copilot.startSession();
await session.send({ prompt: 'Run my custom skill “code-review”.' });

```

## Key Source Files by Component

| Component | Primary Implementations |
|-----------|------------------------|
| **Session Management** | [`nodejs/src/session.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/session.ts), [`python/copilot_sdk/session.py`](https://github.com/github/copilot-sdk/blob/main/python/copilot_sdk/session.py), [`go/session.go`](https://github.com/github/copilot-sdk/blob/main/go/session.go), [`rust/src/session.rs`](https://github.com/github/copilot-sdk/blob/main/rust/src/session.rs), [`dotnet/src/Session.cs`](https://github.com/github/copilot-sdk/blob/main/dotnet/src/Session.cs), [`java/src/main/java/com/github/copilot/Session.java`](https://github.com/github/copilot-sdk/blob/main/java/src/main/java/com/github/copilot/Session.java) |
| **JSON-RPC Types** | [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts), [`go/rpc.go`](https://github.com/github/copilot-sdk/blob/main/go/rpc.go), [`rust/src/generated/rpc.rs`](https://github.com/github/copilot-sdk/blob/main/rust/src/generated/rpc.rs) |
| **Tool Registration** | [`nodejs/src/toolSet.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/toolSet.ts), [`python/copilot_sdk/toolset.py`](https://github.com/github/copilot-sdk/blob/main/python/copilot_sdk/toolset.py), [`go/toolset.go`](https://github.com/github/copilot-sdk/blob/main/go/toolset.go) |
| **Hook Implementations** | `nodejs/src/hooks/*`, [`python/copilot_sdk/hooks.py`](https://github.com/github/copilot-sdk/blob/main/python/copilot_sdk/hooks.py), [`go/hooks.go`](https://github.com/github/copilot-sdk/blob/main/go/hooks.go) |
| **State Persistence** | [`nodejs/src/sessionFsProvider.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/sessionFsProvider.ts), [`go/session_fs_provider.go`](https://github.com/github/copilot-sdk/blob/main/go/session_fs_provider.go), [`rust/src/session_fs.rs`](https://github.com/github/copilot-sdk/blob/main/rust/src/session_fs.rs) |
| **CLI Integration** | [`nodejs/src/ffiRuntimeHost.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/ffiRuntimeHost.ts), [`python/copilot_sdk/ffi.py`](https://github.com/github/copilot-sdk/blob/main/python/copilot_sdk/ffi.py), [`go/ffiRuntimeHost.go`](https://github.com/github/copilot-sdk/blob/main/go/ffiRuntimeHost.go) |
| **MCP Client** | [`nodejs/src/mcpServer.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/mcpServer.ts), [`go/mcp_server.go`](https://github.com/github/copilot-sdk/blob/main/go/mcp_server.go) |
| **Telemetry** | [`nodejs/src/telemetry.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/telemetry.ts), [`go/telemetry.go`](https://github.com/github/copilot-sdk/blob/main/go/telemetry.go), [`rust/src/telemetry.rs`](https://github.com/github/copilot-sdk/blob/main/rust/src/telemetry.rs) |

## Summary

- The GitHub Copilot SDK uses a **language-specific client layer** wrapping a JSON-RPC core to communicate with AI backends via STDIO or TCP.
- **Session management** supports in-memory, filesystem, and SQLite persistence for conversation continuity.
- The **Tool Definition Layer** enables LLM invocation of application functions with type-safe schema validation.
- **Hooks** provide interception points for tool calls, prompt submission, and lifecycle events.
- **MCP Server integration** extends capabilities through external model services or custom skills.
- **OpenTelemetry instrumentation** provides built-in observability for all RPC traffic and internal operations.

## Frequently Asked Questions

### How does the SDK maintain API consistency across different programming languages?

The SDK achieves cross-language consistency through a shared **JSON-RPC protocol** that defines standard message formats for prompts, tool calls, and streaming responses. While each language implementation (Node.js, Python, Go, Rust, .NET, Java) provides idiomatic wrappers in files like [`nodejs/src/session.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/session.ts) or [`python/copilot_sdk/session.py`](https://github.com/github/copilot-sdk/blob/main/python/copilot_sdk/session.py), the underlying transport layer in [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts) and equivalents ensures uniform behavior across all platforms.

### What transport protocols does the Copilot SDK API support?

The API structure supports **STDIO** and **TCP** transports for the JSON-RPC communication channel between the SDK client and the Copilot CLI or custom backend. The transport layer abstraction in files like [`go/rpc.go`](https://github.com/github/copilot-sdk/blob/main/go/rpc.go) and [`nodejs/src/generated/rpc.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/generated/rpc.ts) handles serialization of `MessageOptions` and streaming events, allowing applications to choose between local process communication or networked backends.

### Can I integrate custom LLM backends with the Copilot SDK?

Yes, the SDK supports custom backends through the **Model-Context-Protocol (MCP) Server** integration. By configuring an MCP endpoint in [`nodejs/src/mcpServer.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/mcpServer.ts) or [`go/mcp_server.go`](https://github.com/github/copilot-sdk/blob/main/go/mcp_server.go), applications can redirect specific skills or model inference tasks to external services while maintaining the standard SDK API structure for session management and tool definitions.

### Where does the SDK store conversation state and how can I configure it?

The SDK provides **pluggable persistence** through the Session State component, supporting in-memory storage, filesystem backends ([`nodejs/src/sessionFsProvider.ts`](https://github.com/github/copilot-sdk/blob/main/nodejs/src/sessionFsProvider.ts)), and SQLite databases (`SqliteSessionFsProvider`). Configure the provider during SDK initialization to enable durable storage of conversation history, token usage, and temporary files for multi-turn interactions or session resumption.