GitHub Copilot SDK for Python

Warnings

• breaking Major API overhaul in v0.2.x. `CopilotClient` constructor arguments, `create_session`/`resume_session` parameters, and `send`/`send_and_wait` prompts have changed. Configuration objects are now dataclasses/keyword arguments instead of loosely-typed TypedDicts. The `copilot.types` module was removed.
  Fix: Update `CopilotClient` instantiation (e.g., use `SubprocessConfig()` or `ExternalServerConfig()`). Pass keyword arguments directly to `create_session` and `resume_session`. Pass plain string prompts to `send` and `send_and_wait`. Update imports and references from `copilot.types` to direct imports or new dataclass structures.
• deprecated The `autoRestart` option for `CopilotClient` has been removed. It was never fully implemented and now has no effect.
  Fix: Remove any references to `autoRestart` from your `CopilotClient` options.
• gotcha Ephemeral events (e.g., `session.idle`, delta events) are no longer included in the `session.get_messages()` history after runtime update 1.0.12. They are only observable via live event listeners.
  Fix: If your code relies on ephemeral events, subscribe to them using `session.on('event.type', handler)` instead of relying on `get_messages()` for their historical retrieval.
• gotcha A GitHub Copilot subscription is generally required for the SDK to function, unless you configure a Bring Your Own Key (BYOK) setup with a custom LLM provider.
  Fix: Ensure the user account has an active GitHub Copilot subscription, or configure the SDK with a custom provider and API key if using BYOK.
• gotcha Copilot's AI-generated code, including outputs from the SDK, can contain errors, logical flaws, or security vulnerabilities.
  Fix: Always review, test, and validate AI-generated content and code. Do not accept suggestions blindly, and apply secure coding practices. The SDK provides mechanisms like `on_permission_request` to gate sensitive operations.
• gotcha The SDK explicitly requires Python 3.11 or newer. Older Python versions are not supported and will lead to compatibility issues or errors.
  Fix: Ensure your Python environment is running version 3.11 or later. Upgrade Python if necessary.

Install

• pip install github-copilot-sdk Install SDK

Imports

• CopilotClient

  from copilot import CopilotClient

• SubprocessConfig

  from copilot import SubprocessConfig

• ExternalServerConfig

  from copilot import ExternalServerConfig

• PermissionHandler

  from copilot.session import PermissionHandler

• copilot.types
  The `copilot.types` module was removed in SDK version 0.2.x. Types are now imported directly from the `copilot` package or are represented by dataclasses and keyword arguments.

Quickstart

This quickstart demonstrates how to initialize the `CopilotClient`, create a session, send a message, and receive a response. It utilizes Python's `asyncio` for asynchronous operations and `async with` for proper resource management. The `on_permission_request` handler is essential for tool execution within a session. Replace 'gpt-4o' with an appropriate model.

import asyncio
import os
from copilot import CopilotClient, SubprocessConfig
from copilot.session import PermissionHandler

async def main():
    # Ensure COPILOT_CLI_PATH or 'copilot' in PATH for the CLI to be found
    # The CLI is often bundled, but its presence is crucial.
    
    # For programmatic authentication with BYOK, you might set API keys
    # os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', '')

    try:
        # Using async with for automatic client lifecycle management
        # Use SubprocessConfig for default behavior (SDK managing CLI process)
        # Or ExternalServerConfig if connecting to an already running CLI server
        async with CopilotClient(SubprocessConfig()) as client:
            print("Copilot client started.")

            # Create a session. on_permission_request is required.
            # 'model' is required when using a custom provider.
            async with await client.create_session(
                model="gpt-4o", # Example model, check available models with client.list_models()
                on_permission_request=PermissionHandler.approve_all,
            ) as session:
                print(f"Session created: {session.session_id}")

                print("Sending message...")
                # send_and_wait now takes a plain string prompt (v0.2.x+)
                response = await session.send_and_wait("What is 2+2?")

                if response and response.data and response.data.content:
                    print(f"Response: {response.data.content}")
                else:
                    print("No content in response.")

            print("Session disconnected.")

    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == "__main__":
    asyncio.run(main())