New multi-surface agent example that works with the contact custom component client (#275)

* feat(client): update contact client for custom components and multiple surfaces

* feat(renderer): enable custom component registration

* Add a new multi-surface contact lookup agent that streams to the custom component 'contact' client.

* Add readme.

* Refactored the Contact Multiple Surfaces agent to address review comments, specifically moving large example strings into separate JSON files and improving error handling.

* Rename inlineCatalog to inlineCatalogs

* remove newline

* Fix build

Author: dmandar

renderers/lit/src/0.8/ui/component-registry.ts

@@ -17,13 +17,15 @@
 import { CustomElementConstructorOf } from "./ui.js";
 
 export class ComponentRegistry {
+  private schemas: Map<string, unknown> = new Map();
   private registry: Map<string, CustomElementConstructorOf<HTMLElement>> =
     new Map();
 
   register(
     typeName: string,
     constructor: CustomElementConstructorOf<HTMLElement>,
-    tagName?: string
+    tagName?: string,
+    schema?: unknown
   ) {
     if (!/^[a-zA-Z0-9]+$/.test(typeName)) {
       throw new Error(
@@ -32,6 +34,9 @@ export class ComponentRegistry {
     }
 
     this.registry.set(typeName, constructor);
+    if (schema) {
+      this.schemas.set(typeName, schema);
+    }
     const actualTagName = tagName || `a2ui-custom-${typeName.toLowerCase()}`;
 
     const existingName = customElements.getName(constructor);
@@ -53,6 +58,14 @@ export class ComponentRegistry {
   get(typeName: string): CustomElementConstructorOf<HTMLElement> | undefined {
     return this.registry.get(typeName);
   }
+
+  getInlineCatalog(): { components: { [key: string]: unknown } } {
+    const components: { [key: string]: unknown } = {};
+    for (const [key, value] of this.schemas) {
+      components[key] = value;
+    }
+    return { components };
+  }
 }
 
 export const componentRegistry = new ComponentRegistry();

renderers/lit/src/0.8/ui/surface.ts

@@ -68,6 +68,10 @@ export class Surface extends Root {
     </div>`;
   }
 
+  @property()
+  accessor enableCustomElements = false;
+
+
   #renderSurface() {
     const styles: Record<string, string> = {};
     if (this.surface?.styles) {
@@ -121,6 +125,7 @@ export class Surface extends Root {
       .childComponents=${this.surface?.componentTree
         ? [this.surface.componentTree]
         : null}
+      .enableCustomElements=${this.enableCustomElements}
     ></a2ui-root>`;
   }
 

samples/agent/adk/contact_multiple_surfaces/README.md

@@ -0,0 +1,38 @@
+# A2UI Contact Multiple Surfaces Agent Sample
+
+This sample uses the Agent Development Kit (ADK) along with the A2A protocol to create a simple "Contact Lookup" 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_contact_lookup
+    ```
+
+2. Create an environment file with your API key:
+
+   ```bash
+   echo "GEMINI_API_KEY=your_api_key_here" > .env
+   ```
+
+3. Run the server:
+
+   ```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.

samples/agent/adk/contact_multiple_surfaces/README_CUSTOM_COMPONENTS.md

@@ -0,0 +1,65 @@
+# A2UI Custom Components & Multiple Surfaces Guide
+
+This guide explains how the **Contact Client** and **Contact Multiple Surfaces Agent** work in tandem to deliver rich, custom user interfaces beyond the standard A2UI library.
+
+## Architecture Overview
+
+Unlike standard A2UI agents that rely solely on the core component library, this sample demonstrates a **Client-First Extension Model**:
+
+1.  **Client Defines Components**: The web client (`contact` sample) defines custom components (`OrgChart`, `WebFrame`) and their schemas.
+2.  **Inline Catalog Negotiation**: When the client connects to the agent, it sends these schemas in its connection handshake (Client Event) under `metadata.inlineCatalog`.
+3.  **Agent Adaptation**: The agent (`contact_multiple_surfaces`) dynamically reads this catalog and injects the schema into the LLM's system prompt (via `[SYSTEM]` messages).
+4.  **Rich Rendering**: The LLM can then instruct the client to render these custom components.
+
+## Key Features
+
+### 1. Multiple Surfaces
+The agent manages multiple distinct UI areas ("surfaces") simultaneously:
+-   **`contact-card`**: The main profile view validation.
+-   **`org-chart-view`**: A side-by-side organizational chart.
+-   **`location-surface`**: A transient modal/overlay for map views.
+
+### 2. Custom Components
+
+#### `OrgChart`
+A custom LitElement component created in the client that renders a hierarchical view.
+-   **Schema**: Defined in `samples/client/lit/contact/ui/custom-components`.
+-   **Usage**: The agent sends a JSON structure matching the schema, and the client renders it natively.
+
+#### `WebFrame` (Iframe Component)
+A powerful component that allows embedding external web content or local static HTML files within the A2UI interface.
+-   **Usage in Sample**: Used to render the "Office Floor Plan".
+-   **Security**: Uses standard iframe sequencing and sandbox attributes.
+-   **Interactivity**: Can communicate back to the parent A2UI application (e.g., clicking a desk on the map triggers an A2UI action `chart_node_click`).
+
+## How to Run in Tandem
+
+1.  **Start the Agent**:
+    ```bash
+    cd samples/agent/adk/contact_multiple_surfaces
+    uv run .
+    ```
+    *Runs on port 10004.*
+
+2.  **Start the Client**:
+    ```bash
+    cd samples/client/lit/contact
+    npm run dev
+    ```
+    *Configured to connect to localhost:10004.*
+
+## Flow Example: "View Location"
+
+1.  **User Trigger**: User clicks "Location" on a profile card.
+2.  **Action**: Client sends standard A2UI action `view_location`.
+3.  **Agent Response**: Agent detects the intent and returns a message to render the `location-surface`.
+4.  **Component Payload**:
+    ```json
+    {
+      "WebFrame": {
+        "url": "http://localhost:10004/static/floorplan.html?data=...",
+        "interactionMode": "interactive"
+      }
+    }
+    ```
+5.  **Rendering**: Client receives the message, creates the surface, and instantiates the `WebFrame` component, loading the static HTML map served by the agent.

samples/agent/adk/contact_multiple_surfaces/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from . import agent

samples/agent/adk/contact_multiple_surfaces/__main__.py

@@ -0,0 +1,110 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+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.a2ui_extension import get_a2ui_agent_extension
+from agent import ContactAgent
+from agent_executor import ContactAgentExecutor
+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=10004)
+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."
+                )
+
+        capabilities = AgentCapabilities(
+            streaming=True,
+            extensions=[get_a2ui_agent_extension()],
+        )
+        skill = AgentSkill(
+            id="find_contact",
+            name="Find Contact Tool",
+            description="Helps find contact information for colleagues (e.g., email, location, team).",
+            tags=["contact", "directory", "people", "finder"],
+            examples=["Who is David Chen in marketing?", "Find Sarah Lee from engineering"],
+        )
+
+        base_url = f"http://{host}:{port}"
+
+        agent_card = AgentCard(
+            name="Contact Lookup Agent",
+            description="This agent helps find contact info for people in your organization.",
+            url=base_url,  # <-- Use base_url here
+            version="1.0.0",
+            default_input_modes=ContactAgent.SUPPORTED_CONTENT_TYPES,
+            default_output_modes=ContactAgent.SUPPORTED_CONTENT_TYPES,
+            capabilities=capabilities,
+            skills=[skill],
+        )
+
+        agent_executor = ContactAgentExecutor(base_url=base_url)
+
+        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()