Ferramentas de UI

O crate adk-ui permite que agentes de IA gerem dinamicamente interfaces de usuário avançadas por meio de chamadas de ferramentas. Os agentes podem renderizar formulários, cartões, alertas, tabelas, gráficos e muito mais — tudo por meio de uma API Rust com segurança de tipos que serializa para JSON para consumo no frontend.

O que você criará

Conceitos principais:

• Formulários — Coletar dados do usuário com vários tipos de campos
• Cartões — Exibir informações com botões de ação
• Tabelas — Apresentar dados estruturados em linhas/colunas
• Gráficos — Visualizar dados com gráficos de barras, linhas, áreas e pizza
• Alertas — Exibir notificações e mensagens de status
• Modais — Diálogos de confirmação e interações focadas
• Toasts — Breves notificações de status
• Interoperabilidade de protocolo — Emitir a UI como payloads de A2UI, AG-UI ou Apps MCP

Exemplo: Painel de análise

Exemplo: Formulário de registro

---

Como funciona

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

---

Visão geral

As ferramentas de UI permitem que os agentes:

• Coletem dados do usuário por meio de formulários dinâmicos com suporte a áreas de texto
• Exibam informações com cartões, alertas e notificações
• Apresentem dados em tabelas e gráficos interativos (Recharts)
• Mostrem estados de progresso e carregamento (indicador giratório, esqueleto)
• Criem layouts de painéis com vários componentes
• Solicitem a confirmação do usuário por meio de modais
• Exibam notificações toast para atualizações de status

Início rápido

Adicione ao seu Cargo.toml:

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

Uso básico

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

JSONL A2UI (render_screen / render_page / render_kit)

Essas ferramentas emitem JSONL A2UI v0.9 para compatibilidade com renderizadores A2UI.

render_screen (superfície única)

{
  "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 (página com várias seções)

{
  "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 (catálogo + tokens + modelos)

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

Use o renderizador React para consumir JSONL de 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" />;
}

Ferramentas disponíveis

render_form

Renderize formulários interativos para coletar dados do usuário.

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

Renderiza como:

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

Tipos de campo: text, email, password, number, date, select, multiselect, switch, slider, textarea

render_card

Exiba cartões de informações com botões de ação opcionais.

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

Variações de botão: primary, secondary, danger, ghost, outline

render_alert

Mostre notificações e mensagens de status.

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

Variações: info, success, warning, error

render_confirm

Solicite a confirmação do usuário antes das ações.

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

Exiba dados tabulares.

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

Crie visualizações de dados.

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

Tipos de gráfico: bar, line, area, pie

render_progress

Mostre o progresso das tarefas com etapas opcionais.

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

Crie layouts de painel com várias seções.

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

Tipos de seção: stats, table, chart, alert, text

render_modal

Exiba diálogos modais para confirmações ou interações focadas.

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

Tamanhos: small, medium, large, full

render_toast

Mostre breves notificações toast para atualizações de status.

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

Variações: info, success, warning, error

Ferramentas filtradas

Selecione apenas as ferramentas de que seu agente precisa:

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

Tratamento de eventos da interface

Quando os usuários interagem com a interface renderizada (enviam formulários, clicam em botões), os eventos são enviados de volta ao agente:

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

Atualizações de interface em streaming

Para atualizações da UI em tempo real, use UiUpdate para aplicar patches aos componentes por 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()),
    })),
};

Operações: Replace, Patch, Append, Remove

Esquema de componentes

Todos os 28 tipos de componentes são compatíveis com campos id opcionais para atualizações em streaming:

Átomos: Texto, Botão, Ícone, Imagem, Distintivo Entradas: TextInput, NumberInput, Seleção, MultiSelect, Alternância, DateInput, Controle deslizante, Área de texto Layouts: Pilha, Grade, Cartão, Contêiner, Divisor, Abas Dados: Tabela, Lista, KeyValue, CodeBlock Visualização: Gráfico (barras, linhas, área, pizza via Recharts) Feedback: Alerta, Progresso, Notificação, Modal, Indicador de carregamento, Esqueleto

Cliente React

Uma implementação de referência em React é fornecida no repositório independente adk-ui:

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

O cliente React inclui:

• Tipos TypeScript correspondentes ao esquema Rust
• Renderizador de componentes para todos os 28 tipos
• Integração com Recharts para gráficos interativos
• Suporte à renderização de Markdown
• Suporte ao modo escuro
• Tratamento do envio de formulários
• Componentes de modal e notificação

Arquitetura

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

Interoperabilidade de protocolo

Todas as 13 ferramentas de renderização são compatíveis com saída ciente do protocolo por meio do argumento protocol:

Quando protocol é omitido, as ferramentas usam seu formato de saída padrão (UiResponse JSON legado para a maioria das ferramentas, A2UI para render_screen/render_page/render_kit).

Exemplo com seleção de protocolo:

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

Adaptadores de interoperabilidade

adk-ui inclui primitivas de adaptador para conversão de protocolos:

• A2uiAdapter — Converte superfícies canônicas para JSONL A2UI
• AgUiAdapter — Converte para cargas de eventos AG-UI
• McpAppsAdapter — Converte para cargas de recursos de Apps MCP

Eles implementam um trait UiProtocolAdapter compartilhado para conversão consistente em todas as ferramentas.

Linha do tempo de descontinuação

O perfil de runtime adk_ui legado contém metadados de descontinuação:

Substituições: a2ui, ag_ui, mcp_apps

Esses metadados são expostos por meio das constantes UI_PROTOCOL_CAPABILITIES e disponibilizados por adk-server em /api/ui/capabilities.
A resposta de capacidade também relata implementationTier, specTrack, summary e limitations, para que os clientes possam distinguir subconjuntos híbridos ou de compatibilidade do suporte totalmente nativo ao protocolo.

Quando adk-server é o limite voltado ao host, ele também expõe helpers aditivos da ponte de Apps MCP em /api/ui/initialize, /api/ui/message, /api/ui/update-model-context, /api/ui/notifications/poll, /api/ui/notifications/resources-list-changed e /api/ui/notifications/tools-list-changed. Esses endpoints preservam os contratos de runtime existentes de ADK e aceitam tanto corpos de solicitação diretos quanto envelopes semelhantes a JSON-RPC com métodos ui/....

Para consumidores de runtime, adk-server também oferece suporte a:

• x-adk-ui-transport: protocol_native ou uiTransport: "protocol_native" para serialização SSE nativa do AG-UI
• Entradas de solicitação de caminho duplo do AG-UI por meio de input / agUiInput, além do newMessage existente
• Envelopes da ponte de Apps MCP dentro de /api/run_sse por meio de mcpAppsInitialize, mcpAppsRequest e mcpAppsInitialized

Essas adições são opcionais. Os consumidores existentes de /api/run e /api/run_sse continuam recebendo o wrapper genérico ADK, a menos que solicitem explicitamente um modo de transporte nativo do AG-UI.

Para respostas de ferramentas do Apps MCP pertencentes ao framework, adk-server::ui_types agora expõe:

• McpUiBridgeSnapshot para o estado tipado da ponte entre host e app
• McpUiToolResult para o envelope de resposta aditivo
• McpUiToolResultBridge para metadados da ponte (protocolVersion, structuredContent, hostInfo, hostCapabilities, hostContext, appInfo, appCapabilities, initialized)

Prefira McpUiBridgeSnapshot::build_tool_result(...) ao promover o estado da ponte/sessão para uma resposta de ferramenta. Isso padroniza o formato do resultado da ferramenta, preservando resourceUri e os fallbacks html inline para hosts orientados à compatibilidade.

Para mapeamentos incorporados ou de navegador, a ponte aditiva HTTP corresponde aos fluxos de host/aplicativo da seguinte forma:

• 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
• notificações de host enfileiradas -> /api/ui/notifications/poll

Os endpoints diretos da ponte /api/ui/* são o caminho preferencial do ciclo de vida para hosts de Apps MCP. Os campos de solicitação de Apps MCP do lado do runtime continuam disponíveis como um caminho de compatibilidade aditivo para clientes mistos ou legados.

Exemplos

O repositório independente adk-ui contém os exemplos de UI executáveis:

Execute esses exemplos do repositório adk-ui para que os pacotes Rust e React permaneçam na mesma linha de lançamento.

Exemplos de prompts

Teste as ferramentas de UI com estes 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"

---

Anterior: ← Ferramentas do navegador | Próximo: Ferramentas MCP →