GitHub Copilot SDK: Core Features and Architecture for Building AI Agents

The GitHub Copilot SDK is a multi-language toolkit that embeds the Copilot CLI's agentic LLM runtime into your applications via JSON-RPC, enabling autonomous tool execution, custom agent definitions, and persistent sessions across Node.js, Python, Go, .NET, Rust, and Java.

The GitHub Copilot SDK provides language-specific libraries that let you integrate GitHub Copilot's agentic AI capabilities directly into your own applications. Unlike simple API wrappers, this SDK spawns or connects to a Copilot CLI process and manages the full "agent loop" where LLMs can request tool executions across multiple turns until tasks complete.

Core Architecture: JSON-RPC and the Agent Loop

The SDK operates as a thin transport layer that forwards prompts, receives streaming events, and relays tool-execution results via JSON-RPC. According to the source code in nodejs/src/client.ts, the CopilotClient class manages the lifecycle of the underlying Copilot CLI process, automatically spawning it unless you supply an external server URL.

The architectural flow follows this pattern:

• App → SDK Session → JSON-RPC → Copilot CLI → LLM

In nodejs/src/session.ts, the Session class represents a single logical conversation. It wraps the JSON-RPC client, tracks event listeners, and exposes high-level methods such as session.send(), session.sendAndWait(), and session.on(). This session runs the agent loop, where the LLM may request tools, the CLI executes them, and the loop repeats until the model emits a task_complete signal or reaches an idle state.

Key Features of the GitHub Copilot SDK

Agent Loop and Multi-Turn Execution

The Agent Loop is the core mechanism that processes prompts from initial input to session.idle. It handles multiple turns per user message, allowing the LLM to request tool executions, receive results, and iterate. This feature is documented in docs/features/agent-loop.md and enables complex autonomous workflows.

Hooks and Permission Control

The Hooks system in the hooks/ directory provides interception points for every event type. You can implement onPermissionRequest to approve or deny tool calls before execution, onToolExecutionStart to log operations, or transform results before they reach the model. This is the primary extension mechanism for policy enforcement and custom behavior.

Custom Agents and Fleet Mode

Custom Agents allow you to define sub-agents with scoped toolsets and specific instructions using defineAgent(). For large-scale parallel processing, Fleet Mode enables you to run many sub-agents simultaneously using client.createFleet(), documented in docs/features/fleet-mode.md.

MCP Server Integration

The SDK supports MCP (Model Context Protocol) Servers, allowing you to plug in external tool providers that speak the Model Context Protocol. This makes the SDK tool-agnostic and extensible beyond the built-in Copilot CLI tools.

Session Persistence and State Management

Using nodejs/src/sessionFsProvider.ts, the SDK persists event logs and full session state to a configurable file system (local SQLite or custom storage). This Session Persistence feature allows you to save and resume sessions across application restarts, restoring the exact event sequence so the model can continue where it left off.

Remote and Cloud Sessions

Remote Sessions allow you to share locally hosted sessions with GitHub web and mobile interfaces via Mission Control, while Cloud Sessions enable running on GitHub-hosted compute. These features are documented in docs/features/remote-sessions.md and docs/features/cloud-sessions.md.

Additional Capabilities

• Skills: Load reusable prompt modules from directories using the prompt-library pattern
• Plugin Directories: Bundle skills, hooks, agents, and MCP servers as single loadable units
• Image Input: Attach images to sessions for multimodal LLM calls
• Streaming Events: Subscribe to over 40 real-time event types including turn start/end and tool execution
• Steering & Queueing: Control message delivery order with immediate steering versus sequential queueing

Core Components Deep Dive

CopilotClient (nodejs/src/client.ts)

The CopilotClient class manages authentication, logging, telemetry, and the CLI process lifecycle. It provides factory methods for creating sessions and fleets, handling the underlying RPC connection setup automatically.

Session (nodejs/src/session.ts)

The Session abstraction handles the conversation state and RPC communication. It maintains the event emitter pattern for streaming and provides the sendAndWait() method for synchronous-style interactions with the asynchronous agent loop.

ToolSet (nodejs/src/toolSet.ts)

Tools are declared using defineTool() with Zod schemas for parameter validation. The ToolSet helper translates tool definitions into RPC messages that the CLI executes, bridging your TypeScript/JavaScript implementations with the LLM's tool-calling interface.

Telemetry (nodejs/src/telemetry.ts)

The telemetry system emits usage metrics including turn counts and tool usage frequencies, helping you monitor costs and performance characteristics of your AI implementations.

Practical Implementation Examples

Basic Session with Custom Tools

This example from nodejs/examples/basic-example.ts demonstrates creating a session with a custom tool:

import { z } from "zod";
import { approveAll, CopilotClient, defineTool } from "@github/copilot-sdk";

const facts = {
  javascript: "JavaScript was created in 10 days by Brendan Eich in 1995.",
  node: "Node.js lets you run JavaScript outside the browser using the V8 engine."
};

const lookupFact = defineTool("lookup_fact", {
  description: "Returns a fun fact about a given topic.",
  parameters: z.object({ topic: z.string().describe("e.g. 'javascript'") }),
  handler: ({ topic }) => facts[topic.toLowerCase()] ?? `No fact for ${topic}.`,
});

await using client = new CopilotClient({ logLevel: "info" });
await using session = await client.createSession({
  onPermissionRequest: approveAll,
  tools: [lookupFact],
});

session.on((ev) => console.log(`⚡ ${ev.type}`, ev.data));

console.log(await session.sendAndWait("Tell me 2+2"));
console.log(await session.sendAndWait("Use lookup_fact to tell me about 'node'"));

Implementing Permission Hooks

Restrict tool access using the hooks system:

await using client = new CopilotClient();
await using session = await client.createSession({
  onPermissionRequest: async (req) => {
    // Disallow any tool named "delete_file"
    if (req.tool.name === "delete_file") return { approve: false };
    return { approve: true };
  },
});

Defining Fleet Mode Agents

Create specialized agents and run them in parallel:

import { defineAgent } from "@github/copilot-sdk";

const codeWriter = defineAgent("code_writer", {
  instructions: "Write TypeScript functions based on user specs.",
  tools: [/* list of allowed tools */],
});

await using client = new CopilotClient();
await using fleet = await client.createFleet([codeWriter, /* other agents */]);

Subscribing to Streaming Events

Monitor session activity in real-time:

session.on("assistant.turn_start", (ev) => console.log("Turn start", ev));
session.on("tool.execution_complete", (ev) => console.log("Tool result", ev));

Summary

• The GitHub Copilot SDK wraps the Copilot CLI via JSON-RPC to provide agentic LLM capabilities in Node.js, Python, Go, .NET, Rust, and Java
• Core components include the CopilotClient class in nodejs/src/client.ts, Session management in nodejs/src/session.ts, and tool definitions via nodejs/src/toolSet.ts
• The agent loop enables multi-turn conversations where the LLM can request tool executions until emitting a task_complete signal
• Hooks in the hooks/ directory allow interception of permission requests and tool execution results for policy enforcement
• Fleet mode supports parallel agent execution, while MCP servers enable integration with external Model Context Protocol providers
• Session persistence via nodejs/src/sessionFsProvider.ts allows saving and resuming conversations across application restarts

Frequently Asked Questions

What is the GitHub Copilot SDK used for?

The GitHub Copilot SDK allows developers to embed GitHub Copilot's agentic AI runtime directly into applications, enabling autonomous task execution, tool orchestration, and multi-turn conversations with persistent state. It supports building AI assistants that can run in autopilot mode or interactively across multiple programming languages.

How does the SDK communicate with the Copilot LLM?

The SDK communicates via JSON-RPC with a spawned Copilot CLI process or remote server, acting as a transport layer that forwards prompts and receives streaming events. This architecture is implemented in nodejs/src/client.ts and nodejs/src/session.ts, where the CopilotClient manages the CLI lifecycle and Session handles the RPC messaging.

Can I restrict which tools the LLM is allowed to call?

Yes, the SDK provides a hooks system that allows you to intercept permission requests before tool execution. By implementing the onPermissionRequest hook in your session configuration, you can approve or deny specific tools based on their names or parameters, effectively enforcing security policies.

Does the SDK support multiple agents working in parallel?

Yes, through Fleet Mode, you can define multiple sub-agents using the defineAgent function and run them in parallel using client.createFleet(). This is documented in docs/features/fleet-mode.md and enables large-scale workstreams where specialized agents handle different aspects of a task simultaneously.

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