custom_github_copilot_agent_builder: Instructions file for GitHub Copilot

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 copilot-sdk
# or with poetry
poetry add copilot-sdk
# or with uv
uv add copilot-sdk

Client Initialization

Basic Client Setup

from copilot import CopilotClient

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

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:

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

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

Session Management

Creating Sessions

Use a dict for SessionConfig:

session = await client.create_session({
    "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)