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

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 exports the Copilot class and Session interface
• Python: python/copilot_sdk/session.py provides the session manager
• Go: go/session.go implements the session lifecycle
• Rust: rust/src/session.rs handles the async session runtime
• .NET: dotnet/src/Session.cs provides the managed session wrapper
• Java: 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
• go/rpc.go
• 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 and go/session_fs_provider.go
• SQLite: Durable database storage via 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
• python/copilot_sdk/toolset.py
• 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, and 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 and 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
• go/telemetry.go
• 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 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:

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:

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:

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, python/copilot_sdk/session.py, go/session.go, rust/src/session.rs, dotnet/src/Session.cs, java/src/main/java/com/github/copilot/Session.java
JSON-RPC Types	nodejs/src/generated/rpc.ts, go/rpc.go, rust/src/generated/rpc.rs
Tool Registration	nodejs/src/toolSet.ts, python/copilot_sdk/toolset.py, go/toolset.go
Hook Implementations	nodejs/src/hooks/*, python/copilot_sdk/hooks.py, go/hooks.go
State Persistence	nodejs/src/sessionFsProvider.ts, go/session_fs_provider.go, rust/src/session_fs.rs
CLI Integration	nodejs/src/ffiRuntimeHost.ts, python/copilot_sdk/ffi.py, go/ffiRuntimeHost.go
MCP Client	nodejs/src/mcpServer.ts, go/mcp_server.go
Telemetry	nodejs/src/telemetry.ts, go/telemetry.go, 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 or python/copilot_sdk/session.py, the underlying transport layer in 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 and 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 or 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), 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}