feat(a2a): add lifespan parameter to to_a2a()

Support Starlette lifespan protocol in to_a2a() so users can run
async startup/shutdown logic (e.g. initializing DB connections,
loading prompt registries) without resorting to module-level globals.

The lifespan parameter accepts a standard Starlette async context
manager. Internally, a composed lifespan runs the A2A route setup
first, then delegates to the user's lifespan if provided. This also
replaces the deprecated add_event_handler("startup", ...) pattern
with the modern Starlette(lifespan=...) constructor.

Closes #4701

Co-authored-by: Xiang (Sean) Zhou <seanzhougoogle@google.com>
PiperOrigin-RevId: 886892363

Author: seanzhougoogle

src/google/adk/a2a/utils/agent_to_a2a.py

@@ -14,7 +14,10 @@
 
 from __future__ import annotations
 
+from contextlib import asynccontextmanager
 import logging
+from typing import AsyncIterator
+from typing import Callable
 from typing import Optional
 from typing import Union
 
@@ -82,6 +85,7 @@ def to_a2a(
     agent_card: Optional[Union[AgentCard, str]] = None,
     push_config_store: Optional[PushNotificationConfigStore] = None,
     runner: Optional[Runner] = None,
+    lifespan: Optional[Callable[[Starlette], AsyncIterator[None]]] = None,
 ) -> Starlette:
   """Convert an ADK agent to a A2A Starlette application.
 
@@ -98,6 +102,11 @@ def to_a2a(
         config RPC methods are supported.
       runner: Optional pre-built Runner object. If not provided, a default
               runner will be created using in-memory services.
+      lifespan: Optional async context manager for Starlette lifespan
+        events. Use this to run startup/shutdown logic (e.g. initializing
+        database connections or loading resources). The context manager
+        receives the Starlette app instance and can set state on
+        ``app.state``.
 
   Returns:
       A Starlette application that can be run with uvicorn
@@ -109,6 +118,15 @@ def to_a2a(
 
       # Or with custom agent card:
       app = to_a2a(agent, agent_card=my_custom_agent_card)
+
+      # Or with lifespan:
+      @asynccontextmanager
+      async def lifespan(app):
+          app.state.db = await init_db()
+          yield
+          await app.state.db.close()
+
+      app = to_a2a(agent, lifespan=lifespan)
   """
   # Set up ADK logging to ensure logs are visible when using uvicorn directly
   adk_logger = logging.getLogger("google_adk")
@@ -151,11 +169,8 @@ async def create_runner() -> Runner:
       rpc_url=rpc_url,
   )
 
-  # Create a Starlette app that will be configured during startup
-  app = Starlette()
-
-  # Add startup handler to build the agent card and configure A2A routes
-  async def setup_a2a():
+  # Build the agent card and configure A2A routes
+  async def setup_a2a(app: Starlette):
     # Use provided agent card or build one asynchronously
     if provided_agent_card is not None:
       final_agent_card = provided_agent_card
@@ -173,7 +188,19 @@ async def setup_a2a():
         app,
     )
 
-  # Store the setup function to be called during startup
-  app.add_event_handler("startup", setup_a2a)
+  # Compose a lifespan that runs A2A setup and the user's lifespan
+  @asynccontextmanager
+  async def _combined_lifespan(
+      app: Starlette,
+  ) -> AsyncIterator[None]:
+    await setup_a2a(app)
+    if lifespan:
+      async with lifespan(app):
+        yield
+    else:
+      yield
+
+  # Create a Starlette app with the composed lifespan
+  app = Starlette(lifespan=_combined_lifespan)
 
   return app