GitHub Copilot SDK Python Instructions

Core Principles

- The SDK is in technical preview and may have breaking changes

- Requires Python 3.9 or later

- Requires GitHub Copilot CLI installed and in PATH

- Uses async/await patterns throughout (asyncio)

- Supports both async context managers and manual lifecycle management

- Type hints provided for better IDE support

Installation

Always install via pip:

pip install github-copilot-sdk
# or with poetry
poetry add github-copilot-sdk
# or with uv
uv add github-copilot-sdk

Client Initialization

Basic Client Setup

from copilot import CopilotClient, PermissionHandler
import asyncio

async def main():
    async with CopilotClient() as client:
        # Use client...
        pass

asyncio.run(main())

Client Configuration Options

When creating a CopilotClient, use a dict with these keys:

- `cli_path` - Path to CLI executable (default: "copilot" from PATH or COPILOT_CLI_PATH env var)

- `cli_url` - URL of existing CLI server (e.g., "localhost:8080"). When provided, client won't spawn a process

- `port` - Server port (default: 0 for random)

- `use_stdio` - Use stdio transport instead of TCP (default: True)

- `log_level` - Log level (default: "info")

- `auto_start` - Auto-start server (default: True)

- `auto_restart` - Auto-restart on crash (default: True)

- `cwd` - Working directory for the CLI process (default: os.getcwd())

- `env` - Environment variables for the CLI process (dict)

Manual Server Control

For explicit control:

from copilot import CopilotClient
import asyncio

async def main():
    client = CopilotClient({"auto_start": False})
    await client.start()
    # Use client...
    await client.stop()

asyncio.run(main())

Use `force_stop()` when `stop()` takes too long.

Session Management

Creating Sessions

Use a dict for SessionConfig:

session = await client.create_session({
    "on_permission_request": PermissionHandler.approve_all,
    "model": "gpt-5",
    "streaming": True,
    "tools": [...],
    "system_message": { ... },
    "available_tools": ["tool1", "tool2"],
    "excluded_tools": ["tool3"],
    "provider": { ... }
})

Session Config Options

- `session_id` - Custom session ID (str)

- `model` - Model name ("gpt-5", "claude-sonnet-4.5", etc.)

- `tools` - Custom tools exposed to the CLI (list[Tool])

- `system_message` - System message customization (dict)

- `available_tools` - Allowlist of tool names (list[str])

- `excluded_tools` - Blocklist of tool names (list[str])

- `provider` - Custom API provider configuration (BYOK) (ProviderConfig)

- `streaming` - Enable streaming response chunks (bool)

- `mcp_servers` - MCP server configurations (list)

- `custom_agents` - Custom agent configurations (list)

- `config_dir` - Config directory override (str)

- `skill_directories` - Skill directories (list[str])

- `disabled_skills` - Disabled skills (list[str])

- `on_permission_request` - Permission request handler (callable)

Resuming Sessions

session = await client.resume_session("session-id", {
    "on_permission_request": PermissionHandler.approve_all,
    "tools": [my_new_tool]
})

Session Operations

- `session.session_id` - Get session identifier (str)

- `await session.send({"prompt": "...", "attachments": [...]})` - Send message, returns str (message ID)

- `await session.send_and_wait({"prompt": "..."}, timeout=60.0)` - Send and wait for idle, returns SessionEvent | None

- `await session.abort()` - Abort current processing

- `await session.get_messages()` - Get all events/messages, returns list[SessionEvent]

- `await session.destroy()` - Clean up session

Event Handling

Event Subscription Pattern

ALWAYS use asyncio events or futures for waiting on session events:

import asyncio

done = asyncio.Event()

def handler(event):
    if event.type == "assistant.message":
        print(event.data.content)
    elif event.type == "session.idle":
        done.set()

session.on(handler)