add a2ui example

.gitignore

@@ -148,4 +148,5 @@ package-lock.json
 *.tsbuildinfo
 .wireit/
 .angular/
-*.ts
+*.ts
+uv.lock

examples/agent/a2ui_agent/README.md

@@ -0,0 +1,110 @@
+# A2UI in AgentScope
+
+[A2UI (Agent-to-Agent UI)](https://github.com/google/A2UI) is a protocol for agents to send
+streaming, interactive user interfaces to clients. It enables LLMs to generate platform-agnostic,
+declarative UI definitions that clients can render progressively using native widget sets.
+
+In this example, we demonstrate how to integrate A2UI into a ReAct agent in AgentScope. This
+implementation is based on the official A2UI agent samples, adapted to use AgentScope's agent
+framework.
+
+Specifically, we have:
+
+1. **Reimplemented the agent with AgentScope**: The agent part of the official A2UI samples has
+   been reimplemented using AgentScope's `ReActAgent`, providing a more familiar and integrated
+   development experience for AgentScope users.
+
+2. **Progressive schema and template exposure via skills**: To help the agent learn and generate
+   A2UI-compliant interfaces, we use AgentScope's skill system to progressively expose the A2UI
+   schema and UI templates. The agent can dynamically load these resources through the
+   `A2UI_response_generator` skill, enabling it to understand component definitions and learn from
+   example UI structures.
+
+## Note on External Dependencies
+
+The following directories in this example contain content sourced from the [Google A2UI repository](https://github.com/google/A2UI):
+
+- **`samples/client/`**: A2UI client sample applications
+
+**NPM Package Status**: As of now, the A2UI client libraries (`@a2ui/lit` and `@a2ui/angular`) are **not yet published to NPM**. According to the [official A2UI client setup guide](https://a2ui.org/guides/client-setup/#renderers): "The Lit client library is not yet published to NPM. Check back in the coming days."
+
+Therefore, these dependencies are currently included in this example repository using local file paths (e.g., `"@a2ui/lit": "file:../../../../renderers/lit"` in `package.json` files). This mirrors the approach used in the [official A2UI repository](https://github.com/google/A2UI), where the renderers and samples also use local file paths to reference each other. Additionally, the `copy-spec` task in `renderers/lit/package.json` copies files from the local `specification/` directory during the build process.
+
+**Future Plans**: Once those libraries are published to NPM, we plan to gradually migrate to using the official NPM packages and remove these locally included directories.
+
+## Quick Start
+
+Download the a2ui and agentscope package to the same directory
+
+```bash
+git clone https://github.com/google/A2UI.git
+git clone -b main https://github.com/agentscope-ai/agentscope.git
+# copy the renders and specification directory to AgentScope/examples/agent/a2ui_agent
+copy -r a2ui/renderers AgentScope/examples/agent/a2ui_agent
+copy -r a2ui/specification AgentScope/examples/agent/a2ui_agent
+```
+
+
+Then, navigate to the client directory and run the restaurant finder demo:
+
+```bash
+cd AgentScope/examples/agent/a2ui_agent/samples/client/lit
+npm run demo:restaurant
+```
+
+This command will:
+- Install dependencies and build the A2UI renderer
+- Start the A2A server (AgentScope agent) for the restaurant finder
+- Launch the client application in your browser
+
+> Note:
+> - The example is built with DashScope chat model. Make sure to set your `DASHSCOPE_API_KEY`
+>   environment variable before running the demo.
+> - If you are using Qwen series models, we recommend using `qwen3-max` for better performance in
+>   generating A2UI-compliant JSON responses.
+> - Generating UI JSON responses may take some time, typically 1-2 minutes, as the agent needs to
+>   process the schema, examples, and generate complex UI structures.
+> - The demo uses the standard A2UI catalog. Custom catalog and inline catalog support are under
+>   development.
+
+## Roadmap
+
+AgentScope's main focus going forward will be on improving **How Agents Work** with A2UI. The
+workflow we're working towards is:
+
+```
+User Input → Agent Logic → LLM → A2UI JSON
+```
+
+Our optimization efforts will focus on:
+
+- **Agent Logic**: Improving how agents process inputs and orchestrate the generation of A2UI JSON
+  messages
+
+
+- **Handle user interactions from the client**: Enabling agents to properly process and respond to
+  user interactions from the client (such as button clicks, form submissions), treating them as new
+  user input to create a continuous interactive loop
+
+**Current approach**: The skill-based method we've implemented in this example is our first step
+towards this goal. By using AgentScope's skill system to progressively expose the A2UI schema and
+templates, agents can learn to generate compliant UI structures. Future improvements will focus on
+streamlining this process and making it more intuitive for developers to build A2UI-capable agents.
+
+**Next steps for Agent Logic improvement**
+
+- **Agent skills improvements**:
+  - Support flexible schema addition: Enable developers to easily add and customize schemas without
+    modifying core skill code
+  - Separate schema and examples into dedicated folders: Organize schema definitions and example
+    templates into distinct directories for better maintainability and clearer structure
+
+- **Context management in Memory for A2UI long context**:
+  - Currently, A2UI messages are extremely long, which makes multi-turn interactions inefficient
+    and degrades the quality of agent responses. We plan to implement better context management
+    strategies to handle these long-form messages and improve the quality of multi-turn conversations.
+
+- **Keep up with A2UI protocol updates**:
+  - We will follow A2UI protocol updates and make corresponding adjustments. For example, we plan to
+    support streaming UI JSON introduced in A2UI v0.9.
+

examples/agent/a2ui_agent/samples/agent/general_agent/__main__.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""Main entry point for running the restaurant finder A2UI server."""
+import logging
+import os
+import uvicorn
+from starlette.staticfiles import StaticFiles
+from setup_a2ui_server import app
+
+if __name__ == "__main__":
+    # Get the directory where this script is located
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    images_dir = os.path.join(script_dir, "images")
+
+    # Mount static files if images directory exists
+    if os.path.exists(images_dir):
+        app.mount("/static", StaticFiles(directory=images_dir), name="static")
+        logging.info(
+            "Mounted static files from %s at /static",
+            images_dir,
+        )
+    else:
+        logging.warning(
+            "Images directory not found at %s, "
+            "static files will not be served",
+            images_dir,
+        )
+
+    # Run the app manually with uvicorn
+    uvicorn.run(
+        app,
+        host="0.0.0.0",
+        port=10002,
+        log_level="info",
+        access_log=True,
+    )