UI-Tools

Das adk-ui crate ermöglicht KI-Agenten, dynamisch reichhaltige Benutzeroberflächen durch Tool-Aufrufe zu generieren. Agenten können Formulare, Karten, Warnungen, Tabellen, Diagramme und mehr rendern – alles über ein typsicheres Rust API, das zu JSON serialisiert wird für Frontend-Nutzung.

Was Sie erstellen werden

Schlüsselkonzepte:

• Formulare - Sammeln Sie Benutzereingaben mit verschiedenen Feldtypen
• Karten - Zeigen Sie Informationen mit Aktionsschaltflächen an
• Tabellen - Präsentieren Sie strukturierte Daten in Zeilen/Spalten
• Diagramme - Visualisieren Sie Daten mit Balken-, Linien-, Flächen- und Kreisdiagrammen
• Warnmeldungen - Benachrichtigungen und Statusmeldungen anzeigen
• Modale Dialoge - Bestätigungsdialoge und fokussierte Interaktionen
• Toasts - Kurze Statusbenachrichtigungen
• Protokoll-Interoperabilität - UI ausgeben als A2UI, AG-UI oder MCP Apps-Payloads

Beispiel: Analytics Dashboard

Beispiel: Registrierungsformular

---

So funktioniert's

┌─────────────────────────────────────────────────────────────────────────────┐
│ 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"                                                      │
│   })                                                                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

Übersicht

UI-Tools ermöglichen Agenten, Folgendes zu tun:

• Benutzereingaben über dynamische Formulare mit Unterstützung für Textfelder sammeln
• Informationen mit Karten, Warnungen und Benachrichtigungen anzeigen
• Daten in Tabellen und interaktiven Diagrammen (Recharts) präsentieren
• Fortschritts- und Ladezustände (Spinner, Skeleton) anzeigen
• Dashboard-Layouts mit mehreren Komponenten erstellen
• Benutzerbestätigung über Modals anfordern
• Toast-Benachrichtigungen für Statusaktualisierungen anzeigen

Schnellstart

Fügen Sie dies Ihrem Cargo.toml hinzu:

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

Grundlegende Verwendung

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)

Diese Tools emittieren A2UI v0.9 JSONL zur Kompatibilität mit A2UI Renderern.

render_screen (einzelne Oberfläche)

{
  "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 (mehrteilige Seite)

{
  "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 (Katalog + Token + Vorlagen)

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

Verwenden Sie den React-Renderer, um A2UI JSONL zu konsumieren:

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" />;
}

Verfügbare Tools

render_form

Interaktive Formulare rendern, um Benutzereingaben zu sammeln.

{
  "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"
}

Wird gerendert als:

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

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

render_card

Zeigt Informationskarten mit optionalen Aktionsschaltflächen an.

{
  "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"}
  ]
}

Schaltflächenvarianten: primary, secondary, danger, ghost, outline

render_alert

Benachrichtigungen und Statusmeldungen anzeigen.

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

Varianten: info, success, warning, error

render_confirm

Benutzerbestätigung vor Aktionen anfordern.

{
  "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

Tabellarische Daten anzeigen.

{
  "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

Datenvisualisierungen erstellen.

{
  "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}
  ]
}

Diagrammtypen: bar, line, area, pie

render_progress

Zeigt den Aufgabenfortschritt mit optionalen Schritten an.

{
  "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

Erstellt Dashboard-Layouts mit mehreren Abschnitten.

{
  "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"}]
    }
  ]
}

Abschnittstypen: stats, table, chart, alert, text

render_modal

Anzeige von modalen Dialogen für Bestätigungen oder fokussierte Interaktionen.

{
  "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"
}

Größen: small, medium, large, full

render_toast

Kurze Toast-Benachrichtigungen für Statusaktualisierungen anzeigen.

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

Varianten: info, success, warning, error

Gefilterte Tools

Wählen Sie nur die Tools aus, die Ihr Agent benötigt:

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();

Umgang mit UI-Ereignissen

Wenn Benutzer mit der gerenderten Benutzeroberfläche interagieren (Formulare absenden, Schaltflächen anklicken), werden Ereignisse an den Agenten zurückgesendet:

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

Für Echtzeit-UI-Updates verwenden Sie UiUpdate, um Komponenten anhand ihrer ID zu patchen:

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()),
    })),
};

Operationen: Replace, Patch, Append, Remove

Komponentenschema

Alle 28 Komponententypen unterstützen optionale id Felder für Streaming-Updates:

Atome: Text, Schaltfläche, Symbol, Bild, Abzeichen Eingaben: TextInput, NumberInput, Auswahl, MultiSelect, Schalter, DateInput, Schieberegler, Textbereich Layouts: Stapel, Raster, Karte, Container, Trennlinie, Registerkarten Daten: Tabelle, Liste, KeyValue, CodeBlock Visualisierung: Diagramm (Balken, Linie, Fläche, Kreis via Recharts) Feedback: Warnung, Fortschritt, Toast, Modales Fenster, Ladeanzeige, Skelett-Ladeanzeige

React-Client

Eine Referenzimplementierung für React wird im eigenständigen adk-ui Repository bereitgestellt:

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

Der React-Client beinhaltet:

• TypeScript Typen, die dem Rust-Schema entsprechen
• Komponenten-Renderer für alle 28 Typen
• Recharts-Integration für interaktive Diagramme
• Markdown-Rendering-Unterstützung
• Dark-Mode-Unterstützung
• Behandlung der Formularübermittlung
• Modal- und Toast-Komponenten

Architektur

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

Protokoll-Interoperabilität

Alle 13 Render-Tools unterstützen protokollbewusste Ausgabe über das protocol Argument:

Wenn protocol weggelassen wird, verwenden Tools ihr Standard-Ausgabeformat (Legacy UiResponse JSON für die meisten Tools, A2UI für render_screen/render_page/render_kit).

Beispiel mit Protokollauswahl:

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

Interop-Adapter

adk-ui enthält Adapter-Primitive für die Protokollkonvertierung:

• A2uiAdapter — Konvertiert kanonische Oberflächen in A2UI JSONL
• AgUiAdapter — Konvertiert in AG-UI-Ereignis-Payloads
• McpAppsAdapter — Konvertiert in MCP Apps-Ressourcen-Payloads

Diese implementieren ein gemeinsames UiProtocolAdapter trait für eine konsistente Konvertierung über alle Tools hinweg.

Zeitplan für die Veralterung

Das veraltete adk_ui runtime profile enthält Veralterungsmetadaten:

Ersatz: a2ui, ag_ui, mcp_apps

Diese Metadaten werden über UI_PROTOCOL_CAPABILITIES-Konstanten bereitgestellt und von adk-server unter /api/ui/capabilities ausgegeben. Die Fähigkeitsantwort meldet auch implementationTier, specTrack, summary und limitations, damit Clients hybride oder Kompatibilitäts-Teilmengen von vollständig nativer Protokollunterstützung unterscheiden können.

Wenn adk-server die hostseitige Grenze ist, stellt es auch zusätzliche MCP Apps-Brücken-Helfer unter /api/ui/initialize, /api/ui/message, /api/ui/update-model-context, /api/ui/notifications/poll, /api/ui/notifications/resources-list-changed und /api/ui/notifications/tools-list-changed bereit. Diese Endpunkte bewahren die bestehende ADK Laufzeit Verträge und akzeptieren entweder direkte Anforderungs-Bodies oder JSON-RPC-ähnliche Umschläge mit ui/... Methoden.

Für Laufzeit-Konsumenten unterstützt adk-server auch:

• x-adk-ui-transport: protocol_native oder uiTransport: "protocol_native" für AG-UI-native SSE Serialisierung
• AG-UI Dual-Pfad-Anfrageeingaben über input / agUiInput neben den bestehenden newMessage
• MCP Apps überbrücken Umschläge innerhalb /api/run_sse über mcpAppsInitialize, mcpAppsRequest und mcpAppsInitialized

Diese Ergänzungen sind Opt-in. Bestehende /api/run und /api/run_sse Konsumenten erhalten weiterhin den generischen ADK Wrapper, es sei denn, sie fordern explizit einen nativen AG-UI transport mode.

Für vom Framework verwaltete MCP Apps tool Antworten stellt adk-server::ui_types jetzt Folgendes bereit:

• McpUiBridgeSnapshot für den typisierten Host/App-Bridge-Zustand
• McpUiToolResult für den additiven Antwort-Umschlag
• McpUiToolResultBridge für bridge metadata (protocolVersion, structuredContent, hostInfo, hostCapabilities, hostContext, appInfo, appCapabilities, initialized)

Bevorzugen Sie McpUiBridgeSnapshot::build_tool_result(...), wenn der Bridge-/Sitzungszustand in eine Tool-Antwort überführt wird. Dies standardisiert die Form des Tool-Ergebnisses, während resourceUri und Inline-html Fallbacks für kompatibilitätsorientierte Hosts beibehalten werden.

Für eingebettete oder Browser-Host-Mappings entspricht die additive HTTP Brücke den Host/App-Flüssen wie folgt:

• 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
• Gewartete Host-Benachrichtigungen -> /api/ui/notifications/poll

Direkte /api/ui/* Bridge-Endpunkte sind der bevorzugte Lebenszykluspfad für MCP Apps-Hosts. Laufzeitseitige MCP Apps-Anfragefelder bleiben als ein zusätzlicher Kompatibilitätspfad für gemischte oder ältere Clients verfügbar.

Beispiele

Das eigenständige adk-ui Repo enthält die ausführbaren UI-Beispiele:

Führen Sie diese Beispiele aus dem adk-ui Repository aus, damit die Rust- und React-Pakete auf derselben Release-Linie bleiben.

Beispiel-Prompts

Testen Sie die UI-Tools mit diesen 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"

---

Zurück: ← Browser Tools | Weiter: MCP Tools →