Outils d'interface utilisateur

La crate adk-ui permet aux agents IA de générer dynamiquement des interfaces utilisateur riches via des appels d'outils. Les agents peuvent afficher des formulaires, des cartes, des alertes, des tableaux, des graphiques, et plus encore - le tout via une API Rust de type sûr qui se sérialise en JSON pour la consommation frontend.

Ce que vous allez construire

Concepts Clés :

• Formulaires - Recueillir les entrées utilisateur avec divers types de champs
• Cartes - Afficher des informations avec des boutons d'action
• Tableaux - Présenter des données structurées en lignes/colonnes
• Graphiques - Visualiser des données avec des diagrammes à barres, linéaires, en aires, circulaires
• Alertes - Afficher des notifications et des messages d'état
• Modales - Dialogues de confirmation et interactions ciblées
• Toasts - Brèves notifications d'état
• Interopérabilité de Protocole - Émettre l'interface utilisateur sous forme de charges utiles A2UI, AG-UI, ou MCP Apps

Exemple : Tableau de bord analytique

Exemple : Formulaire d'inscription

---

Comment ça marche

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

---

Aperçu

Les outils d'interface utilisateur permettent aux agents de :

• Collecter les entrées utilisateur via des formulaires dynamiques avec prise en charge des zones de texte
• Afficher des informations avec des cartes, des alertes et des notifications
• Présenter des données dans des tableaux et des graphiques interactifs (Recharts)
• Afficher la progression et les états de chargement (spinner, squelette)
• Créer des mises en page de tableau de bord avec plusieurs composants
• Demander la confirmation de l'utilisateur via des modales
• Afficher des notifications toast pour les mises à jour de statut

Démarrage rapide

Ajoutez à votre Cargo.toml :

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

Utilisation de base

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)

Ces outils émettent du A2UI v0.9 JSONL pour la compatibilité avec les moteurs de rendu A2UI.

render_screen (surface unique)

{
  "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 (page multi-sections)

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

Composants d'interface utilisateur 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"]
}

Utilisez le React renderer pour consommer 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" />;
}

Outils disponibles

Formulaire render_form

Affiche des formulaires interactifs pour recueillir les entrées de l'utilisateur.

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

Rendu :

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

Types de champs : text, email, password, number, date, select, multiselect, switch, slider, textarea

Carte render_card

Affiche des cartes d'information avec des boutons d'action optionnels.

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

Variantes de bouton : primary, secondary, danger, ghost, outline

Notification render_alert

Affiche des notifications et des messages d'état.

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

Variantes : info, success, warning, error

Confirmation render_confirm

Demande la confirmation de l'utilisateur avant les 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"
}

Tableau render_table

Affiche des données tabulaires.

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

Graphique render_chart

Crée des visualisations de données.

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

Types de graphiques: bar, line, area, pie

render_progress

Afficher la progression des tâches avec des étapes optionnelles.

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

Créer des mises en page de tableau de bord avec plusieurs 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"}]
    }
  ]
}

Types de sections: stats, table, chart, alert, text

render_modal

Afficher des boîtes de dialogue modales pour les confirmations ou les interactions ciblées.

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

Tailles: small, medium, large, full

render_toast

Afficher de brèves notifications toast pour les mises à jour de statut.

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

Variantes: info, success, warning, error

Outils filtrés

Sélectionnez uniquement les outils dont votre agent a besoin :

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

Gestion des événements d'interface utilisateur

Lorsque les utilisateurs interagissent avec l'interface utilisateur rendue (soumission de formulaires, clics sur des boutons), les événements sont renvoyés à l'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();

Mises à jour de l'interface utilisateur en continu

Pour les mises à jour d'interface utilisateur en temps réel, utilisez UiUpdate pour patcher les composants par 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()),
    })),
};

Opérations : Replace, Patch, Append, Remove

Schéma des Composants

Les 28 types de composants prennent en charge des champs optionnels id pour les mises à jour en streaming :

Atomes : Text, Button, Icon, Image, Badge Entrées : TextInput, NumberInput, Select, MultiSelect, Switch, DateInput, Slider, Textarea Dispositions : Stack, Grid, Card, Container, Divider, Tabs Données : Table, List, KeyValue, CodeBlock Visualisation : Chart (barres, lignes, aires, secteurs via Recharts) Retour d'information : Alert, Progress, Toast, Modal, Spinner, Skeleton

Client React

Une implémentation de référence React est fournie dans le dépôt autonome adk-ui :

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

Le client React inclut :

• TypeScript types correspondant au schéma Rust
• Rendu de composants pour les 28 types
• Intégration de Recharts pour les graphiques interactifs
• Prise en charge du rendu Markdown
• Prise en charge du mode sombre
• Gestion de la soumission de formulaires
• Composants modaux et de notification (toast)

Architecture

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

Interopérabilité des protocoles

Les 13 outils de rendu prennent en charge la sortie sensible au protocole via l'argument protocol :

Lorsque protocol est omis, les outils utilisent leur format de sortie par défaut (le format UiResponse JSON hérité pour la plupart des outils, A2UI pour render_screen/render_page/render_kit).

Exemple avec sélection de protocole :

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

Adaptateurs d'interopérabilité

adk-ui inclut des primitives d'adaptateur pour la conversion de protocole :

• A2uiAdapter — Convertit les surfaces canoniques en A2UI JSONL
• AgUiAdapter — Convertit en charges utiles d'événements AG-UI
• McpAppsAdapter — Convertit en charges utiles de ressources MCP Apps

Ceux-ci implémentent un trait UiProtocolAdapter partagé pour une conversion cohérente entre tous les outils.

Chronologie de dépréciation

Le profil d'exécution adk_ui hérité contient des métadonnées de dépréciation :

Remplacements : a2ui, ag_ui, mcp_apps

Ces métadonnées sont exposées par les constantes UI_PROTOCOL_CAPABILITIES et publiées par adk-server sur /api/ui/capabilities. La réponse de capacité fournit aussi implementationTier, specTrack, summary et limitations. Les clients peuvent ainsi distinguer les sous-ensembles hybrides ou compatibles d’une prise en charge entièrement native du protocole.

Lorsque adk-server constitue la frontière côté hôte, il expose également les points d’accès complémentaires du pont MCP Apps : /api/ui/initialize, /api/ui/message, /api/ui/update-model-context, /api/ui/notifications/poll, /api/ui/notifications/resources-list-changed et /api/ui/notifications/tools-list-changed. Ces points d’accès préservent les contrats d’exécution ADK existants et acceptent soit des corps de requête directs, soit des enveloppes proches de JSON-RPC avec des méthodes ui/....

Pour les consommateurs d'exécution, adk-server prend également en charge :

• x-adk-ui-transport: protocol_native ou uiTransport: "protocol_native" pour la sérialisation native AG-UI SSE
• les entrées de requête à double chemin AG-UI via input / agUiInput à côté de l'existant newMessage
• les enveloppes de pont MCP Apps à l'intérieur de /api/run_sse via mcpAppsInitialize, mcpAppsRequest et mcpAppsInitialized

Ces ajouts sont optionnels. Les consommateurs existants de /api/run et /api/run_sse continuent de recevoir l'enveloppe générique ADK à moins qu'ils ne demandent explicitement un mode de transport natif AG-UI.

Pour les réponses d'outils MCP Apps détenues par le framework, adk-server::ui_types expose désormais :

• McpUiBridgeSnapshot pour l'état de pont hôte/application typé
• McpUiToolResult pour l'enveloppe de réponse additive
• McpUiToolResultBridge pour les métadonnées de pont (protocolVersion, structuredContent, hostInfo, hostCapabilities, hostContext, appInfo, appCapabilities, initialized)

Privilégiez McpUiBridgeSnapshot::build_tool_result(...) lors de la promotion de l'état du pont/de la session dans une réponse d'outil. Cela standardise la forme du résultat de l'outil tout en préservant les resourceUri et les html de secours en ligne pour les hôtes orientés compatibilité.

Pour les mappages d'hôtes embarqués ou de navigateur, le pont additif HTTP correspond aux flux hôte/application comme suit :

• 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
• notifications d'hôte en file d'attente -> /api/ui/notifications/poll

Les points d'extrémité de pont directs /api/ui/* sont le chemin de cycle de vie préféré pour les hôtes d'applications MCP. Les champs de requête des applications MCP côté exécution restent disponibles comme chemin de compatibilité additif pour les clients mixtes ou hérités.

Exemples

Le dépôt autonome adk-ui contient les exemples d'interface utilisateur exécutables :

Exécutez ces exemples depuis le adk-ui dépôt afin que les paquets Rust et React restent sur la même ligne de version.

Exemples d'invites

Testez les outils d'interface utilisateur avec ces invites :

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

---

Précédent: ← Outils de navigateur | Suivant: MCP Outils →