refactor!: Make the FastAPI and Starlette dependencies optional (#217)

# Description

This update makes Starlette and FastAPI libraries as optional
dependencies. Users can run `uv add a2a-sdk[http-server]` to install
these dependencies.

## Additional Checks

- Verified that the "helloworld" agent sample works with this change.
- Verified that a reasonable error message is printed when trying to use
`A2AFastAPIApplication`.

Release-As: 0.3.0

---------

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Co-authored-by: Holt Skinner <holtskinner@google.com>

Author: darkhaniop

.github/workflows/unit-tests.yml

@@ -57,6 +57,6 @@ jobs:
       - name: Install dependencies
         run: uv sync --dev --extra sql --extra encryption --extra grpc --extra telemetry
       - name: Run tests and check coverage
-        run: uv run pytest --cov=a2a --cov-report term --cov-fail-under=89
+        run: uv run pytest --cov=a2a --cov-report term --cov-fail-under=88
       - name: Show coverage summary in log
         run: uv run coverage report

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
@@ -69,6 +75,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,12 +8,9 @@ authors = [{ name = "Google LLC", email = "googleapis-packages@google.com" }]
 requires-python = ">=3.10"
 keywords = ["A2A", "A2A SDK", "A2A Protocol", "Agent2Agent", "Agent 2 Agent"]
 dependencies = [
-  "fastapi>=0.95.0",
   "httpx>=0.28.1",
   "httpx-sse>=0.4.0",
   "pydantic>=2.11.3",
-  "sse-starlette",
-  "starlette",
   "protobuf>=5.29.5",
   "google-api-core>=1.26.0",
 ]
@@ -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"]
@@ -89,6 +87,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

@@ -1,13 +1,30 @@
 import logging
 
-from typing import Any
+from collections.abc import Callable
+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,
     JSONRPCApplication,
 )
-from a2a.types import A2ARequest
+from a2a.server.context import ServerCallContext
+from a2a.server.request_handlers.jsonrpc_handler import RequestHandler
+from a2a.types import A2ARequest, AgentCard
 from a2a.utils.constants import (
     AGENT_CARD_WELL_KNOWN_PATH,
     DEFAULT_RPC_URL,
@@ -49,6 +66,50 @@ class A2AFastAPIApplication(JSONRPCApplication):
     (SSE).
     """
 
+    def __init__(  # noqa: PLR0913
+        self,
+        agent_card: AgentCard,
+        http_handler: RequestHandler,
+        extended_agent_card: AgentCard | None = None,
+        context_builder: CallContextBuilder | None = None,
+        card_modifier: Callable[[AgentCard], AgentCard] | None = None,
+        extended_card_modifier: Callable[
+            [AgentCard, ServerCallContext], AgentCard
+        ]
+        | None = None,
+    ) -> None:
+        """Initializes the A2AFastAPIApplication.
+
+        Args:
+            agent_card: The AgentCard describing the agent's capabilities.
+            http_handler: The handler instance responsible for processing A2A
+              requests via http.
+            extended_agent_card: An optional, distinct AgentCard to be served
+              at the authenticated extended card endpoint.
+            context_builder: The CallContextBuilder used to construct the
+              ServerCallContext passed to the http_handler. If None, no
+              ServerCallContext is passed.
+            card_modifier: An optional callback to dynamically modify the public
+              agent card before it is served.
+            extended_card_modifier: An optional callback to dynamically modify
+              the extended agent card before it is served. It receives the
+              call context.
+        """
+        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,
+            extended_agent_card=extended_agent_card,
+            context_builder=context_builder,
+            card_modifier=card_modifier,
+            extended_card_modifier=extended_card_modifier,
+        )
+
     def add_routes_to_app(
         self,
         app: FastAPI,

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

@@ -5,17 +5,9 @@
 
 from abc import ABC, abstractmethod
 from collections.abc import AsyncGenerator, Callable
-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."""
@@ -135,7 +163,7 @@ def __init__(  # noqa: PLR0913
         ]
         | None = None,
     ) -> None:
-        """Initializes the A2AStarletteApplication.
+        """Initializes the JSONRPCApplication.
 
         Args:
             agent_card: The AgentCard describing the agent's capabilities.
@@ -152,6 +180,12 @@ def __init__(  # noqa: PLR0913
               the extended agent card before it is served. It receives the
               call context.
         """
+        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.card_modifier = card_modifier

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

@@ -1,13 +1,34 @@
 import logging
 
-from typing import Any
+from collections.abc import Callable
+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,
     JSONRPCApplication,
 )
+from a2a.server.context import ServerCallContext
+from a2a.server.request_handlers.jsonrpc_handler import RequestHandler
+from a2a.types import AgentCard
 from a2a.utils.constants import (
     AGENT_CARD_WELL_KNOWN_PATH,
     DEFAULT_RPC_URL,
@@ -27,6 +48,50 @@ class A2AStarletteApplication(JSONRPCApplication):
     (SSE).
     """
 
+    def __init__(  # noqa: PLR0913
+        self,
+        agent_card: AgentCard,
+        http_handler: RequestHandler,
+        extended_agent_card: AgentCard | None = None,
+        context_builder: CallContextBuilder | None = None,
+        card_modifier: Callable[[AgentCard], AgentCard] | None = None,
+        extended_card_modifier: Callable[
+            [AgentCard, ServerCallContext], AgentCard
+        ]
+        | None = None,
+    ) -> None:
+        """Initializes the A2AStarletteApplication.
+
+        Args:
+            agent_card: The AgentCard describing the agent's capabilities.
+            http_handler: The handler instance responsible for processing A2A
+              requests via http.
+            extended_agent_card: An optional, distinct AgentCard to be served
+              at the authenticated extended card endpoint.
+            context_builder: The CallContextBuilder used to construct the
+              ServerCallContext passed to the http_handler. If None, no
+              ServerCallContext is passed.
+            card_modifier: An optional callback to dynamically modify the public
+              agent card before it is served.
+            extended_card_modifier: An optional callback to dynamically modify
+              the extended agent card before it is served. It receives the
+              call context.
+        """
+        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,
+            extended_agent_card=extended_agent_card,
+            context_builder=context_builder,
+            card_modifier=card_modifier,
+            extended_card_modifier=extended_card_modifier,
+        )
+
     def routes(
         self,
         agent_card_url: str = AGENT_CARD_WELL_KNOWN_PATH,

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

@@ -1,8 +1,25 @@
 import logging
 
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    from fastapi import APIRouter, FastAPI, Request, Response
+
+    _package_fastapi_installed = True
+else:
+    try:
+        from fastapi import APIRouter, FastAPI, Request, Response
+
+        _package_fastapi_installed = True
+    except ImportError:
+        APIRouter = Any
+        FastAPI = Any
+        Request = Any
+        Response = Any
+
+        _package_fastapi_installed = False
 
-from fastapi import APIRouter, FastAPI, Request, Response
 
 from a2a.server.apps.jsonrpc.jsonrpc_app import CallContextBuilder
 from a2a.server.apps.rest.rest_adapter import RESTAdapter
@@ -40,6 +57,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'
+                ' `A2ARESTFastAPIApplication`. It can be added as a part of'
+                ' `a2a-sdk` optional dependencies, `a2a-sdk[http-server]`.'
+            )
         self._adapter = RESTAdapter(
             agent_card=agent_card,
             http_handler=http_handler,