Initial commit for a2ui_restaurant_finder and a generic a2UI extension. (#31)

* Initial commit for a2ui_restaurant_finder and a generic a2UI extension.

* Update spec.md with catalog definition.

* Only have data fetch be a tool. Pass the UI requirements in the prompt.

Author: dmandar

a2a_samples/a2ui_extension/README.md

@@ -0,0 +1,11 @@
+# A2UI Extension Implementation
+
+This is the Python implementation of the a2ui extension.
+
+## Disclaimer
+
+Important: The sample code provided is for demonstration purposes and illustrates the mechanics of the Agent-to-Agent (A2A) protocol. When building production applications, it is critical to treat any agent operating outside of your direct control as a potentially untrusted entity.
+
+All data received from an external agent—including but not limited to its AgentCard, messages, artifacts, and task statuses—should be handled as untrusted input. For example, a malicious agent could provide an AgentCard containing crafted data in its fields (e.g., description, name, skills.description). If this data is used without sanitization to construct prompts for a Large Language Model (LLM), it could expose your application to prompt injection attacks.  Failure to properly validate and sanitize this data before use can introduce security vulnerabilities into your application.
+
+Developers are responsible for implementing appropriate security measures, such as input validation and secure handling of credentials to protect their systems and users.

a2a_samples/a2ui_extension/pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "a2ui_ext"
+version = "0.1.0"
+description = "a2ui Extension"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["a2a-sdk>=0.3.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

a2a_samples/a2ui_extension/spec/spec.md

@@ -0,0 +1,51 @@
+# A2UI (Agent-to-Agent UI) Extension Spec
+## Overview
+This extension implements the A2UI (Agent-to-Agent UI) spec, a format for agents to send streaming, interactive user interfaces to clients.
+
+## Extension URI
+The URI of this extension is https://github.com/google/a2ui/a2a_samples/a2ui_extension/spec/spec.md.
+
+This is the only URI accepted for this extension.
+
+## Core Concepts
+The A2UI extension is built on three main concepts:
+
+Surfaces: A "Surface" is a distinct, controllable region of the client's UI. The spec uses a surfaceId to direct updates to specific surfaces (e.g., a main content area, a side panel, or a new chat bubble). This allows a single agent stream to manage multiple UI areas independently.
+
+Catalog Definition Document: The a2ui extension is component-agnostic. All UI components (e.g., Text, Row, Button) and their stylings are defined in a separate Catalog Definition Schema. This allows clients and servers to negotiate which catalog to use.
+
+Schemas: The a2ui extension is defined by three primary JSON schemas:
+
+Catalog Definition Schema: A standard format for defining a library of components and styles.
+
+Server-to-Client Message Schema: The core wire format for messages sent from the agent to the client (e.g., surfaceUpdate, dataModelUpdate).
+
+Client-to-Server Event Schema: The core wire format for messages sent from the client to the agent (e.g., userAction, clientUiCapabilities).
+
+Agent Capability Declaration
+Agents advertise their A2UI capabilities in their AgentCard within the AgentCapabilities.extensions list. The params object defines the agent's specific UI support, including which component catalogs it can generate and whether it accepts dynamic catalogs from the client.
+
+Example AgentExtension block:
+
+Parameter Definitions
+params.supportedSchemas: (REQUIRED) An array of strings, where each string is a URI pointing to a component Catalog Definition Schema that the agent can generate. This could include the default catalog or custom catalogs or both.
+
+params.acceptsDynamicSchemas: (OPTIONAL) A boolean indicating if the agent can accept a clientUiCapabilities message containing a dynamicCatalog. If omitted, this defaults to false.
+
+Client Capability Declaration
+The client-to-server spec includes a clientUiCapabilities message. If a client wishes to use a specific catalog (other than the server's default) or provide its own dynamic catalog, it MUST send this message after the connection is established and before the first user prompt.
+
+This message allows the client to specify either:
+
+A catalogUri: A URI for a known, shared catalog (which must be one of the supportedSchemas from the agent).
+
+A dynamicCatalog: An inline Catalog Definition Schema object. This is only allowed if the agent's acceptsDynamicSchemas capability is true.
+
+Extension Activation
+Clients indicate their desire to use the A2UI extension by specifying it via the transport-defined A2A extension activation mechanism.
+
+For JSON-RPC and HTTP transports, this is indicated via the X-A2A-Extensions HTTP header.
+
+For gRPC, this is indicated via the X-A2A-Extensions metadata value.
+
+Activating this extension implies that the server can send A2UI-specific messages (like surfaceUpdate) and the client is expected to send A2UI-specific events (like userAction).

a2a_samples/a2ui_extension/src/a2ui_ext/__init__.py

@@ -0,0 +1,76 @@
+import logging
+from typing import Any
+
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events.event_queue import EventQueue
+from a2a.types import AgentExtension, Task
+
+logger = logging.getLogger(__name__)
+
+# --- Define a2ui UI constants ---
+_CORE_PATH = "a2ui.org/ext/a2a-ui/v0.1"
+URI = f"https://{_CORE_PATH}"
+a2ui_MIME_TYPE = "application/json+a2ui"
+
+
+class a2uiExtension:
+    """A generic a2ui UI extension that activates UI mode."""
+
+    def agent_extension(self) -> AgentExtension:
+        """Get the AgentExtension representing this extension."""
+        return AgentExtension(
+            uri=URI,
+            description="Provides a declarative a2ui UI JSON structure in messages.",
+            params={
+                "supportedSchemas": [
+                    "https://raw.githubusercontent.com/google/a2ui/refs/heads/main/schemas/v0.1/standard_catalog.json"
+                ],
+                "acceptsDynamicSchemas": True,
+            },
+        )
+
+    def activate(self, context: RequestContext) -> bool:
+        """Checks if the a2ui UI extension was requested by the client."""
+        if URI in context.requested_extensions:
+            context.add_activated_extension(URI)
+            return True
+        return False
+
+    def wrap_executor(self, executor: AgentExecutor) -> AgentExecutor:
+        """Wrap an executor to activate the extension."""
+        return _a2uiExecutor(executor, self)
+
+
+class _a2uiExecutor(AgentExecutor):
+    """Executor wrapper that activates the a2ui UI extension."""
+
+    def __init__(self, delegate: AgentExecutor, ext: a2uiExtension):
+        self._delegate = delegate
+        self._ext = ext
+
+    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        # The extension's ONLY job is to check for the header and log activation.
+        logger.info(
+            f"--- Client requested extensions: {context.requested_extensions} ---"
+        )
+        use_ui = self._ext.activate(context)
+        if use_ui:
+            logger.info("--- a2ui UI EXTENSION ACTIVATED ---")
+        else:
+            logger.info("--- a2ui UI EXTENSION *NOT* ACTIVE ---")
+
+        # All parsing logic is now handled correctly inside the delegate executor.
+        # We pass the `use_ui` flag to the delegate.
+        await self._delegate.execute(context, event_queue, use_ui=use_ui)
+
+    async def cancel(
+        self, context: RequestContext, event_queue: EventQueue
+    ) -> Task | None:
+        return await self._delegate.cancel(context, event_queue)
+
+
+__all__ = [
+    "URI",
+    "a2uiExtension",
+    "a2ui_MIME_TYPE",
+]

a2a_samples/a2ui_extension/src/a2ui_ext/__pycache__/__init__.cpython-313.pyc

@@ -0,0 +1,38 @@
+# A2UI Restaurant finder and table reservation agent sample.
+
+This sample uses the Agent Development Kit (ADK) along with the A2A protocol to create a simple "Restaurant finder and table reservation" agent that is hosted as an A2A server.
+
+## Prerequisites
+
+- Python 3.9 or higher
+- [UV](https://docs.astral.sh/uv/)
+- Access to an LLM and API Key
+
+## Running the Sample
+
+1. Navigate to the samples directory:
+
+    ```bash
+    cd a2a_samples/a2ui_restaurant_finder
+    ```
+
+2. Create an environment file with your API key:
+
+   ```bash
+   echo "GEMINI_API_KEY=your_api_key_here" > .env
+   ```
+
+3. Run an agent:
+
+    ```bash
+    uv run .
+    ```
+
+
+## Disclaimer
+
+Important: The sample code provided is for demonstration purposes and illustrates the mechanics of the Agent-to-Agent (A2A) protocol. When building production applications, it is critical to treat any agent operating outside of your direct control as a potentially untrusted entity.
+
+All data received from an external agent—including but not limited to its AgentCard, messages, artifacts, and task statuses—should be handled as untrusted input. For example, a malicious agent could provide an AgentCard containing crafted data in its fields (e.g., description, name, skills.description). If this data is used without sanitization to construct prompts for a Large Language Model (LLM), it could expose your application to prompt injection attacks.  Failure to properly validate and sanitize this data before use can introduce security vulnerabilities into your application.
+
+Developers are responsible for implementing appropriate security measures, such as input validation and secure handling of credentials to protect their systems and users.

a2a_samples/a2ui_extension/src/a2ui_ext/py.typed

@@ -0,0 +1 @@
+from . import agent

a2a_samples/a2ui_restaurant_finder/README.md

@@ -0,0 +1,101 @@
+import logging
+import os
+
+import click
+from a2a.server.apps import A2AStarletteApplication
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.tasks import InMemoryTaskStore
+from a2a.types import AgentCapabilities, AgentCard, AgentSkill
+from a2ui_ext import a2uiExtension
+from agent import RestaurantAgent
+from agent_executor import RestaurantAgentExecutor
+from dotenv import load_dotenv
+from starlette.middleware.cors import CORSMiddleware
+from starlette.staticfiles import StaticFiles
+
+load_dotenv()
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class MissingAPIKeyError(Exception):
+    """Exception for missing API key."""
+
+
+@click.command()
+@click.option("--host", default="localhost")
+@click.option("--port", default=10002)
+def main(host, port):
+    try:
+        # Check for API key only if Vertex AI is not configured
+        if not os.getenv("GOOGLE_GENAI_USE_VERTEXAI") == "TRUE":
+            if not os.getenv("GEMINI_API_KEY"):
+                raise MissingAPIKeyError(
+                    "GEMINI_API_KEY environment variable not set and GOOGLE_GENAI_USE_VERTEXAI is not TRUE."
+                )
+
+        hello_ext = a2uiExtension()
+        capabilities = AgentCapabilities(
+            streaming=True,
+            extensions=[
+                hello_ext.agent_extension(),
+            ],
+        )
+        skill = AgentSkill(
+            id="find_restaurants",
+            name="Find Restaurants Tool",
+            description="Helps find restaurants based on user criteria (e.g., cuisine, location).",
+            tags=["restaurant", "finder"],
+            examples=["Find me the top 10 chinese restaurants in the US"],
+        )
+
+        base_url = f"http://{host}:{port}"
+
+        agent_card = AgentCard(
+            name="Restaurant Agent",
+            description="This agent helps find restaurants based on user criteria.",
+            url=base_url,  # <-- Use base_url here
+            version="1.0.0",
+            default_input_modes=RestaurantAgent.SUPPORTED_CONTENT_TYPES,
+            default_output_modes=RestaurantAgent.SUPPORTED_CONTENT_TYPES,
+            capabilities=capabilities,
+            skills=[skill],
+        )
+
+        agent_executor = RestaurantAgentExecutor(base_url=base_url)
+
+        agent_executor = hello_ext.wrap_executor(agent_executor)
+
+        request_handler = DefaultRequestHandler(
+            agent_executor=agent_executor,
+            task_store=InMemoryTaskStore(),
+        )
+        server = A2AStarletteApplication(
+            agent_card=agent_card, http_handler=request_handler
+        )
+        import uvicorn
+
+        app = server.build()
+
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=["http://localhost:5173"],
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+        app.mount("/static", StaticFiles(directory="images"), name="static")
+
+        uvicorn.run(app, host=host, port=port)
+    except MissingAPIKeyError as e:
+        logger.error(f"Error: {e}")
+        exit(1)
+    except Exception as e:
+        logger.error(f"An error occurred during server startup: {e}")
+        exit(1)
+
+
+if __name__ == "__main__":
+    main()