Ferramentas de UI

O crate adk-ui permite que agentes de IA gerem dinamicamente interfaces de usuário ricas através de chamadas de ferramenta. Agentes podem renderizar formulários, cartões, alertas, tabelas, gráficos e muito mais - tudo através de um API Rust com segurança de tipo que serializa para JSON para consumo no frontend.

O Que Você Vai Construir

Conceitos Chave:

• Formulários - Coletam entrada do usuário com vários tipos de campo
• Cartões - Exibem informações com botões de ação
• Tabelas - Apresentam dados estruturados em linhas/colunas
• Gráficos - Visualizam dados com gráficos de barras, linhas, áreas, pizza
• Alertas - Exibem notificações e mensagens de status
• Modais - Diálogos de confirmação e interações focadas
• Toasts - Notificações de status breves
• Interoperabilidade de Protocolo - Emitem UI como payloads de A2UI, AG-UI ou MCP Apps

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 agents:

• Coletar entrada do usuário através de formulários dinâmicos com suporte a textarea
• Exibir informações com cards, alertas e notificações
• Apresentar dados em tabelas e gráficos interativos (Recharts)
• Mostrar progresso e estados de carregamento (spinner, skeleton)
• Criar layouts de dashboard com múltiplos componentes
• Solicitar confirmação do usuário via modais
• Exibir 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.0.0"
adk-model = "2.0.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-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)

Essas ferramentas emitem A2UI v0.9 JSONL 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 de múltiplas 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 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" />;
}

Ferramentas Disponíveis

render_form

Renderiza formulários interativos para coletar entrada 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

Exibe cartões de informação 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"}
  ]
}

Variantes de botão: primary, secondary, danger, ghost, outline

render_alert

Mostra notificações e mensagens de status.

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

Variantes: info, success, warning, error

render_confirm

Solicita 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

Exibe 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

Cria 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 da tarefa 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 notificações toast breves para atualizações de status.

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

Variantes: info, success, warning, error

Ferramentas Filtradas

Selecione apenas as ferramentas 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();

Lidando com Eventos de UI

Quando os usuários interagem com a UI 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 UI por Streaming

Para atualizações de UI em tempo real, use UiUpdate para aplicar patches em 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 suportam campos opcionais id para atualizações de streaming:

Átomos: Text, Button, Icon, Image, Badge Entradas: TextInput, NumberInput, Select, MultiSelect, Switch, DateInput, Slider, Textarea Layouts: Stack, Grid, Card, Container, Divider, Tabs Dados: Table, List, KeyValue, CodeBlock Visualização: Gráfico (barra, linha, área, pizza via Recharts) Feedback: Alert, Progress, Toast, Modal, Spinner, Skeleton

Cliente React

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

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

O cliente React inclui:

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

Arquitetura

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

Interoperabilidade de Protocolo

Todas as 13 ferramentas de renderização suportam saída ciente do protocolo através 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 protocolo:

• A2uiAdapter — Converte superfícies canônicas para A2UI JSONL
• AgUiAdapter — Converte para cargas úteis de evento AG-UI
• McpAppsAdapter — Converte para cargas úteis de recurso de MCP Apps

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

Cronograma de Descontinuação

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

Substituições: a2ui, ag_ui, mcp_apps

Esses metadados são expostos pelas constantes UI_PROTOCOL_CAPABILITIES e disponibilizados pelo adk-server em /api/ui/capabilities. A resposta de capacidades também informa implementationTier, specTrack, summary e limitations, permitindo que os clientes diferenciem subconjuntos híbridos ou de compatibilidade do suporte totalmente nativo ao protocolo.

Quando o adk-server é o limite voltado ao host, ele também expõe auxiliares adicionais da ponte MCP Apps 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 existentes do runtime ADK e aceitam corpos de solicitação diretos ou envelopes semelhantes a JSON-RPC com métodos ui/....

Para consumidores em tempo de execução, adk-server também suporta:

• x-adk-ui-transport: protocol_native ou uiTransport: "protocol_native" para serialização SSE nativa do AG-UI
• Entradas de requisição de caminho duplo AG-UI via input / agUiInput ao lado do newMessage existente
• Envelopes de ponte MCP Apps dentro de /api/run_sse via mcpAppsInitialize, mcpAppsRequest e mcpAppsInitialized

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

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

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

Prefira McpUiBridgeSnapshot::build_tool_result(...) ao promover o estado de bridge/sessão em uma resposta de ferramenta. Isso padroniza o formato do resultado da ferramenta enquanto preserva resourceUri e as alternativas inline html para hosts orientados à compatibilidade.

Para mapeamentos de host incorporados ou de navegador, a bridge 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

Endpoints diretos de bridge /api/ui/* são o caminho de ciclo de vida preferencial para hosts de MCP Apps. Campos de solicitação de MCP Apps do lado do runtime permanecem disponíveis como um caminho de compatibilidade aditivo para clientes mistos ou legados.

Exemplos

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

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

Prompts de Exemplo

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 de Navegador | Próximo: MCP Ferramentas →