Merge branch 'main' into make-fastapi-package-optional

Author: darkhaniop

.github/workflows/unit-tests.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Set postgres for tests
         run: |
           sudo apt-get update && sudo apt-get install -y postgresql-client
-          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d a2a_test -f ${{ github.workspace }}/docker/postgres/init.sql
+          PGPASSWORD=postgres psql -h localhost -p 5432 -U postgres -d a2a_test -f ${{ github.workspace }}/tests/docker/postgres/init.sql
           export POSTGRES_TEST_DSN="postgresql+asyncpg://postgres:postgres@localhost:5432/a2a_test"
 
       - name: Install uv

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.2.12](https://github.com/a2aproject/a2a-python/compare/v0.2.11...v0.2.12) (2025-07-14)
+
+
+### Features
+
+* add `metadata` property to `RequestContext` ([#302](https://github.com/a2aproject/a2a-python/issues/302)) ([e781ced](https://github.com/a2aproject/a2a-python/commit/e781ced3b082ef085f9aeef02ceebb9b35c68280))
+* add A2ABaseModel ([#292](https://github.com/a2aproject/a2a-python/issues/292)) ([24f2eb0](https://github.com/a2aproject/a2a-python/commit/24f2eb0947112539cbd4e493c98d0d9dadc87f05))
+* add support for notification tokens in PushNotificationSender ([#266](https://github.com/a2aproject/a2a-python/issues/266)) ([75aa4ed](https://github.com/a2aproject/a2a-python/commit/75aa4ed866a6b4005e59eb000e965fb593e0888f))
+* Update A2A types from specification 🤖 ([#289](https://github.com/a2aproject/a2a-python/issues/289)) ([ecb321a](https://github.com/a2aproject/a2a-python/commit/ecb321a354d691ca90b52cc39e0a397a576fd7d7))
+
+
+### Bug Fixes
+
+* add proper a2a request body documentation to Swagger UI ([#276](https://github.com/a2aproject/a2a-python/issues/276)) ([4343be9](https://github.com/a2aproject/a2a-python/commit/4343be99ad0df5eb6908867b71d55b1f7d0fafc6)), closes [#274](https://github.com/a2aproject/a2a-python/issues/274)
+* Handle asyncio.cancellederror and raise to propagate back ([#293](https://github.com/a2aproject/a2a-python/issues/293)) ([9d6cb68](https://github.com/a2aproject/a2a-python/commit/9d6cb68a1619960b9c9fd8e7aa08ffb27047343f))
+* Improve error handling in task creation ([#294](https://github.com/a2aproject/a2a-python/issues/294)) ([6412c75](https://github.com/a2aproject/a2a-python/commit/6412c75413e26489bd3d33f59e41b626a71807d3))
+* Resolve dependency issue with sql stores ([#303](https://github.com/a2aproject/a2a-python/issues/303)) ([2126828](https://github.com/a2aproject/a2a-python/commit/2126828b5cb6291f47ca15d56c0e870950f17536))
+* Send push notifications for message/send ([#298](https://github.com/a2aproject/a2a-python/issues/298)) ([0274112](https://github.com/a2aproject/a2a-python/commit/0274112bb5b077c17b344da3a65277f2ad67d38f))
+* **server:** Improve event consumer error handling ([#282](https://github.com/a2aproject/a2a-python/issues/282)) ([a5786a1](https://github.com/a2aproject/a2a-python/commit/a5786a112779a21819d28e4dfee40fa11f1bb49a))
+
 ## [0.2.11](https://github.com/a2aproject/a2a-python/compare/v0.2.10...v0.2.11) (2025-07-07)
 
 

scripts/generate_types.sh

@@ -32,6 +32,7 @@ uv run datamodel-codegen \
   --use-one-literal-as-default \
   --class-name A2A \
   --use-standard-collections \
-  --use-subclass-enum
+  --use-subclass-enum \
+  --base-class a2a._base.A2ABaseModel
 
 echo "Codegen finished successfully."

src/a2a/_base.py

@@ -0,0 +1,15 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class A2ABaseModel(BaseModel):
+    """Base class for shared behavior across A2A data models.
+
+    Provides a common configuration (e.g., alias-based population) and
+    serves as the foundation for future extensions or shared utilities.
+    """
+
+    model_config = ConfigDict(
+        # SEE: https://docs.pydantic.dev/latest/api/config/#pydantic.config.ConfigDict.populate_by_name
+        validate_by_name=True,
+        validate_by_alias=True,
+    )

src/a2a/grpc/a2a_pb2.py

@@ -1,5 +1,7 @@
 import uuid
 
+from typing import Any
+
 from a2a.server.context import ServerCallContext
 from a2a.types import (
     InvalidParamsError,
@@ -134,6 +136,13 @@ def call_context(self) -> ServerCallContext | None:
         """The server call context associated with this request."""
         return self._call_context
 
+    @property
+    def metadata(self) -> dict[str, Any]:
+        """Metadata associated with the request, if available."""
+        if not self._params:
+            return {}
+        return self._params.metadata or {}
+
     def _check_or_generate_task_id(self) -> None:
         """Ensures a task ID is present, generating one if necessary."""
         if not self._params:

src/a2a/server/agent_execution/context.py

@@ -39,6 +39,7 @@
 from a2a.utils.constants import (
     AGENT_CARD_WELL_KNOWN_PATH,
     DEFAULT_RPC_URL,
+    EXTENDED_AGENT_CARD_PATH,
 )
 from a2a.utils.errors import MethodNotImplementedError
 
@@ -50,8 +51,10 @@
     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:
@@ -60,8 +63,10 @@
         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:
@@ -71,9 +76,11 @@
         EventSourceResponse = Any
         Starlette = Any
         BaseUser = Any
+        HTTPException = Any
         Request = Any
         JSONResponse = Any
         Response = Any
+        HTTP_413_REQUEST_ENTITY_TOO_LARGE = Any
 
 
 class StarletteUserProxy(A2AUser):
@@ -206,7 +213,7 @@ def _generate_error_response(
             status_code=200,
         )
 
-    async def _handle_requests(self, request: Request) -> Response:
+    async def _handle_requests(self, request: Request) -> Response:  # noqa: PLR0911
         """Handles incoming POST requests to the main A2A endpoint.
 
         Parses the request body as JSON, validates it against A2A request types,
@@ -262,6 +269,15 @@ async def _handle_requests(self, request: Request) -> Response:
                 request_id,
                 A2AError(root=InvalidRequestError(data=json.loads(e.json()))),
             )
+        except HTTPException as e:
+            if e.status_code == HTTP_413_REQUEST_ENTITY_TOO_LARGE:
+                return self._generate_error_response(
+                    request_id,
+                    A2AError(
+                        root=InvalidRequestError(message='Payload too large')
+                    ),
+                )
+            raise e
         except Exception as e:
             logger.error(f'Unhandled exception: {e}')
             traceback.print_exc()
@@ -468,13 +484,16 @@ def build(
         self,
         agent_card_url: str = AGENT_CARD_WELL_KNOWN_PATH,
         rpc_url: str = DEFAULT_RPC_URL,
+        extended_agent_card_url: str = EXTENDED_AGENT_CARD_PATH,
         **kwargs: Any,
     ) -> FastAPI | Starlette:
         """Builds and returns the JSONRPC application instance.
 
         Args:
             agent_card_url: The URL for the agent card endpoint.
-            rpc_url: The URL for the A2A JSON-RPC endpoint
+            rpc_url: The URL for the A2A JSON-RPC endpoint.
+            extended_agent_card_url: The URL for the authenticated extended
+              agent card endpoint.
             **kwargs: Additional keyword arguments to pass to the FastAPI constructor.
 
         Returns:

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

@@ -4,6 +4,8 @@
 
 from collections.abc import AsyncGenerator
 
+from pydantic import ValidationError
+
 from a2a.server.events.event_queue import Event, EventQueue
 from a2a.types import (
     InternalError,
@@ -138,6 +140,9 @@ async def consume_all(self) -> AsyncGenerator[Event]:
                 # python 3.12 and get a queue empty error on an open queue
                 if self.queue.is_closed():
                     break
+            except ValidationError as e:
+                logger.error(f'Invalid event format received: {e}')
+                continue
             except Exception as e:
                 logger.error(
                     f'Stopping event consumption due to exception: {e}'

src/a2a/server/events/event_consumer.py

@@ -33,9 +33,7 @@
     InvalidParamsError,
     ListTaskPushNotificationConfigParams,
     Message,
-    MessageSendConfiguration,
     MessageSendParams,
-    PushNotificationConfig,
     Task,
     TaskIdParams,
     TaskNotFoundError,
@@ -202,18 +200,6 @@ async def _setup_message_execution(
                 )
 
             task = task_manager.update_with_message(params.message, task)
-            if self.should_add_push_info(params):
-                assert self._push_config_store is not None
-                assert isinstance(
-                    params.configuration, MessageSendConfiguration
-                )
-                assert isinstance(
-                    params.configuration.pushNotificationConfig,
-                    PushNotificationConfig,
-                )
-                await self._push_config_store.set_info(
-                    task.id, params.configuration.pushNotificationConfig
-                )
 
         # Build request context
         request_context = await self._request_context_builder.build(
@@ -228,6 +214,16 @@ async def _setup_message_execution(
         # Always assign a task ID. We may not actually upgrade to a task, but
         # dictating the task ID at this layer is useful for tracking running
         # agents.
+
+        if (
+            self._push_config_store
+            and params.configuration
+            and params.configuration.pushNotificationConfig
+        ):
+            await self._push_config_store.set_info(
+                task_id, params.configuration.pushNotificationConfig
+            )
+
         queue = await self._queue_manager.create_or_tap(task_id)
         result_aggregator = ResultAggregator(task_manager)
         # TODO: to manage the non-blocking flows.
@@ -333,16 +329,6 @@ async def on_message_send_stream(
                 if isinstance(event, Task):
                     self._validate_task_id_match(task_id, event.id)
 
-                if (
-                    self._push_config_store
-                    and params.configuration
-                    and params.configuration.pushNotificationConfig
-                ):
-                    await self._push_config_store.set_info(
-                        task_id,
-                        params.configuration.pushNotificationConfig,
-                    )
-
                 await self._send_push_notification_if_needed(
                     task_id, result_aggregator
                 )
@@ -509,11 +495,3 @@ async def on_delete_task_push_notification_config(
         await self._push_config_store.delete_info(
             params.id, params.pushNotificationConfigId
         )
-
-    def should_add_push_info(self, params: MessageSendParams) -> bool:
-        """Determines if push notification info should be set for a task."""
-        return bool(
-            self._push_config_store
-            and params.configuration
-            and params.configuration.pushNotificationConfig
-        )

src/a2a/server/request_handlers/default_request_handler.py

@@ -1,9 +1,10 @@
 """Components for managing tasks within the A2A server."""
 
+import logging
+
 from a2a.server.tasks.base_push_notification_sender import (
     BasePushNotificationSender,
 )
-from a2a.server.tasks.database_task_store import DatabaseTaskStore
 from a2a.server.tasks.inmemory_push_notification_config_store import (
     InMemoryPushNotificationConfigStore,
 )
@@ -18,6 +19,30 @@
 from a2a.server.tasks.task_updater import TaskUpdater
 
 
+logger = logging.getLogger(__name__)
+
+try:
+    from a2a.server.tasks.database_task_store import (
+        DatabaseTaskStore,  # type: ignore
+    )
+except ImportError as e:
+    _original_error = e
+    # If the database task store is not available, we can still use in-memory stores.
+    logger.debug(
+        'DatabaseTaskStore not loaded. This is expected if database dependencies are not installed. Error: %s',
+        e,
+    )
+
+    class DatabaseTaskStore:  # type: ignore
+        """Placeholder for DatabaseTaskStore when dependencies are not installed."""
+
+        def __init__(self, *args, **kwargs):
+            raise ImportError(
+                'To use DatabaseTaskStore, its dependencies must be installed. '
+                'You can install them with \'pip install "a2a-sdk[sql]"\''
+            ) from _original_error
+
+
 __all__ = [
     'BasePushNotificationSender',
     'DatabaseTaskStore',