{"id":5941,"library":"github-copilot-sdk","title":"GitHub Copilot SDK for Python","description":"The GitHub Copilot SDK for Python provides programmatic access to GitHub Copilot's agentic engine via JSON-RPC, allowing developers to embed AI capabilities directly into their applications and workflows. It manages the connection to the Copilot CLI, handles session context, tool invocation, and streaming events. The SDK is currently in public preview, requires Python 3.11+, and is actively developed with frequent updates.","status":"active","version":"0.2.2","language":"en","source_language":"en","source_url":"https://github.com/github/copilot-sdk","tags":["ai","copilot","github","agent","sdk","llm","cli","async","preview"],"install":[{"cmd":"pip install github-copilot-sdk","lang":"bash","label":"Install SDK"}],"dependencies":[{"reason":"Requires Python 3.11 or later.","package":"Python","optional":false},{"reason":"The SDK communicates with the Copilot CLI in server mode. For Python, the CLI is bundled automatically, but its functionality (e.g., authentication) is prerequisite.","package":"GitHub Copilot CLI","optional":false},{"reason":"A GitHub Copilot subscription is generally required to use the SDK, unless utilizing the Bring Your Own Key (BYOK) feature with custom API providers.","package":"GitHub Copilot Subscription","optional":true}],"imports":[{"symbol":"CopilotClient","correct":"from copilot import CopilotClient"},{"symbol":"SubprocessConfig","correct":"from copilot import SubprocessConfig"},{"symbol":"ExternalServerConfig","correct":"from copilot import ExternalServerConfig"},{"symbol":"PermissionHandler","correct":"from copilot.session import PermissionHandler"},{"note":"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.","wrong":"from copilot.types import ...","symbol":"copilot.types"}],"quickstart":{"code":"import asyncio\nimport os\nfrom copilot import CopilotClient, SubprocessConfig\nfrom copilot.session import PermissionHandler\n\nasync def main():\n    # Ensure COPILOT_CLI_PATH or 'copilot' in PATH for the CLI to be found\n    # The CLI is often bundled, but its presence is crucial.\n    \n    # For programmatic authentication with BYOK, you might set API keys\n    # os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', '')\n\n    try:\n        # Using async with for automatic client lifecycle management\n        # Use SubprocessConfig for default behavior (SDK managing CLI process)\n        # Or ExternalServerConfig if connecting to an already running CLI server\n        async with CopilotClient(SubprocessConfig()) as client:\n            print(\"Copilot client started.\")\n\n            # Create a session. on_permission_request is required.\n            # 'model' is required when using a custom provider.\n            async with await client.create_session(\n                model=\"gpt-4o\", # Example model, check available models with client.list_models()\n                on_permission_request=PermissionHandler.approve_all,\n            ) as session:\n                print(f\"Session created: {session.session_id}\")\n\n                print(\"Sending message...\")\n                # send_and_wait now takes a plain string prompt (v0.2.x+)\n                response = await session.send_and_wait(\"What is 2+2?\")\n\n                if response and response.data and response.data.content:\n                    print(f\"Response: {response.data.content}\")\n                else:\n                    print(\"No content in response.\")\n\n            print(\"Session disconnected.\")\n\n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Remove any references to `autoRestart` from your `CopilotClient` options.","message":"The `autoRestart` option for `CopilotClient` has been removed. It was never fully implemented and now has no effect.","severity":"deprecated","affected_versions":">=0.2.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.2.1-preview.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Copilot's AI-generated code, including outputs from the SDK, can contain errors, logical flaws, or security vulnerabilities.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Python environment is running version 3.11 or later. Upgrade Python if necessary.","message":"The SDK explicitly requires Python 3.11 or newer. Older Python versions are not supported and will lead to compatibility issues or errors.","severity":"gotcha","affected_versions":"<0.1.32 (some versions required >=3.10, but >=3.11 is now standard)"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}