copilot-sdk-cpp

C++ SDK for interacting with the Copilot CLI agent runtime (JSON-RPC over stdio or TCP).

Version 0.4.2

Targets Copilot CLI 1.0.102-1 and SDK protocol version 3.

• Correlate message waiters with the originating request, including sub-agent, abort, and autopilot events; receive structured JSON with response_schema and send_and_wait_structured.
• Replace session tools at runtime with Session::set_tools; use tool namespaces and per-invocation agent/request identifiers.
• Supply session skill providers, installation confirmation handlers, and extension launch providers. Handle MCP authentication token updates or runtime refresh.
• Configure diagnostics, agent/hook directories, sandboxing, image generation, transcript recovery, and the expanded provider/agent options.
• Cancel incoming JSON-RPC requests and run request callbacks independently of the reader. Retire session callbacks on teardown and shut down owned runtimes gracefully.
• Use generated binary SessionFs request/result types and report partial writes with SessionFsError::write_changed.

Known limitations: experimental AHP hosting is not implemented. The in-process macOS UI-thread dispatcher is not provided.

Build

Requirements: CMake 3.20+ and a C++20 compiler.

cmake -S . -B build
cmake --build build --config Release

Official protocol baseline and code generation

schemas/official-baseline.json pins the official SDK commit, protocol version, schema hashes, and the complete generated surface: 1,899 API definitions, 679 session-event definitions, 619 RPC methods, and 163 event variants. Generated wire-preserving types live under include/copilot/generated/; the existing handwritten public API remains the ergonomic layer.

# Regenerate from the committed baseline
cmake --build build --target copilot_codegen

# Fail if committed generated headers are stale
cmake --build build --target copilot_codegen_check

To refresh from a checked-out official SDK and the matching CLI package schemas:

python tools/generate_protocol_types.py --refresh \
  --official-sdk-root ../copilot-sdk \
  --api-schema <path-to-api.schema.json> \
  --session-events-schema <path-to-session-events.schema.json>

Current public API surface

ClientOptions supports SDK modes plus stdio, TCP, URI, and declared in-process runtime connections. Session create/resume requests expose the current official configuration fields while preserving the existing handwritten C++ API. Session::invoke/invoke_typed provide low-level access, with typed convenience wrappers for MCP, authentication, agents, skills, tasks, commands, history, usage, and remote-session operations.

Advanced parity includes:

• RuntimeConnection::for_in_process() using the official copilot_runtime_* native ABI (prebuilds/<platform>/runtime.node).
• CopilotRequestHandler and WebSocket handlers for streamed model-layer I/O.
• Automatic MCP OAuth event handling and pending-request responses.
• create_canvas, define_workflow, Session::workflow(), and join_session helpers for canvas, workflow, and extension consumers.

Custom Tools

Custom tools are provided when creating or resuming a session. The SDK auto-generates JSON schemas from C++ types.

Fluent Builder (Recommended)

#include <copilot/tool_builder.hpp>

// Fluent builder with full control over parameters
auto calc = copilot::ToolBuilder("calculator", "Perform math calculations")
    .param<std::string>("expression", "Math expression to evaluate")
    .handler([](std::string expression) {
        // Evaluate expression...
        return "42";
    });

// With enum constraints and default values
auto search = copilot::ToolBuilder("search", "Search the web")
    .param<std::string>("query", "Search query")
    .param<int>("limit", "Max results").default_value(10)
    .param<std::string>("sort", "Sort order").one_of("relevance", "date")
    .handler([](std::string query, int limit, std::string sort) {
        return "Results for: " + query;
    });

// Use in session
copilot::SessionConfig config;
config.tools = {calc, search};
auto session = client.create_session(config).get();

Quick One-Liner with make_tool

// Simple tools with auto-generated schema
auto echo = copilot::make_tool(
    "echo", "Echo a message",
    [](std::string message) { return message; },
    {"message"}
);

auto add = copilot::make_tool(
    "add", "Add two numbers",
    [](double a, double b) { return std::to_string(a + b); },
    {"first", "second"}
);

// Optional parameters (use std::optional)
auto greet = copilot::make_tool(
    "greet", "Greet someone",
    [](std::string name, std::optional<std::string> title) {
        return title ? "Hello, " + *title + " " + name + "!"
                     : "Hello, " + name + "!";
    },
    {"name", "title"}
);

config.tools = {echo, add, greet};

See examples/tools.cpp and examples/resume_with_tools.cpp for complete examples.

BYOK (Bring Your Own Key)

Use your own API key instead of GitHub Copilot authentication.

Method 1: Explicit Configuration

copilot::ProviderConfig provider;
provider.api_key = "sk-your-api-key";
provider.base_url = "https://api.openai.com/v1";
provider.type = "openai";

copilot::SessionConfig config;
config.provider = provider;
config.model = "gpt-4";
auto session = client.create_session(config).get();

Method 2: Environment Variables

Set environment variables:

export COPILOT_SDK_BYOK_API_KEY=sk-your-api-key
export COPILOT_SDK_BYOK_BASE_URL=https://api.openai.com/v1   # Optional, defaults to OpenAI
export COPILOT_SDK_BYOK_PROVIDER_TYPE=openai                 # Optional, defaults to "openai"
export COPILOT_SDK_BYOK_MODEL=gpt-4                          # Optional

Then enable auto-loading in your code:

copilot::SessionConfig config;
config.auto_byok_from_env = true;  // Load from COPILOT_SDK_BYOK_* env vars
auto session = client.create_session(config).get();

Precedence (for each field):

1. Explicit value in SessionConfig (highest priority)
2. Environment variable (if auto_byok_from_env = true)
3. Default Copilot behavior (lowest priority)

Note: auto_byok_from_env defaults to false for backwards compatibility. Existing code will not be affected by setting these environment variables.

Checking Environment Configuration

// Check if BYOK env vars are configured
if (copilot::ProviderConfig::is_env_configured()) {
    // COPILOT_SDK_BYOK_API_KEY is set
}

// Load provider config from env (returns nullopt if not configured)
if (auto provider = copilot::ProviderConfig::from_env()) {
    // Use *provider
}

// Load model from env
if (auto model = copilot::ProviderConfig::model_from_env()) {
    // Use *model
}

Install / Package

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=./install
cmake --build build --config Release
cmake --install build --config Release

Related Projects

Project	Language	Description
claude-agent-sdk-cpp	C++	C++ port of the Claude Agent SDK
claude-agent-sdk-dotnet	C#	.NET port of the Claude Agent SDK
fastmcpp	C++	C++ port of FastMCP for building MCP servers

Projects Using This SDK

Project	Description
windbg_copilot	WinDbg extension for AI-assisted debugging
lldb_copilot	LLDB plugin for AI-assisted debugging
libagents	Unified C++ library for AI agent providers

Want to add your project? Open a PR!

Author

Elias Bachaalany (@0xeb)

Pair-programmed with Claude Code and Codex.

License

Copyright 2025 Elias Bachaalany

Licensed under the MIT License. See LICENSE for details.

This is a C++ port of copilot-sdk by GitHub.