feat!: Add FastAPI JSONRPC Application

[martimfasantos]

Description

Summary

This PR introduces a A2AFastAPIApplication class that enables serving A2A endpoints using a FastAPI application, while preserving compatibility with the existing JSONRPC Starlette-based architecture.

Motivation

While the SDK currently provides a Starlette-based server app for A2A agent communication using JSONRPC, many production Python APIs are built with FastAPI due to its support for performance, extensibility, automatic OpenAPI schema generation, and strong async capabilities. Providing native FastAPI support enables seamless integration into such environments without requiring users to manually wrap the existing Starlette app.

This addition does not introduce any breaking changes. FastAPI is treated as an optional integration, and the core A2A logic continues to rely on shared base classes and request handlers.

Implementation Details

• Introduced JSONRPCApplication, an abstract base class that encapsulates the shared request-handling logic for both Starlette and FastAPI JSONRPC applications. This isolates the common behavior, with the only required customization being the build(...) method used to register routes and return the appropriate application instance.

• Added A2AFastAPIApplication, a concrete implementation of JSONRPCApplication that constructs a FastAPI app with the appropriate routes:

  • POST / (or custom RPC endpoint) for handling A2A JSON-RPC messages.
  • GET /.well-known/agent.json (or custom) for serving the agent card.

• All request processing is shared via _handle_requests and _handle_get_agent_card.

• SSE streaming support is preserved for SendStreamingMessageRequest and TaskResubscriptionRequest.

• Added fastapi to the dependencies in pyproject.toml.

Usage Example

from a2a.server.apps.jsonrpc import A2AFastAPIApplication

app = A2AFastAPIApplication(agent_card=my_agent_card, http_handler=my_handler).build()

Hello World Example (examples/helloword/)

1. Change A2AStarletteApplication to A2AFastAPIApplication

2. Start the server

   uv run .

3. Run the test client

 uv run test_client.py

---

• Follow the CONTRIBUTING Guide.
• Make your Pull Request title in the https://www.conventionalcommits.org/ specification.
• Ensure the tests and linter pass (Run nox -s format from the repository root to format)
• Appropriate docs were updated (if necessary)

Continues #26
Fixes #21 🦕

[holtskinner]

There's now a backwards-incompatible change:

==================================== ERRORS ====================================
______________ ERROR collecting tests/server/test_integration.py _______________
ImportError while importing test module '/home/runner/work/a2a-python/a2a-python/tests/server/test_integration.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
/opt/hostedtoolcache/Python/3.10.17/x64/lib/python3.10/importlib/__init__.py:1[26](https://github.com/google-a2a/a2a-python/actions/runs/15398882285/job/43326395575#step:7:27): in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
tests/server/test_integration.py:10: in <module>
    from a2a.server.apps.starlette_app import A2AStarletteApplication
src/a2a/server/apps/__init__.py:3: in <module>
    from a2a.server.apps.starlette_app import A2AStarletteApplication
E   ModuleNotFoundError: No module named 'a2a.server.apps.starlette_app'
================================ tests coverage ================================

Can you update the tests to fix this import error and any further usage of a2a.server.apps.starlette_app in the docs/other examples?

[martimfasantos]

There's now a backwards-incompatible change:

==================================== ERRORS ====================================
______________ ERROR collecting tests/server/test_integration.py _______________
ImportError while importing test module '/home/runner/work/a2a-python/a2a-python/tests/server/test_integration.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
/opt/hostedtoolcache/Python/3.10.17/x64/lib/python3.10/importlib/__init__.py:1[26](https://github.com/google-a2a/a2a-python/actions/runs/15398882285/job/43326395575#step:7:27): in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
tests/server/test_integration.py:10: in <module>
    from a2a.server.apps.starlette_app import A2AStarletteApplication
src/a2a/server/apps/__init__.py:3: in <module>
    from a2a.server.apps.starlette_app import A2AStarletteApplication
E   ModuleNotFoundError: No module named 'a2a.server.apps.starlette_app'
================================ tests coverage ================================

Can you update the tests to fix this import error and any further usage of a2a.server.apps.starlette_app in the docs/other examples?

Fixed in 54747f8:

• Updated Starlette test imports
• Added FastAPI tests

Will update docs/examples after merge, if needed :)

[holtskinner]

Seems like the tests are still failing

[martimfasantos]

Seems like the tests are still failing

@holtskinner Oh right, my bad! The updates for the extended agent card didn't get merged correctly.
Fixed that and the tests too - should be all good now! 🚀