refactor!: Make the FastAPI and Starlette dependencies optional

.github/actions/spelling/allow.txt

@@ -67,6 +67,7 @@ pyi
 pypistats
 pyupgrade
 pyversions
+redef
 respx
 resub
 RUF

README.md

@@ -33,6 +33,12 @@ When you're working within a uv project or a virtual environment managed by uv,
 uv add a2a-sdk
 ```
 
+To include the optional HTTP server components (FastAPI, Starlette), install the `http-server` extra:
+
+```bash
+uv add a2a-sdk[http-server]
+```
+
 To install with gRPC support:
 
 ```bash
@@ -63,6 +69,12 @@ If you prefer to use pip, the standard Python package installer, you can install
 pip install a2a-sdk
 ```
 
+To include the optional HTTP server components (FastAPI, Starlette), install the `http-server` extra:
+
+```bash
+pip install a2a-sdk[http-server]
+```
+
 To install with gRPC support:
 
 ```bash

pyproject.toml

@@ -8,14 +8,11 @@ authors = [{ name = "Google LLC", email = "[email protected]" }]
 requires-python = ">=3.10"
 keywords = ["A2A", "A2A SDK", "A2A Protocol", "Agent2Agent", "Agent 2 Agent"]
 dependencies = [
-  "fastapi>=0.115.2",
   "httpx>=0.28.1",
   "httpx-sse>=0.4.0",
   "opentelemetry-api>=1.33.0",
   "opentelemetry-sdk>=1.33.0",
   "pydantic>=2.11.3",
-  "sse-starlette",
-  "starlette"
 ]
 
 classifiers = [
@@ -32,6 +29,7 @@ classifiers = [
 ]
 
 [project.optional-dependencies]
+http-server = ["fastapi>=0.115.2", "sse-starlette", "starlette"]
 postgresql = ["sqlalchemy[asyncio,postgresql-asyncpg]>=2.0.0"]
 mysql = ["sqlalchemy[asyncio,aiomysql]>=2.0.0"]
 sqlite = ["sqlalchemy[asyncio,aiosqlite]>=2.0.0"]
@@ -88,6 +86,9 @@ dev = [
   "types-protobuf",
   "types-requests",
   "pre-commit",
+  "fastapi>=0.115.2",
+  "sse-starlette",
+  "starlette",
   "pyupgrade",
   "autoflake",
   "no_implicit_optional",

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

@@ -2,9 +2,22 @@
 
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from fastapi import FastAPI
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+    _package_fastapi_installed = True
+else:
+    try:
+        from fastapi import FastAPI
+
+        _package_fastapi_installed = True
+    except ImportError:
+        FastAPI = Any
+
+        _package_fastapi_installed = False
 
 from a2a.server.apps.jsonrpc.jsonrpc_app import (
     CallContextBuilder,
@@ -38,7 +51,7 @@ def __init__(
         extended_agent_card: AgentCard | None = None,
         context_builder: CallContextBuilder | None = None,
     ) -> None:
-        """Initializes the A2AStarletteApplication.
+        """Initializes the A2AFastAPIApplication.
 
         Args:
             agent_card: The AgentCard describing the agent's capabilities.
@@ -50,6 +63,12 @@ def __init__(
               ServerCallContext passed to the http_handler. If None, no
               ServerCallContext is passed.
         """
+        if not _package_fastapi_installed:
+            raise ImportError(
+                'The `fastapi` package is required to use the `A2AFastAPIApplication`.'
+                ' It can be added as a part of `a2a-sdk` optional dependencies,'
+                ' `a2a-sdk[http-server]`.'
+            )
         super().__init__(
             agent_card=agent_card,
             http_handler=http_handler,

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

@@ -5,17 +5,9 @@
 
 from abc import ABC, abstractmethod
 from collections.abc import AsyncGenerator
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from fastapi import FastAPI
 from pydantic import ValidationError
-from sse_starlette.sse import EventSourceResponse
-from starlette.applications import Starlette
-from starlette.authentication import BaseUser
-from starlette.exceptions import HTTPException
-from starlette.requests import Request
-from starlette.responses import JSONResponse, Response
-from starlette.status import HTTP_413_REQUEST_ENTITY_TOO_LARGE
 
 from a2a.auth.user import UnauthenticatedUser
 from a2a.auth.user import User as A2AUser
@@ -61,6 +53,42 @@
 
 logger = logging.getLogger(__name__)
 
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+    from sse_starlette.sse import EventSourceResponse
+    from starlette.applications import Starlette
+    from starlette.authentication import BaseUser
+    from starlette.exceptions import HTTPException
+    from starlette.requests import Request
+    from starlette.responses import JSONResponse, Response
+    from starlette.status import HTTP_413_REQUEST_ENTITY_TOO_LARGE
+
+    _package_starlette_installed = True
+else:
+    FastAPI = Any
+    try:
+        from sse_starlette.sse import EventSourceResponse
+        from starlette.applications import Starlette
+        from starlette.authentication import BaseUser
+        from starlette.exceptions import HTTPException
+        from starlette.requests import Request
+        from starlette.responses import JSONResponse, Response
+        from starlette.status import HTTP_413_REQUEST_ENTITY_TOO_LARGE
+
+        _package_starlette_installed = True
+    except ImportError:
+        _package_starlette_installed = False
+        # Provide placeholder types for runtime type hinting when dependencies are not installed.
+        # These will not be used if the code path that needs them is guarded by _http_server_installed.
+        EventSourceResponse = Any
+        Starlette = Any
+        BaseUser = Any
+        HTTPException = Any
+        Request = Any
+        JSONResponse = Any
+        Response = Any
+        HTTP_413_REQUEST_ENTITY_TOO_LARGE = Any
+
 
 class StarletteUserProxy(A2AUser):
     """Adapts the Starlette User class to the A2A user representation."""
@@ -130,7 +158,7 @@ def __init__(
         extended_agent_card: AgentCard | None = None,
         context_builder: CallContextBuilder | None = None,
     ) -> None:
-        """Initializes the A2AStarletteApplication.
+        """Initializes the JSONRPCApplication.
 
         Args:
             agent_card: The AgentCard describing the agent's capabilities.
@@ -142,6 +170,12 @@ def __init__(
               ServerCallContext passed to the http_handler. If None, no
               ServerCallContext is passed.
         """
+        if not _package_starlette_installed:
+            raise ImportError(
+                'Packages `starlette` and `sse-starlette` are required to use the'
+                ' `JSONRPCApplication`. They can be added as a part of `a2a-sdk`'
+                ' optional dependencies, `a2a-sdk[http-server]`.'
+            )
         self.agent_card = agent_card
         self.extended_agent_card = extended_agent_card
         self.handler = JSONRPCHandler(

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

@@ -1,9 +1,25 @@
 import logging
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
-from starlette.applications import Starlette
-from starlette.routing import Route
+
+if TYPE_CHECKING:
+    from starlette.applications import Starlette
+    from starlette.routing import Route
+
+    _package_starlette_installed = True
+
+else:
+    try:
+        from starlette.applications import Starlette
+        from starlette.routing import Route
+
+        _package_starlette_installed = True
+    except ImportError:
+        Starlette = Any
+        Route = Any
+
+        _package_starlette_installed = False
 
 from a2a.server.apps.jsonrpc.jsonrpc_app import (
     CallContextBuilder,
@@ -49,6 +65,12 @@ def __init__(
               ServerCallContext passed to the http_handler. If None, no
               ServerCallContext is passed.
         """
+        if not _package_starlette_installed:
+            raise ImportError(
+                'Packages `starlette` and `sse-starlette` are required to use the'
+                ' `A2AStarletteApplication`. It can be added as a part of `a2a-sdk`'
+                ' optional dependencies, `a2a-sdk[http-server]`.'
+            )
         super().__init__(
             agent_card=agent_card,
             http_handler=http_handler,

tests/server/apps/jsonrpc/test_fastapi_app.py

@@ -0,0 +1,80 @@
+from typing import Any
+from unittest.mock import MagicMock
+
+import pytest
+
+from a2a.server.apps.jsonrpc import fastapi_app
+from a2a.server.apps.jsonrpc.fastapi_app import A2AFastAPIApplication
+from a2a.server.request_handlers.request_handler import (
+    RequestHandler,  # For mock spec
+)
+from a2a.types import AgentCard  # For mock spec
+
+
+# --- A2AFastAPIApplication Tests ---
+
+
+class TestA2AFastAPIApplicationOptionalDeps:
+    # Running tests in this class requires the optional dependency fastapi to be
+    # present in the test environment.
+
+    @pytest.fixture(scope='class', autouse=True)
+    def ensure_pkg_fastapi_is_present(self):
+        try:
+            import fastapi as _fastapi  # noqa: F401
+        except ImportError:
+            pytest.fail(
+                f'Running tests in {self.__class__.__name__} requires'
+                ' the optional dependency fastapi to be present in the test'
+                ' environment. Run `uv sync --dev ...` before running the test'
+                ' suite.'
+            )
+
+    @pytest.fixture(scope='class')
+    def mock_app_params(self) -> dict:
+        # Mock http_handler
+        mock_handler = MagicMock(spec=RequestHandler)
+        # Mock agent_card with essential attributes accessed in __init__
+        mock_agent_card = MagicMock(spec=AgentCard)
+        # Ensure 'url' attribute exists on the mock_agent_card, as it's accessed
+        # in __init__
+        mock_agent_card.url = 'http://example.com'
+        # Ensure 'supportsAuthenticatedExtendedCard' attribute exists
+        mock_agent_card.supportsAuthenticatedExtendedCard = False
+        return dict(agent_card=mock_agent_card, http_handler=mock_handler)
+
+    @pytest.fixture(scope='class')
+    def mark_pkg_fastapi_not_installed(self):
+        pkg_fastapi_installed_flag = fastapi_app._package_fastapi_installed
+        fastapi_app._package_fastapi_installed = False
+        yield
+        fastapi_app._package_fastapi_installed = pkg_fastapi_installed_flag
+
+    def test_create_a2a_fastapi_app_with_present_deps_succeeds(
+        self, mock_app_params: dict
+    ):
+        try:
+            _app = A2AFastAPIApplication(**mock_app_params)
+        except ImportError:
+            pytest.fail(
+                'With the fastapi package present, creating a'
+                ' A2AFastAPIApplication instance should not raise ImportError'
+            )
+
+    def test_create_a2a_fastapi_app_with_missing_deps_raises_importerror(
+        self,
+        mock_app_params: dict,
+        mark_pkg_fastapi_not_installed: Any,
+    ):
+        with pytest.raises(
+            ImportError,
+            match=(
+                'The `fastapi` package is required to use the'
+                ' `A2AFastAPIApplication`'
+            ),
+        ):
+            _app = A2AFastAPIApplication(**mock_app_params)
+
+
+if __name__ == '__main__':
+    pytest.main([__file__])