Python SDK Cookbook

Short, practical recipes for using the GitHub Copilot SDK with Python. Each recipe is concise, copy-pasteable, and points to complete runnable examples.

Setup

Install the GitHub Copilot SDK:

pip install copilot-sdk

Import in your code:

import asyncio
from copilot import CopilotClient, SessionConfig, MessageOptions

Error Handling

Handle errors gracefully including connection failures, timeouts, and cleanup.

Basic try-except Pattern

import asyncio
from copilot import CopilotClient, SessionConfig, MessageOptions

async def main():
    client = CopilotClient()

    try:
        await client.start()
        session = await client.create_session(SessionConfig(model="gpt-5"))

        response = await session.send_and_wait(MessageOptions(prompt="Hello!"))

        if response:
            print(response.data.content)

        await session.destroy()
    except Exception as e:
        print(f"Error: {e}")
    finally:
        await client.stop()

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

Timeout Handling

session = await client.create_session(SessionConfig(model="gpt-5"))

try:
    # send_and_wait accepts an optional timeout in seconds
    response = await session.send_and_wait(
        MessageOptions(prompt="Complex question..."),
        timeout=30.0
    )
    print("Response received")
except TimeoutError:
    print("Request timed out")

Aborting Requests

session = await client.create_session(SessionConfig(model="gpt-5"))

# Start a request (non-blocking send)
await session.send(MessageOptions(prompt="Write a very long story..."))

# Abort it after some condition
await asyncio.sleep(5)
await session.abort()
print("Request aborted")

Graceful Shutdown

import signal
import sys

def signal_handler(sig, frame):
    print("\nShutting down...")
    try:
        loop = asyncio.get_running_loop()
        loop.create_task(client.stop())
    except RuntimeError:
        asyncio.run(client.stop())
    sys.exit(0)

signal.signal(signal.SIGINT, signal_handler)

Always use try-finally to ensure await client.stop() is called. This prevents the Copilot CLI process from becoming orphaned.

Multiple Sessions

Manage multiple independent conversations simultaneously.

import asyncio
from copilot import CopilotClient, SessionConfig, MessageOptions

async def main():
    client = CopilotClient()
    await client.start()

    # Create multiple independent sessions
    session1 = await client.create_session(SessionConfig(model="gpt-5"))
    session2 = await client.create_session(SessionConfig(model="gpt-5"))
    session3 = await client.create_session(SessionConfig(model="claude-sonnet-4.5"))

    print("Created 3 independent sessions")

    # Each session maintains its own conversation history
    await session1.send(MessageOptions(prompt="You are helping with a Python project"))
    await session2.send(MessageOptions(prompt="You are helping with a TypeScript project"))
    await session3.send(MessageOptions(prompt="You are helping with a Go project"))

    print("Sent initial context to all sessions")

    # Follow-up messages stay in their respective contexts
    await session1.send(MessageOptions(prompt="How do I create a virtual environment?"))
    await session2.send(MessageOptions(prompt="How do I set up tsconfig?"))
    await session3.send(MessageOptions(prompt="How do I initialize a module?"))

    print("Sent follow-up questions to each session")

    # Clean up all sessions
    await session1.destroy()
    await session2.destroy()
    await session3.destroy()
    await client.stop()

    print("All sessions destroyed successfully")

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

Custom Session IDs

session = await client.create_session(SessionConfig(
    session_id="user-123-chat",
    model="gpt-5"
))

print(f"Session ID: {session.session_id}")

Use Cases

Multi-User Apps

One session per user in web applications

Parallel Tasks

Run multiple AI tasks concurrently with asyncio

Model Comparison

Compare responses from different models

Session Persistence

Save and resume sessions across application restarts.

import asyncio
import json
from copilot import CopilotClient, SessionConfig, MessageOptions

async def save_session():
    client = CopilotClient()
    await client.start()

    session = await client.create_session(SessionConfig(model="gpt-5"))
    await session.send_and_wait(MessageOptions(prompt="Remember: my name is Alice"))

    # Save session state
    session_state = session.get_state()
    with open("session.json", "w") as f:
        json.dump(session_state, f, indent=2)

    await session.destroy()
    await client.stop()
    print("Session saved")

async def restore_session():
    # Later: restore session state
    client = CopilotClient()
    await client.start()

    with open("session.json", "r") as f:
        state = json.load(f)

    restored_session = await client.create_session(SessionConfig(
        model="gpt-5",
        state=state
    ))

    # Session remembers previous context
    response = await restored_session.send_and_wait(
        MessageOptions(prompt="What's my name?")
    )
    print(response.data.content)  # "Your name is Alice"

    await restored_session.destroy()
    await client.stop()

if __name__ == "__main__":
    # First run: save session
    asyncio.run(save_session())
    
    # Later run: restore session
    asyncio.run(restore_session())

Session persistence allows you to maintain conversation context across restarts, perfect for long-running workflows or user session management.

Managing Local Files

Use AI to organize and categorize files.

import asyncio
from copilot import CopilotClient, SessionConfig, MessageOptions

async def organize_files():
    client = CopilotClient()
    await client.start()

    session = await client.create_session(SessionConfig(model="gpt-5"))

    response = await session.send_and_wait(MessageOptions(prompt="""
        I have these files in a directory:
        - report.pdf
        - meeting-notes.txt
        - photo.jpg
        - invoice.xlsx
        - presentation.pptx
        
        Please organize them into folders by type.
        Return JSON with the folder structure.
    """))

    print(response.data.content)

    # Parse the AI response and execute file operations
    # import json
    # organization = json.loads(response.data.content)
    # ...

    await session.destroy()
    await client.stop()

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

Working with asyncio

The Python SDK is fully async. Here are some useful patterns:

Running Multiple Sessions Concurrently

import asyncio
from copilot import CopilotClient, SessionConfig, MessageOptions

async def process_with_session(client, prompt, model="gpt-5"):
    session = await client.create_session(SessionConfig(model=model))
    response = await session.send_and_wait(MessageOptions(prompt=prompt))
    await session.destroy()
    return response.data.content

async def main():
    client = CopilotClient()
    await client.start()

    # Run multiple prompts concurrently
    results = await asyncio.gather(
        process_with_session(client, "Explain Python async/await"),
        process_with_session(client, "What are Python decorators?"),
        process_with_session(client, "How does the GIL work?"),
    )

    for i, result in enumerate(results, 1):
        print(f"\nResult {i}:")
        print(result)

    await client.stop()

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

Using Context Managers (Python 3.7+)

from contextlib import asynccontextmanager

@asynccontextmanager
async def copilot_session(model="gpt-5"):
    client = CopilotClient()
    await client.start()
    session = await client.create_session(SessionConfig(model=model))
    try:
        yield session
    finally:
        await session.destroy()
        await client.stop()

async def main():
    async with copilot_session() as session:
        response = await session.send_and_wait(
            MessageOptions(prompt="Hello!")
        )
        print(response.data.content)

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

Running Examples

All complete, runnable examples are available in the cookbook/copilot-sdk/python/recipe directory.

Navigate to the recipe directory

cd cookbook/copilot-sdk/python/recipe

Install dependencies

pip install -r requirements.txt

Run any example

python error_handling.py
python multiple_sessions.py
python persisting_sessions.py

Best Practices

Always Clean Up Resources

Use try-finally to ensure await client.stop() is called.

try:
    await client.start()
    # ... work ...
finally:
    await client.stop()

Handle Connection Errors

Check for FileNotFoundError and ConnectionError when starting the client.

except FileNotFoundError:
    print("Please install GitHub Copilot CLI")

Use Timeouts

Always provide a timeout parameter to send_and_wait() for long requests.

response = await session.send_and_wait(options, timeout=30.0)

Leverage asyncio for Concurrency

Use asyncio.gather() to run multiple sessions or requests concurrently.

results = await asyncio.gather(
    session1.send_and_wait(prompt1),
    session2.send_and_wait(prompt2),
)

Additional Recipes

Explore more advanced recipes in the source repository:

Ralph Loop - Autonomous AI coding loops
PR Visualization - Generate interactive PR charts
Accessibility Report - WCAG accessibility reports
Managing Local Files - AI-powered file organization

Getting Started

SDK Examples

Practical Examples

Python SDK Cookbook

Python SDK Cookbook

Setup

Error Handling

Basic try-except Pattern

Timeout Handling

Aborting Requests

Graceful Shutdown

Multiple Sessions

Custom Session IDs

Use Cases

Multi-User Apps

Parallel Tasks

Model Comparison

Session Persistence

Managing Local Files

Working with asyncio

Running Multiple Sessions Concurrently

Using Context Managers (Python 3.7+)

Running Examples

Best Practices

Additional Recipes

Resources

Build docs developers (and LLMs) love

Getting Started

SDK Examples

Practical Examples

​Python SDK Cookbook

​Setup

​Error Handling

​Basic try-except Pattern

​Timeout Handling

​Aborting Requests

​Graceful Shutdown

​Multiple Sessions

​Custom Session IDs

​Use Cases

Multi-User Apps

Parallel Tasks

Model Comparison

​Session Persistence

​Managing Local Files

​Working with asyncio

​Running Multiple Sessions Concurrently

​Using Context Managers (Python 3.7+)

​Running Examples

​Best Practices

​Additional Recipes

​Resources

Build docs developers (and LLMs) love

Python SDK Cookbook

Setup

Error Handling

Basic try-except Pattern

Timeout Handling

Aborting Requests

Graceful Shutdown

Multiple Sessions

Custom Session IDs

Use Cases

Session Persistence

Managing Local Files

Working with asyncio

Running Multiple Sessions Concurrently

Using Context Managers (Python 3.7+)

Running Examples

Best Practices

Additional Recipes

Resources