Skip to content

Copilot SDK Python quickstart: clarify package compatibility and update API examples #47003

Backlog

Description

@jenkauppila

Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/copilot/get-started/sdk-quickstart

What part(s) of the article would you like to see updated?

The Python examples in Steps 1 through 5 would benefit from clearer SDK version compatibility guidance and updated API examples.

While following the quickstart, I encountered the following error with the originally documented SDK package:

SDK protocol version mismatch: SDK supports versions 3-3, but server reports version 4

The quickstart uses github-copilot-sdk and API patterns that differ from the working implementation I completed using microsoft-copilot-sdk==2.0.1.

After investigating the incompatibility, I successfully completed all five stages by updating the dependency and adapting the Python examples.

Proposed documentation improvements:

  1. Clarify which Python SDK package and version the quickstart currently supports
  2. Explain the relationship between github-copilot-sdk and microsoft-copilot-sdk
  3. Update the Python examples or provide version-specific alternatives for the supported SDK
  4. Document the session configuration differences, including permissions, streaming events, and custom-tool registration
  5. Add troubleshooting guidance for SDK/runtime protocol version mismatches

Expected outcome: A developer following the Python quickstart should be able to install the recommended SDK, run the examples, and complete all five steps without encountering undocumented compatibility issues.

Additional information

Reproduction and working implementation

I encountered the protocol mismatch while following the Python quickstart in my local development environment.

I resolved it by migrating to microsoft-copilot-sdk==2.0.1 and adapting the examples to the APIs supported by that version.

The working implementation uses:

  • CopilotClient(mode="coding-agent")
  • permissions={"on_request": PermissionHandler.approve_all}
  • events={"streaming": True}
  • tools={"definitions": [get_weather]}
  • Asynchronous context managers for client and session cleanup

Both the single-prompt custom-tool example and the interactive weather assistant were tested successfully.

Working repository:
https://github.com/jenkauppila/copilot_sdk_learning_lab

The repository includes the completed examples, pinned dependencies, setup instructions and an SDK compatibility reference.

Proposed contribution

I'd be happy to prepare a pull request updating the Python quickstart and adding compatibility guidance.

Before making those changes, I'd appreciate confirmation of which Python SDK package and version the documentation should target, so the proposed fix aligns with the maintainers' intended direction.

Activity

  1. added
    contentThis issue or pull request belongs to the Docs Content team
    on Nov 19, 2026
  2. added
    triageDo not begin working on this issue until triaged by the team
    on Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    contentThis issue or pull request belongs to the Docs Content teamtriageDo not begin working on this issue until triaged by the team

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions