Fix Python cookbook recipes to use correct async SDK API

[tonybaloney]

Problem

All 5 Python cookbook recipes and their corresponding markdown documentation use a synchronous, kwargs-based API that doesn't match the real github-copilot-sdk package.

Issues found

• Sync calls instead of async (e.g. client.start() should be await client.start())
• Session creation uses kwargs instead of SessionConfig TypedDict
• Message sending uses kwargs instead of MessageOptions TypedDict
• session.wait_for_idle() doesn't exist - should use send_and_wait()
• Events accessed as dicts instead of objects (event.type, event.data.content)
• Missing async def main() + asyncio.run(main()) wrapper

Files changed (10)

Recipes: error_handling.py, persisting_sessions.py, multiple_sessions.py, managing_local_files.py, pr_visualization.py

Documentation: error-handling.md, persisting-sessions.md, multiple-sessions.md, managing-local-files.md, pr-visualization.md

Verification

All imports verified against installed github-copilot-sdk package.

[Copilot]

Pull request overview

Updates the Python Copilot SDK cookbook recipes and docs to match the async, TypedDict-based API shape used by github-copilot-sdk, replacing outdated synchronous/kwargs-style examples.

Changes:

• Convert all 5 runnable Python recipes to async usage (await client.start(), await session.send_and_wait(...), typed events).
• Update corresponding markdown docs to reflect the async API and object-based event access.
• Replace deprecated/incorrect session APIs (e.g., wait_for_idle() → send_and_wait()).

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
cookbook/copilot-sdk/python/recipe/error_handling.py	Converts the runnable error-handling recipe to async client/session APIs.
cookbook/copilot-sdk/python/recipe/persisting_sessions.py	Updates persistence/resumption recipe to async session management and typed options.
cookbook/copilot-sdk/python/recipe/multiple_sessions.py	Updates multi-session recipe to async session creation and messaging.
cookbook/copilot-sdk/python/recipe/managing_local_files.py	Updates local-files recipe to async workflow and typed event handling.
cookbook/copilot-sdk/python/recipe/pr_visualization.py	Updates PR visualization CLI to async session lifecycle, events, and messaging.
cookbook/copilot-sdk/python/error-handling.md	Updates documentation snippets to async API patterns (needs some fixes for runnable correctness).
cookbook/copilot-sdk/python/persisting-sessions.md	Updates docs for persistence/resume/list/delete/history to async API (some snippets now use top-level await).
cookbook/copilot-sdk/python/multiple-sessions.md	Updates docs to async multi-session patterns (some snippets now use top-level await).
cookbook/copilot-sdk/python/managing-local-files.md	Updates docs to async patterns and typed events (some follow-up snippets now use top-level await).
cookbook/copilot-sdk/python/pr-visualization.md	Updates documentation version of the PR visualization script to async API usage.

Comments suppressed due to low confidence (8)

cookbook/copilot-sdk/python/managing-local-files.md:112

• Same issue here: this snippet uses await session.send_and_wait(...) without showing the required async wrapper and session/target_folder initialization. Make the snippet runnable standalone or clearly mark it as a continuation of the full example above.

await session.send_and_wait(MessageOptions(prompt=f"""
Look at the files in "{target_folder}" and suggest a logical organization.
Consider:

cookbook/copilot-sdk/python/error-handling.md:47

• The snippet uses await client.start() directly inside a try block, but await only works inside an async def and this block doesn’t define client. Make this example self-contained by showing async def main() (including client = CopilotClient()) and running it via asyncio.run(main()), or explicitly note it must be placed inside the earlier main().

try:
    await client.start()

cookbook/copilot-sdk/python/error-handling.md:82

• This block uses top-level await for create_session, send, sleep, and abort. As written it’s not valid Python outside an async def. Consider wrapping the whole example in async def main() + asyncio.run(main()) to keep it runnable.

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()

cookbook/copilot-sdk/python/persisting-sessions.md:64

• The “Listing available sessions” block uses await client.list_sessions() at top level and assumes client exists. Wrap in an async function (or include the missing setup) so the example can be copied and run.

sessions = await client.list_sessions()
for s in sessions:

cookbook/copilot-sdk/python/persisting-sessions.md:72

• This “Deleting a session” example uses await client.delete_session(...) at top level without showing the async wrapper / client setup. Make it a complete runnable snippet (or note required surrounding context).

await client.delete_session("user-123-conversation")

cookbook/copilot-sdk/python/persisting-sessions.md:80

• The “Getting session history” snippet uses await session.get_messages() but doesn’t show where session comes from (and uses top-level await). Consider folding this into the resumption example or adding a minimal async def main() that initializes client/session.

messages = await session.get_messages()
for msg in messages:
    print(f"[{msg.type}] {msg.data.content}")

cookbook/copilot-sdk/python/multiple-sessions.md:58

• This “Custom session IDs” snippet uses await at top level and assumes an initialized client. Wrap it in an async function (and include await client.start()), or label it as a continuation from the earlier full example.

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

cookbook/copilot-sdk/python/multiple-sessions.md:75

• This “Deleting sessions” snippet uses await client.delete_session(...) at top level and doesn’t show the surrounding async/client setup. Wrap it in async def main() + asyncio.run(main()) or clarify the required context.

await client.delete_session("user-123-chat")