Merge branch 'main' into ae_routes

Author: rajeshvelicheti

.github/actions/spelling/allow.txt

@@ -9,6 +9,7 @@ agentic
 AGrpc
 aio
 aiomysql
+amannn
 aproject
 ARequest
 ARun

.github/workflows/conventional-commits.yml

@@ -0,0 +1,26 @@
+name: "Conventional Commits"
+
+on:
+  pull_request:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  contents: read
+
+jobs:
+  main:
+    permissions:
+      pull-requests: read
+      statuses: write
+    name: Validate PR Title
+    runs-on: ubuntu-latest
+    steps:
+      - name: semantic-pull-request
+        uses: amannn/action-semantic-pull-request@v5.5.3
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          validateSingleCommit: false

.github/workflows/unit-tests.yml

@@ -40,23 +40,21 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
       - name: Set up test environment variables
         run: |
           echo "POSTGRES_TEST_DSN=postgresql+asyncpg://a2a:a2a_password@localhost:5432/a2a_test" >> $GITHUB_ENV
           echo "MYSQL_TEST_DSN=mysql+aiomysql://a2a:a2a_password@localhost:3306/a2a_test" >> $GITHUB_ENV
 
-      - name: Install uv
+      - name: Install uv for Python ${{ matrix.python-version }}
         uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
       - name: Add uv to PATH
         run: |
           echo "$HOME/.cargo/bin" >> $GITHUB_PATH
       - 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

error_handlers.py

@@ -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",

pyproject.toml

@@ -17,9 +17,6 @@ class A2AServiceStub(object):
     - TaskPushNotificationConfig are a resource whose parent is a task.
     They have get, list and create methods.
     - AgentCard is a static resource with only a get method.
-    fields are not present as they don't comply with AIP rules, and the
-    optional history_length on the get task method is not present as it also
-    violates AIP-127 and AIP-131.
     """
 
     def __init__(self, channel):
@@ -91,9 +88,6 @@ class A2AServiceServicer(object):
     - TaskPushNotificationConfig are a resource whose parent is a task.
     They have get, list and create methods.
     - AgentCard is a static resource with only a get method.
-    fields are not present as they don't comply with AIP rules, and the
-    optional history_length on the get task method is not present as it also
-    violates AIP-127 and AIP-131.
     """
 
     def SendMessage(self, request, context):
@@ -244,9 +238,6 @@ class A2AService(object):
     - TaskPushNotificationConfig are a resource whose parent is a task.
     They have get, list and create methods.
     - AgentCard is a static resource with only a get method.
-    fields are not present as they don't comply with AIP rules, and the
-    optional history_length on the get task method is not present as it also
-    violates AIP-127 and AIP-131.
     """
 
     @staticmethod

src/a2a/grpc/a2a_pb2_grpc.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/fastapi_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