UI Tools

The adk-ui crate enables AI agents to dynamically generate rich user interfaces through tool calls. Agents can render forms, cards, alerts, tables, charts, and more - all through a type-safe Rust API that serializes to JSON for frontend consumption.

What You'll Build

Key Concepts:

• Forms - Collect user input with various field types
• Cards - Display information with action buttons
• Tables - Present structured data in rows/columns
• Charts - Visualize data with bar, line, area, pie charts
• Alerts - Show notifications and status messages
• Modals - Confirmation dialogs and focused interactions
• Toasts - Brief status notifications
• Protocol Interop - Emit UI as A2UI, AG-UI, or MCP Apps payloads

Example: Analytics Dashboard

Example: Registration Form

---

How It Works

┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 1: User requests something                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   User: "I want to register for an account"                                 │
│                                                                             │
│                              ↓                                              │
│                                                                             │
│   ┌──────────────────────────────────────┐                                  │
│   │         AI AGENT (LLM)              │                                  │
│   │  "I should show a registration form" │                                  │
│   └──────────────────────────────────────┘                                  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 2: Agent calls render_form tool                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   📞 Tool Call: render_form({                                               │
│     title: "Registration",                                                  │
│     fields: [                                                               │
│       {name: "email", type: "email"},                                       │
│       {name: "password", type: "password"}                                  │
│     ]                                                                       │
│   })                                                                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 3: Frontend renders the form                                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌─────────────────────────────────────────────────┐                       │
│   │  📋 Registration                               │                       │
│   │  ────────────────────────────────────────────  │                       │
│   │  Email:    [________________________]          │                       │
│   │  Password: [________________________]          │                       │
│   │                                                │                       │
│   │  [           Register           ]              │                       │
│   └─────────────────────────────────────────────────┘                       │
│                                                                             │
│   ✅ User sees an interactive form, fills it out, clicks Register           │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ STEP 4: Form submission sent back to agent                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   📩 Event: {                                                               │
│     type: "form_submit",                                                    │
│     data: { email: "user@example.com", password: "***" }                    │
│   }                                                                         │
│                                                                             │
│   Agent: "Great! I'll process your registration and show a success alert"  │
│                                                                             │
│   📞 Tool Call: render_alert({                                              │
│     title: "Registration Complete!",                                        │
│     variant: "success"                                                      │
│   })                                                                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

Overview

UI tools allow agents to:

• Collect user input through dynamic forms with textarea support
• Display information with cards, alerts, and notifications
• Present data in tables and interactive charts (Recharts)
• Show progress and loading states (spinner, skeleton)
• Create dashboard layouts with multiple components
• Request user confirmation via modals
• Display toast notifications for status updates

Quick Start

Add to your Cargo.toml:

[dependencies]
adk-ui = { git = "https://github.com/zavora-ai/adk-ui" }
adk-agent = "2.0.0"
adk-model = "2.0.0"

Basic Usage

use adk_rust::prelude::*;
use adk_ui::UiToolset;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let model = Arc::new(GeminiModel::from_env("gemini-2.5-flash")?);

    // Get all 10 UI tools
    let ui_tools = UiToolset::all_tools();

    // Create AI agent with UI tools
    let mut builder = LlmAgentBuilder::new("ui_agent")
        .model(model)
        .instruction(r#"
            You are a helpful assistant that uses UI components to interact with users.
            Use render_form for collecting information.
            Use render_card for displaying results.
            Use render_alert for notifications.
            Use render_modal for confirmation dialogs.
            Use render_toast for brief status messages.
        "#);

    for tool in ui_tools {
        builder = builder.tool(tool);
    }

let agent = builder.build()?;
Ok(())
}

A2UI JSONL (render_screen / render_page / render_kit)

These tools emit A2UI v0.9 JSONL for compatibility with A2UI renderers.

render_screen (single surface)

{
  "surface_id": "main",
  "components": [
    { "id": "root", "component": "Column", "children": ["title", "cta"] },
    { "id": "title", "component": "Text", "text": "Welcome", "variant": "h1" },
    { "id": "cta_label", "component": "Text", "text": "Continue", "variant": "body" },
    { "id": "cta", "component": "Button", "child": "cta_label", "action": { "event": { "name": "continue" } } }
  ]
}

render_page (multi-section page)

{
  "title": "Release Notes",
  "description": "Highlights for the latest launch.",
  "sections": [
    {
      "heading": "What’s new",
      "body": "Three big improvements shipped this week.",
      "bullets": ["Faster onboarding", "Better search", "New dashboards"],
      "actions": [{ "label": "View details", "action": "view_details", "variant": "borderless" }]
    }
  ]
}

render_kit (catalog + tokens + templates)

{
  "name": "Fintech Pro",
  "version": "0.1.0",
  "brand": { "vibe": "trustworthy", "industry": "fintech" },
  "colors": { "primary": "#2F6BFF" },
  "typography": { "family": "Source Sans 3" },
  "templates": ["auth_login", "dashboard"]
}

Use the React renderer to consume A2UI JSONL:

import {
  A2uiStore,
  A2uiSurfaceRenderer,
  applyParsedMessages,
  parseJsonl,
} from "@zavora-ai/adk-ui-react";

const store = new A2uiStore();
const parsed = parseJsonl(jsonl);
applyParsedMessages(store, parsed);

export function App() {
  return <A2uiSurfaceRenderer store={store} surfaceId="main" />;
}

Available Tools

render_form

Render interactive forms to collect user input.

{
  "title": "Registration Form",
  "description": "Create your account",
  "fields": [
    {"name": "username", "label": "Username", "type": "text", "required": true},
    {"name": "email", "label": "Email", "type": "email", "required": true},
    {"name": "password", "label": "Password", "type": "password", "required": true},
    {"name": "newsletter", "label": "Subscribe to newsletter", "type": "switch"}
  ],
  "submit_label": "Register"
}

Renders as:

┌─────────────────────────────────────────────────┐
│  📋 Registration Form                          │
│  Create your account                           │
│  ─────────────────────────────────────────────  │
│                                                │
│  Username *                                    │
│  ┌─────────────────────────────────────────┐   │
│  │                                         │   │
│  └─────────────────────────────────────────┘   │
│                                                │
│  Email *                                       │
│  ┌─────────────────────────────────────────┐   │
│  │                                         │   │
│  └─────────────────────────────────────────┘   │
│                                                │
│  Password *                                    │
│  ┌─────────────────────────────────────────┐   │
│  │ ••••••••                                │   │
│  └─────────────────────────────────────────┘   │
│                                                │
│  Subscribe to newsletter  [○]                  │
│                                                │
│  ┌─────────────────────────────────────────┐   │
│  │             Register                    │   │
│  └─────────────────────────────────────────┘   │
│                                                │
└─────────────────────────────────────────────────┘

Field types: text, email, password, number, date, select, multiselect, switch, slider, textarea

render_card

Display information cards with optional action buttons.

{
  "title": "Order Confirmed",
  "description": "Order #12345",
  "content": "Your order has been placed successfully. Expected delivery: Dec 15, 2025.",
  "actions": [
    {"label": "Track Order", "action_id": "track", "variant": "primary"},
    {"label": "Cancel", "action_id": "cancel", "variant": "danger"}
  ]
}

Button variants: primary, secondary, danger, ghost, outline

render_alert

Show notifications and status messages.

{
  "title": "Payment Successful",
  "description": "Your payment of $99.00 has been processed.",
  "variant": "success"
}

Variants: info, success, warning, error

render_confirm

Request user confirmation before actions.

{
  "title": "Delete Account",
  "message": "Are you sure you want to delete your account? This action cannot be undone.",
  "confirm_label": "Delete",
  "cancel_label": "Keep Account",
  "variant": "danger"
}

render_table

Display tabular data.

{
  "title": "Recent Orders",
  "columns": [
    {"header": "Order ID", "accessor_key": "id"},
    {"header": "Date", "accessor_key": "date"},
    {"header": "Amount", "accessor_key": "amount"},
    {"header": "Status", "accessor_key": "status"}
  ],
  "data": [
    {"id": "#12345", "date": "2025-12-10", "amount": "$99.00", "status": "Delivered"},
    {"id": "#12346", "date": "2025-12-11", "amount": "$149.00", "status": "Shipped"}
  ]
}

render_chart

Create data visualizations.

{
  "title": "Monthly Sales",
  "chart_type": "bar",
  "x_key": "month",
  "y_keys": ["revenue", "profit"],
  "data": [
    {"month": "Jan", "revenue": 4000, "profit": 2400},
    {"month": "Feb", "revenue": 3000, "profit": 1398},
    {"month": "Mar", "revenue": 5000, "profit": 3800}
  ]
}

Chart types: bar, line, area, pie

render_progress

Show task progress with optional steps.

{
  "title": "Installing Dependencies",
  "value": 65,
  "description": "Installing package 13 of 20...",
  "steps": [
    {"label": "Download", "completed": true},
    {"label": "Extract", "completed": true},
    {"label": "Install", "current": true},
    {"label": "Configure", "completed": false}
  ]
}

render_layout

Create dashboard layouts with multiple sections.

{
  "title": "System Status",
  "description": "Current system health overview",
  "sections": [
    {
      "title": "Services",
      "type": "stats",
      "stats": [
        {"label": "API Server", "value": "Healthy", "status": "operational"},
        {"label": "Database", "value": "Degraded", "status": "warning"},
        {"label": "Cache", "value": "Down", "status": "error"}
      ]
    },
    {
      "title": "Recent Errors",
      "type": "table",
      "columns": [{"header": "Time", "key": "time"}, {"header": "Error", "key": "error"}],
      "rows": [{"time": "10:30", "error": "Connection timeout"}]
    }
  ]
}

Section types: stats, table, chart, alert, text

render_modal

Display modal dialogs for confirmations or focused interactions.

{
  "title": "Confirm Deletion",
  "message": "Are you sure you want to delete this item? This action cannot be undone.",
  "size": "medium",
  "closable": true,
  "confirm_label": "Delete",
  "cancel_label": "Cancel",
  "confirm_action": "delete_confirmed"
}

Sizes: small, medium, large, full

render_toast

Show brief toast notifications for status updates.

{
  "message": "Settings saved successfully",
  "variant": "success",
  "duration": 5000,
  "dismissible": true
}

Variants: info, success, warning, error

Filtered Tools

Select only the tools your agent needs:

let toolset = UiToolset::new()
    .without_chart()      // Disable charts
    .without_table()      // Disable tables
    .without_progress()   // Disable progress
    .without_modal()      // Disable modals
    .without_toast();     // Disable toasts

// Or use forms only
let forms_only = UiToolset::forms_only();

Handling UI Events

When users interact with rendered UI (submit forms, click buttons), events are sent back to the agent:

use adk_ui::{UiEvent, UiEventType};

// UiEvent structure
pub struct UiEvent {
    pub event_type: UiEventType,  // FormSubmit, ButtonClick, InputChange
    pub action_id: Option<String>,
    pub data: Option<HashMap<String, Value>>,
}

// Convert to message for agent
let message = ui_event.to_message();

Streaming UI Updates

For real-time UI updates, use UiUpdate to patch components by ID:

use adk_ui::{UiUpdate, UiOperation};

let update = UiUpdate {
    target_id: "progress-bar".to_string(),
    operation: UiOperation::Patch,
    payload: Some(Component::Progress(Progress {
        id: Some("progress-bar".to_string()),
        value: 75,
        label: Some("75%".to_string()),
    })),
};

Operations: Replace, Patch, Append, Remove

Component Schema

All 28 component types support optional id fields for streaming updates:

Atoms: Text, Button, Icon, Image, Badge Inputs: TextInput, NumberInput, Select, MultiSelect, Switch, DateInput, Slider, Textarea Layouts: Stack, Grid, Card, Container, Divider, Tabs Data: Table, List, KeyValue, CodeBlock Visualization: Chart (bar, line, area, pie via Recharts) Feedback: Alert, Progress, Toast, Modal, Spinner, Skeleton

React Client

A reference React implementation is provided in the standalone adk-ui repository:

npm install @zavora-ai/adk-ui-react

The React client includes:

• TypeScript types matching the Rust schema
• Component renderer for all 28 types
• Recharts integration for interactive charts
• Markdown rendering support
• Dark mode support
• Form submission handling
• Modal and toast components

Architecture

Agent ──[render_* tool]──> UiResponse (JSON)
                              │
                              │ SSE
                              ▼
                         Client (React)
                              │
                              └──> UiEvent (user action) ──> Agent

Protocol Interop

All 13 render tools support protocol-aware output through the protocol argument:

When protocol is omitted, tools use their default output format (legacy UiResponse JSON for most tools, A2UI for render_screen/render_page/render_kit).

Example with protocol selection:

{
  "protocol": "mcp_apps",
  "mcp_apps": {
    "resource_uri": "ui://demo/surface"
  }
}

Interop Adapters

adk-ui includes adapter primitives for protocol conversion:

• A2uiAdapter — Converts canonical surfaces to A2UI JSONL
• AgUiAdapter — Converts to AG-UI event payloads
• McpAppsAdapter — Converts to MCP Apps resource payloads

These implement a shared UiProtocolAdapter trait for consistent conversion across all tools.

Deprecation Timeline

The legacy adk_ui runtime profile carries deprecation metadata:

Replacements: a2ui, ag_ui, mcp_apps

This metadata is exposed through UI_PROTOCOL_CAPABILITIES constants and surfaced by adk-server at /api/ui/capabilities. The capability response also reports implementationTier, specTrack, summary, and limitations so clients can distinguish hybrid or compatibility subsets from fully native protocol support.

When adk-server is the host-facing boundary, it also exposes additive MCP Apps bridge helpers at /api/ui/initialize, /api/ui/message, /api/ui/update-model-context, /api/ui/notifications/poll, /api/ui/notifications/resources-list-changed, and /api/ui/notifications/tools-list-changed. These endpoints preserve the existing ADK runtime contracts and accept either direct request bodies or JSON-RPC-like envelopes with ui/... methods.

For runtime consumers, adk-server also supports:

• x-adk-ui-transport: protocol_native or uiTransport: "protocol_native" for AG-UI-native SSE serialization
• AG-UI dual-path request inputs via input / agUiInput beside the existing newMessage
• MCP Apps bridge envelopes inside /api/run_sse via mcpAppsInitialize, mcpAppsRequest, and mcpAppsInitialized

These additions are opt-in. Existing /api/run and /api/run_sse consumers continue to receive the generic ADK wrapper unless they explicitly request a native AG-UI transport mode.

For framework-owned MCP Apps tool responses, adk-server::ui_types now exposes:

• McpUiBridgeSnapshot for typed host/app bridge state
• McpUiToolResult for the additive response envelope
• McpUiToolResultBridge for bridge metadata (protocolVersion, structuredContent, hostInfo, hostCapabilities, hostContext, appInfo, appCapabilities, initialized)

Prefer McpUiBridgeSnapshot::build_tool_result(...) when promoting bridge/session state into a tool response. This standardizes the tool-result shape while preserving resourceUri and inline html fallbacks for compatibility-oriented hosts.

For embedded or browser-host mappings, the additive HTTP bridge corresponds to host/app flows as follows:

• ui/initialize -> /api/ui/initialize
• ui/message -> /api/ui/message
• ui/update-model-context -> /api/ui/update-model-context
• notifications/resources/list_changed -> /api/ui/notifications/resources-list-changed
• notifications/tools/list_changed -> /api/ui/notifications/tools-list-changed
• queued host notifications -> /api/ui/notifications/poll

Direct /api/ui/* bridge endpoints are the preferred lifecycle path for MCP Apps hosts. Runtime-side MCP Apps request fields remain available as an additive compatibility path for mixed or legacy clients.

Examples

The standalone adk-ui repo contains the runnable UI examples:

Run those examples from the adk-ui repository so the Rust and React packages stay on the same release line.

Sample Prompts

Test the UI tools with these prompts:

# Forms
"I want to register for an account"
"Create a contact form"
"Create a feedback form with a comments textarea"

# Cards
"Show me my profile"
"Display a product card for a laptop"

# Alerts
"Show a success message"
"Display a warning about expiring session"

# Modals
"I want to delete my account" (shows confirmation modal)
"Show a confirmation dialog before submitting"

# Toasts
"Show a success toast notification"
"Display an error toast"

# Tables
"Show my recent orders"
"List all users"

# Charts
"Show monthly sales chart"
"Display traffic trends as a line chart"
"Show revenue breakdown as a pie chart"

# Progress & Loading
"Show upload progress at 75%"
"Display a loading spinner"
"Show skeleton loading state"

# Dashboards
"Show system status dashboard"

---

Previous: ← Browser Tools | Next: MCP Tools →