Outils d’interface

La crate adk-ui permet aux agents IA de générer dynamiquement des interfaces utilisateur riches grâce à des appels d’outils. Les agents peuvent afficher des formulaires, des cartes, des alertes, des tableaux, des graphiques et bien plus encore — le tout via un API Rust à typage sûr, sérialisé en JSON pour être utilisé par le frontend.

Ce que vous allez construire

ADK Agent d’interface

Concepts clés :

Formulaires — Recueillir les saisies utilisateur avec différents types de champs
Cartes — Afficher des informations avec des boutons d’action
Tableaux — Présenter des données structurées en lignes et colonnes
Graphiques — Visualiser des données avec des graphiques à barres, linéaires, en aires et circulaires
Alertes — Afficher des notifications et des messages d’état
Modales — Afficher des boîtes de dialogue de confirmation et des interactions ciblées
Toasts — Afficher de brèves notifications d’état
Interopérabilité des protocoles — Émettre l’interface utilisateur sous forme de charges utiles A2UI, AG-UI ou MCP Apps

Exemple : Tableau de bord analytique

ADK Analytique d’interface

Exemple : Formulaire d’inscription

ADK Inscription d’interface

Fonctionnement

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

Vue d’ensemble

Les outils d’interface permettent aux agents de :

Recueillir les saisies utilisateur au moyen de formulaires dynamiques prenant en charge les 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 les états de progression et de chargement (indicateur de chargement, squelette)
Créer des mises en page de tableaux de bord avec plusieurs composants
Demander la confirmation de l’utilisateur via des modales
Afficher des notifications toast pour les mises à jour d’état

Démarrage rapide

Ajoutez à votre Cargo.toml :

[dependencies]
adk-ui = { git = "https://github.com/zavora-ai/adk-ui" }
adk-agent = "2.1.0"
adk-model = "2.1.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-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)

Ces outils émettent du JSONL A2UI v0.9 pour assurer 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 à plusieurs 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" }]
    }
  ]
}

render_kit (catalogue + jetons + modèles)

{
  "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 moteur de rendu React pour consommer le JSONL A2UI :

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

render_form

Affichez des formulaires interactifs pour recueillir les informations 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"
}

S’affiche comme suit :

┌─────────────────────────────────────────────────┐
│  📋 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

render_card

Affichez des cartes d’information avec des boutons d’action facultatifs.

{
  "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 boutons : primary, secondary, danger, ghost, outline

render_alert

Affichez 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

render_confirm

Demandez la confirmation de l’utilisateur avant d’effectuer des 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

Affichez des données sous forme de tableau.

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

Créez 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

Affichez la progression des tâches avec des étapes facultatives.

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

Affichez 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

Affichez de brèves notifications toast pour les mises à jour d’état.

{
  "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 de l’interface utilisateur

Lorsque les utilisateurs interagissent avec l’interface utilisateur affichée (soumettent des formulaires, cliquent 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 de l’interface utilisateur en temps réel, utilisez UiUpdate pour modifier 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 tous en charge les champs facultatifs id pour les mises à jour en flux continu :

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

Client React

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

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

Le client React comprend :

des types TypeScript correspondant au schéma Rust
un moteur de rendu des composants pour les 28 types
l’intégration de Recharts pour les graphiques interactifs
la prise en charge du rendu Markdown
la prise en charge du mode sombre
la gestion de l’envoi des formulaires
des composants de fenêtre modale 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 tous en charge une sortie compatible avec les protocoles via l’argument protocol :

Protocole	Description
`a2ui`	Interfaces JSONL alignées sur A2UI v0.9 (par défaut pour `render_screen`, `render_page`)
`ag_ui`	Prise en charge hybride d’AG-UI : wrappers de compatibilité par défaut, ainsi qu’un transport d’exécution natif du protocole et additif pour les clients `adk-server`
`mcp_apps`	Compatibilité des charges utiles des applications MCP avec les ressources `ui://`, assistants de pont additifs, flux de notifications, champs de requête d’exécution et adaptateurs HTML/de ressources

Lorsque protocol est omis, les outils utilisent leur format de sortie par défaut (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’adaptation pour la conversion de protocole :

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

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

Calendrier d’obsolescence

Le profil d’exécution adk_ui hérité contient des métadonnées d’obsolescence :

Date	Étape importante
2026-02-07	Dépréciation annoncée
2026-12-31	Date cible de fin de vie

Remplacements : a2ui, ag_ui, mcp_apps

Ces métadonnées sont exposées via les constantes UI_PROTOCOL_CAPABILITIES et présentées par adk-server à /api/ui/capabilities. La réponse de capacité fournit également implementationTier, specTrack, summary et limitations afin que les clients puissent distinguer les sous-ensembles hybrides ou de compatibilité d’une prise en charge entièrement native du protocole.

Lorsque adk-server constitue la limite exposée à l’hôte, il expose également les assistants supplémentaires du pont Apps MCP à /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 de terminaison préservent les contrats d’exécution ADK existants et acceptent soit des corps de requête directs, soit des enveloppes de type 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 de SSE
les entrées de requêtes AG-UI à double voie via input / agUiInput, en complément de newMessage existant
les enveloppes du pont Apps MCP dans /api/run_sse via mcpAppsInitialize, mcpAppsRequest et mcpAppsInitialized

Ces ajouts nécessitent une activation explicite. Les consommateurs existants de /api/run et /api/run_sse continuent de recevoir l’enveloppe générique ADK, sauf s’ils demandent explicitement un mode de transport AG-UI natif.

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

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

Privilégiez McpUiBridgeSnapshot::build_tool_result(...) lorsque vous intégrez l’état du pont ou de la session dans une réponse d’outil. Cela standardise la structure du résultat d’outil tout en préservant resourceUri et les solutions de repli html intégrées pour les hôtes privilégiant la compatibilité.

Pour les mappages intégrés ou hébergés par un 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 hôte mises en file d’attente -> /api/ui/notifications/poll

Les points de terminaison directs du pont /api/ui/* constituent le chemin de cycle de vie privilégié pour les hôtes Apps MCP. Les champs de requête Apps 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 :

Exemple	Description	Commande d’exécution
`ui_agent`	Démonstration de la console	`cargo run --bin ui_agent`
`ui_server`	Serveur avec HTTP et SSE	`cargo run --bin ui_server`
`ui_react_client`	interface front-end React	`cd ui_react_client && npm run dev`

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

Exemples de prompts

Testez les outils d’interface utilisateur avec ces 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"

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