UI-Werkzeuge

Die adk-ui-Crate ermöglicht es KI-Agenten, über Tool-Aufrufe dynamisch umfangreiche Benutzeroberflächen zu erzeugen. Agenten können Formulare, Karten, Warnungen, Tabellen, Diagramme und mehr rendern – alles über eine typsichere Rust-API, die für die Nutzung im Frontend in JSON serialisiert wird.

Was Sie erstellen werden

ADK-UI-Agent

Wichtige Konzepte:

Formulare – Benutzereingaben mit verschiedenen Feldtypen erfassen
Karten – Informationen mit Aktionsschaltflächen anzeigen
Tabellen – Strukturierte Daten in Zeilen und Spalten darstellen
Diagramme – Daten mit Balken-, Linien-, Flächen- und Kreisdiagrammen visualisieren
Warnungen – Benachrichtigungen und Statusmeldungen anzeigen
Modale Dialoge – Bestätigungsdialoge und fokussierte Interaktionen
Toasts – Kurze Statusbenachrichtigungen
Protokollinteroperabilität – UI als A2UI-, AG-UI- oder MCP-Apps-Payloads ausgeben

Beispiel: Analyse-Dashboard

ADK-UI-Analyse

Beispiel: Registrierungsformular

ADK-UI-Registrierung

Funktionsweise

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

Überblick

UI-Werkzeuge ermöglichen Agenten:

Benutzereingaben über dynamische Formulare mit Unterstützung für Textbereiche zu erfassen
Informationen mit Karten, Warnungen und Benachrichtigungen anzuzeigen
Daten in Tabellen und interaktiven Diagrammen (Recharts) darzustellen
Fortschritts- und Ladezustände anzuzeigen (Spinner, Skeleton)
Dashboard-Layouts mit mehreren Komponenten zu erstellen
Über modale Dialoge eine Benutzerbestätigung anzufordern
Toast-Benachrichtigungen für Statusaktualisierungen anzuzeigen

Schnellstart

Fügen Sie Folgendes zu Ihrer Cargo.toml hinzu:

[dependencies]
adk-ui = { git = "https://github.com/zavora-ai/adk-ui" }
adk-agent = "2.1.0"
adk-model = "2.1.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-3.7-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 Werkzeuge geben A2UI v0.9 JSONL zur Kompatibilität mit A2UI-Renderern aus.

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 (Seite mit mehreren Abschnitten)

{
  "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 + Tokens + 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 verarbeiten:

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

Rendern Sie interaktive Formulare, um Benutzereingaben zu erfassen.

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

Zeigen Sie 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

Zeigen Sie Benachrichtigungen und Statusmeldungen an.

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

Varianten: info, success, warning, error

render_confirm

Fordern Sie vor Aktionen eine Bestätigung des Benutzers an.

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

Zeigen Sie tabellarische Daten an.

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

Erstellen Sie Datenvisualisierungen.

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

Zeigen Sie 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

Erstellen Sie 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

Zeigen Sie modale Dialoge für Bestätigungen oder fokussierte Interaktionen an.

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

Zeigen Sie kurze Toast-Benachrichtigungen für Statusaktualisierungen an.

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

Verarbeiten von UI-Ereignissen

Wenn Benutzer mit der gerenderten UI interagieren (Formulare absenden, Schaltflächen anklicken), werden Ereignisse an den Agent gesendet:

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 von UI-Aktualisierungen

Für UI-Aktualisierungen in Echtzeit verwenden Sie UiUpdate, um Komponenten nach 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-Aktualisierungen:

Atome: Text, Button, Icon, Image, Badge Eingaben: TextInput, NumberInput, Select, MultiSelect, Switch, DateInput, Slider, Textarea Layouts: Stack, Grid, Card, Container, Divider, Tabs Daten: Table, List, KeyValue, CodeBlock Visualisierung: Chart (Balken, Linien, Fläche, Kreis über Recharts) Rückmeldung: Alert, Progress, Toast, Modal, Spinner, Skeleton

React-Client

Eine Referenzimplementierung in React wird im eigenständigen Repository adk-ui bereitgestellt:

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

Der React-Client umfasst:

TypeScript-Typen, die dem Rust-Schema entsprechen
Komponenten-Renderer für alle 28 Typen
Recharts-Integration für interaktive Diagramme
Unterstützung für Markdown-Rendering
Unterstützung des Dunkelmodus
Verarbeitung von Formularübermittlungen
Modal- und Toast-Komponenten

Architektur

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

Protokollinteroperabilität

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

Protokoll	Beschreibung
`a2ui`	A2UI-an JSONL-Schnittstellen v0.9 (Standard für `render_screen`, `render_page`)
`ag_ui`	Hybride AG-UI-Unterstützung: standardmäßig Kompatibilitäts-Wrapper sowie ein zusätzlicher protokollnativer Laufzeittransport für `adk-server`-Clients
`mcp_apps`	Kompatibilität von MCP-Apps-Nutzlasten mit `ui://`-Ressourcen, additive Bridge-Hilfsfunktionen, Benachrichtigungsabläufe, Laufzeitanforderungsfelder und HTML/Ressourcenadapter

Wenn protocol weggelassen wird, verwenden Tools ihr standardmäßiges Ausgabeformat (das ältere 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"
  }
}

Interoperabilitäts-Adapter

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

A2uiAdapter — Konvertiert kanonische Oberflächen in A2UI JSONL
AgUiAdapter — Konvertiert in AG-UI-Ereignisnutzdaten
McpAppsAdapter — Konvertiert in MCP-Apps-Ressourcennutzdaten

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

Zeitplan für die Einstellung

Das Legacy-adk_ui-Laufzeitprofil enthält Metadaten zur Einstellung:

Datum	Meilenstein
2026-02-07	Einstellung angekündigt
2026-12-31	Zieltermin für die Abschaltung

Ersetzungen: a2ui, ag_ui, mcp_apps

Diese Metadaten werden über die Konstanten UI_PROTOCOL_CAPABILITIES bereitgestellt und von adk-server unter /api/ui/capabilities angezeigt.
Die Capability-Antwort meldet außerdem implementationTier, specTrack, summary und limitations, sodass Clients hybride oder kompatible Teilmengen von vollständig nativer Protokollunterstützung unterscheiden können.

Wenn adk-server die hostseitige Grenze bildet, stellt es außerdem additive MCP-Apps-Bridge-Hilfsfunktionen 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 bestehenden ADK-Laufzeitverträge und akzeptieren entweder direkte Request-Bodies oder JSON-RPC-ähnliche Umschläge mit ui/...-Methoden.

Für Laufzeitkonsumenten unterstützt adk-server außerdem:

x-adk-ui-transport: protocol_native oder uiTransport: "protocol_native" für die native SSE-Serialisierung von AG-UI
Dual-Path-Request-Eingaben von AG-UI über input / agUiInput neben dem bestehenden newMessage
MCP-Apps-Bridge-Umschläge innerhalb von /api/run_sse über mcpAppsInitialize, mcpAppsRequest und mcpAppsInitialized

Diese Ergänzungen sind optional. Bestehende Konsumenten von /api/run und /api/run_sse erhalten weiterhin den generischen ADK-Wrapper, sofern sie nicht ausdrücklich einen nativen AG-UI-Transportmodus anfordern.

Für framework-eigene MCP-Apps-Tool-Antworten stellt adk-server::ui_types nun Folgendes bereit:

McpUiBridgeSnapshot für typisierten Host-/App-Bridge-Status
McpUiToolResult für den additiven Antwortumschlag
McpUiToolResultBridge für Bridge-Metadaten (protocolVersion, structuredContent, hostInfo, hostCapabilities, hostContext, appInfo, appCapabilities, initialized)

Verwenden Sie McpUiBridgeSnapshot::build_tool_result(...) bevorzugt, wenn Bridge-/Session-Status in eine Tool-Antwort übernommen wird. Dadurch wird die Form des Tool-Ergebnisses standardisiert, während resourceUri und Inline-html-Fallbacks für kompatibilitätsorientierte Hosts erhalten bleiben.

Für Zuordnungen zwischen eingebetteten und Browser-Hosts entspricht die additive HTTP-Bridge den Host-/App-Abläufen 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
Wartende Host-Benachrichtigungen -> /api/ui/notifications/poll

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

Beispiele

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

Beispiel	Beschreibung	Ausführungsbefehl
`ui_agent`	Konsolendemo	`cargo run --bin ui_agent`
`ui_server`	HTTP-Server mit SSE	`cargo run --bin ui_server`
`ui_react_client`	React-Frontend	`cd ui_react_client && npm run dev`

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

Beispielaufforderungen

Testen Sie die UI-Tools mit diesen Aufforderungen:

# 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: Tools von MCP →