Refactor to also make starlette optional

Author: holtskinner

README.md

@@ -26,40 +26,28 @@ You can install the A2A SDK using either `uv` or `pip`.
 
 ### Using `uv`
 
-When you're working within a uv project or a virtual environment managed by uv, the preferred way to add packages is using uv add.
-
 ```bash
 uv add a2a-sdk
 ```
 
-### Using `pip`
-
-If you prefer to use pip, the standard Python package installer, you can install `a2a-sdk` as follows
+To include the optional HTTP server components (FastAPI, Starlette), install the `http-server` extra:
 
 ```bash
-pip install a2a-sdk
+uv add a2a-sdk[http-server]
 ```
 
-### Optional Dependencies
-
-#### FastAPI-based A2A Server App
-
-If you plan to build a server application using the `A2AFastAPIApplication` helper, you will need to install the `fastapi` package. This is an optional dependency.
-
-You can install it with the `fastapi` extra:
+### Using `pip`
 
-```shell
-# Using uv
-uv add a2a-sdk[fastapi]
+You can install `a2a-sdk` using pip, the standard Python package installer.
 
-# Using pip
-pip install "a2a-sdk[fastapi]"
+```bash
+pip install a2a-sdk
 ```
 
-Alternatively, if you manage your dependencies separately, you can add `fastapi` to your project directly:
+To include the optional HTTP server components (FastAPI, Starlette), install the `http-server` extra:
 
-```shell
-uv add fastapi
+```bash
+pip install a2a-sdk[http-server]
 ```
 
 ## Examples

pyproject.toml

@@ -8,18 +8,16 @@ authors = [{ name = "Google LLC", email = "googleapis-packages@google.com" }]
 requires-python = ">=3.10"
 keywords = ["A2A", "A2A SDK", "A2A Protocol", "Agent2Agent"]
 dependencies = [
-    "httpx>=0.28.1",
-    "httpx-sse>=0.4.0",
-    "google-api-core>=1.26.0",
-    "opentelemetry-api>=1.33.0",
-    "opentelemetry-sdk>=1.33.0",
-    "pydantic>=2.11.3",
-    "sse-starlette",
-    "starlette",
-    "grpcio>=1.60",
-    "grpcio-tools>=1.60",
-    "grpcio_reflection>=1.7.0",
-    "protobuf==6.31.1",
+  "httpx>=0.28.1",
+  "httpx-sse>=0.4.0",
+  "google-api-core>=1.26.0",
+  "opentelemetry-api>=1.33.0",
+  "opentelemetry-sdk>=1.33.0",
+  "pydantic>=2.11.3",
+  "grpcio>=1.60",
+  "grpcio-tools>=1.60",
+  "grpcio_reflection>=1.7.0",
+  "protobuf==5.29.5",
 ]
 
 classifiers = [
@@ -35,6 +33,13 @@ classifiers = [
   "License :: OSI Approved :: Apache Software License",
 ]
 
+[project.optional-dependencies]
+http-server = [
+  "fastapi>=0.115.2",
+  "sse-starlette",
+  "starlette",
+]
+
 [project.urls]
 homepage = "https://google-a2a.github.io/A2A/"
 repository = "https://github.com/google-a2a/a2a-python"
@@ -69,21 +74,20 @@ style = "pep440"
 
 [dependency-groups]
 dev = [
-    "datamodel-code-generator>=0.30.0",
-    "mypy>=1.15.0",
-    "pytest>=8.3.5",
-    "pytest-asyncio>=0.26.0",
-    "pytest-cov>=6.1.1",
-    "pytest-mock>=3.14.0",
-    "respx>=0.20.2",
-    "ruff>=0.11.6",
-    "uv-dynamic-versioning>=0.8.2",
-    "types-protobuf",
-    "types-requests",
-    "fastapi>=0.115.2",
-]
-fastapi = [
-    "fastapi>=0.115.2",
+  "datamodel-code-generator>=0.30.0",
+  "mypy>=1.15.0",
+  "pytest>=8.3.5",
+  "pytest-asyncio>=0.26.0",
+  "pytest-cov>=6.1.1",
+  "pytest-mock>=3.14.0",
+  "respx>=0.20.2",
+  "ruff>=0.11.6",
+  "uv-dynamic-versioning>=0.8.2",
+  "types-protobuf",
+  "types-requests",
+  "fastapi>=0.115.2",
+  "sse-starlette",
+  "starlette",
 ]
 
 [[tool.uv.index]]

src/a2a/server/apps/jsonrpc/fastapi_app.py

@@ -2,11 +2,14 @@
 
 from typing import Any
 
-from a2a.server.apps.jsonrpc.fastapi_import_helpers import (
-    FastAPI,
-    Request,
-    Response,
-)
+
+try:
+    from fastapi import FastAPI, Request, Response
+except ImportError:
+    FastAPI = object
+    Request = object
+    Response = object
+
 from a2a.server.apps.jsonrpc.jsonrpc_app import (
     CallContextBuilder,
     JSONRPCApplication,

src/a2a/server/apps/jsonrpc/fastapi_import_helpers.py

@@ -42,9 +42,23 @@
 )
 from a2a.utils.errors import MethodNotImplementedError
 
-
 logger = logging.getLogger(__name__)
 
+try:
+    from fastapi import FastAPI
+    from sse_starlette.sse import EventSourceResponse
+    from starlette.applications import Starlette
+    from starlette.authentication import BaseUser
+    from starlette.requests import Request
+    from starlette.responses import JSONResponse, Response
+
+    _http_server_installed = True
+except ImportError:
+    _http_server_installed = False
+    # Define placeholder types for type hinting and to avoid import errors in other files.
+    # These will not be used at runtime if deps are missing, as __init__ will raise.
+    FastAPI, EventSourceResponse, Starlette, BaseUser, Request, JSONResponse, Response = (object,) * 7
+
 
 class StarletteUserProxy(A2AUser):
     """Adapts the Starlette User class to the A2A user representation."""
@@ -108,7 +122,7 @@ def __init__(
         extended_agent_card: AgentCard | None = None,
         context_builder: CallContextBuilder | None = None,
     ):
-        """Initializes the A2AStarletteApplication.
+        """Initializes the JSONRPCApplication.
 
         Args:
             agent_card: The AgentCard describing the agent's capabilities.
@@ -120,6 +134,10 @@ def __init__(
               ServerCallContext passed to the http_handler. If None, no
               ServerCallContext is passed.
         """
+        if not _http_server_installed:
+            raise ImportError(
+                'The `a2a-sdk[http-server]` package is required to use the `JSONRPCApplication`.'
+            )
         self.agent_card = agent_card
         self.extended_agent_card = extended_agent_card
         self.handler = JSONRPCHandler(
@@ -163,7 +181,7 @@ def _generate_error_response(
             log_level,
             f'Request Error (ID: {request_id}): '
             f"Code={error_resp.error.code}, Message='{error_resp.error.message}'"
-            f'{", Data=" + str(error_resp.error.data) if error_resp.error.data else ""}',
+            f'{", Data="  str(error_resp.error.data) if error_resp.error.data else ""}',
         )
         return JSONResponse(
             error_resp.model_dump(mode='json', exclude_none=True),
@@ -411,7 +429,7 @@ def build(
         agent_card_url: str = '/.well-known/agent.json',
         rpc_url: str = '/',
         **kwargs: Any,
-    ) -> FastAPI | Starlette:
+    ) -> 'FastAPI' | Starlette':
         """Builds and returns the JSONRPC application instance.
 
         Args:

src/a2a/server/apps/jsonrpc/jsonrpc_app.py

@@ -2,8 +2,13 @@
 
 from typing import Any
 
-from starlette.applications import Starlette
-from starlette.routing import Route
+
+try:
+    from starlette.applications import Starlette
+    from starlette.routing import Route
+except ImportError:
+    Starlette = object
+    Route = object
 
 from a2a.server.apps.jsonrpc.jsonrpc_app import (
     CallContextBuilder,