Ship Your First Agentic UI in 5 Minutes

The Goal: Don’t just build a chatbot. Build an app that talks. In this guide, we’ll transform a standard React component into an AI-controlled interface.

What we’re building

A Restaurant Finder Agent that doesn’t just tell you about sushi places, but shows you interactive cards with ratings and photos.

Prerequisites

• Node.js 18+
• An API Key (OpenAI, Anthropic, or Google Gemini)

1. Install the SDK

A2UI is lightweight and strictly typed. Install the core library for your framework (React in this example).

npm install @a2ui/react @a2ui/core

2. Bring Your Own Component

The best part about A2UI? You don’t need to learn a new UI library. Just use your existing React components.

Let’s say you have a RestaurantCard:

// components/RestaurantCard.tsx
export const RestaurantCard = ({ name, rating, cuisine }) => (
  <div className="p-4 border rounded shadow-sm bg-white hover:shadow-md transition-shadow">
    <h3 className="text-lg font-bold">{name}</h3>
    <p className="text-gray-600">{cuisine} • {rating} ⭐</p>
  </div>
);

3. Create the Registry (The “Firewall”)

This is the most important step for Security. The Registry acts as an allowlist. It tells A2UI: “These are the ONLY components the AI is allowed to render.” This prevents the AI from hallucinating UI or injecting malicious code.

// registry.ts
import { createRegistry } from '@a2ui/react';
import { RestaurantCard } from './components/RestaurantCard';

export const myRegistry = createRegistry({
  components: {
    // Map the JSON tag 'restaurant-card' -> Your React Component
    'restaurant-card': RestaurantCard,
  },
});

4. Render the Agent’s “Thinking”

When your agent returns JSON, simply feed it into the AIOutput component. It handles the parsing, streaming, and error handling for you.

// App.tsx
import { AIOutput } from '@a2ui/react';
import { myRegistry } from './registry';

// Simulating what the LLM sends back
const agentResponse = {
  type: 'restaurant-card',
  data: {
    name: 'Sushi Palace',
    rating: 4.8,
    cuisine: 'Japanese'
  }
};

export default function App() {
  return (
    <div className="max-w-md mx-auto mt-10">
        <AIOutput 
          registry={myRegistry} 
          data={agentResponse} 
        />
    </div>
  );
}

5. Teach the AI to “Speak UI”

Finally, you need to tell your LLM (GPT-4, Claude, etc.) how to use your new tool. This is done via the System Prompt.

SYSTEM:
You are a helpful food assistant.
When suggesting restaurants, DO NOT use markdown or plain text.
Instead, use the 'restaurant-card' tool content.

Output Format (JSON):
{
  "name": string, // Name of the restaurant
  "rating": number, // 0-5 stars
  "cuisine": string // e.g. "Italian", "Japanese"
}

Why this works: The LLM treats your UI component just like a function call or a tool. It generates the JSON, and A2UI renders the pixels.

Next Steps

Running the Official Demo

The best way to understand the architecture of A2UI is to run the official Restaurant Finder sample provided in the google/A2UI repository.

Prerequisites

• Node.js (for web clients)
• Python uv (for agent backend)
• A valid Gemini API Key

1. Clone & Setup

git clone https://github.com/google/A2UI.git
cd A2UI
export GEMINI_API_KEY="your_gemini_api_key"

2. Run the Agent Backend

Starts the specific Restaurant Finder intelligence agent on Python using uv.

cd samples/agent/adk/restaurant_finder
uv run .

3. Run the Client Shell

Open a new terminal to start the Web/Lit rendering shell environment:

cd renderers/markdown/markdown-it && npm install && npm run build
cd ../../web_core && npm install && npm run build
cd ../lit && npm install && npm run build
cd ../../samples/client/lit/shell && npm install && npm run dev