[Bug]: Protobuf version mismatch error when running helloworld agent sample (gencode 6.31.1 vs runtime 5.29.4)

[vayvay0993]

What happened?

I git clone the https://github.com/google-a2a/a2a-python.git for git hash [d5e5f5f]

Follow the guide to run the remote agent

git clone https://github.com/google-a2a/a2a-samples.git
cd a2a-samples/samples/python/agents/helloworld
uv run .

And got:
google.protobuf.runtime_version.VersionError: Detected mismatched Protobuf Gencode/Runtime major versions when loading a2a.proto: gencode 6.31.1 runtime 5.29.4. Same major version is required. See Protobuf version guarantees at https://protobuf.dev/support/cross-version-runtime-guarantee.

Operating System: Windows 11
Python version: 3.13
uv version: uv 0.5.27 (73e9928d4 2025-02-03)

Relevant log output

Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "D:\Projects\a2a-samples\samples\python\agents\helloworld\__main__.py", line 3, in <module>
    from a2a.server.apps import A2AStarletteApplication
  File "D:\Projects\a2a-samples\samples\python\agents\helloworld\.venv\Lib\site-packages\a2a\server\apps\__init__.py", line 3, in <module>
    from a2a.server.apps.jsonrpc import (
    ...<4 lines>...
    )
  File "D:\Projects\a2a-samples\samples\python\agents\helloworld\.venv\Lib\site-packages\a2a\server\apps\jsonrpc\__init__.py", line 3, in <module>
    from a2a.server.apps.jsonrpc.fastapi_app import A2AFastAPIApplication
  File "D:\Projects\a2a-samples\samples\python\agents\helloworld\.venv\Lib\site-packages\a2a\server\apps\jsonrpc\fastapi_app.py", line 7, in <module>
    from a2a.server.apps.jsonrpc.jsonrpc_app import (
    ...<2 lines>...
    )
  File "D:\Projects\a2a-samples\samples\python\agents\helloworld\.venv\Lib\site-packages\a2a\server\apps\jsonrpc\jsonrpc_app.py", line 21, in <module>
    from a2a.server.request_handlers.jsonrpc_handler import JSONRPCHandler
  File "D:\Projects\a2a-samples\samples\python\agents\helloworld\.venv\Lib\site-packages\a2a\server\request_handlers\__init__.py", line 6, in <module>
    from a2a.server.request_handlers.grpc_handler import GrpcHandler
  File "D:\Projects\a2a-samples\samples\python\agents\helloworld\.venv\Lib\site-packages\a2a\server\request_handlers\grpc_handler.py", line 10, in <module>
    import a2a.grpc.a2a_pb2_grpc as a2a_grpc
  File "D:\Projects\a2a-samples\samples\python\agents\helloworld\.venv\Lib\site-packages\a2a\grpc\a2a_pb2_grpc.py", line 5, in <module>
    from . import a2a_pb2 as a2a__pb2
  File "D:\Projects\a2a-samples\samples\python\agents\helloworld\.venv\Lib\site-packages\a2a\grpc\a2a_pb2.py", line 12, in <module>
    _runtime_version.ValidateProtobufRuntimeVersion(
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
        _runtime_version.Domain.PUBLIC,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ...<4 lines>...
        'a2a.proto'
        ^^^^^^^^^^^
    )
    ^
  File "D:\Projects\a2a-samples\samples\python\agents\helloworld\.venv\Lib\site-packages\google\protobuf\runtime_version.py", line 106, in ValidateProtobufRuntimeVersion
    _ReportVersionError(
    ~~~~~~~~~~~~~~~~~~~^
        'Detected mismatched Protobuf Gencode/Runtime major versions when'
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        f' loading {location}: gencode {gen_version} runtime {version}.'
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        f' Same major version is required. {error_prompt}'
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "D:\Projects\a2a-samples\samples\python\agents\helloworld\.venv\Lib\site-packages\google\protobuf\runtime_version.py", line 50, in _ReportVersionError
    raise VersionError(msg)
google.protobuf.runtime_version.VersionError: Detected mismatched Protobuf Gencode/Runtime major versions when loading a2a.proto: gencode 6.31.1 runtime 5.29.4. Same major version is required. See Protobuf version guarantees at https://protobuf.dev/support/cross-version-runtime-guarantee.

Code of Conduct

• I agree to follow this project's Code of Conduct

[VeshRaazThapa]

It appears that the issue is specific to a2a-sdk version 0.2.6. As a temporary workaround, you can use version 0.2.5 by running the following command:

uv add "a2a-sdk==0.2.5"

[holtskinner]

This issue should have been resolved in release 0.2.7