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 uma API Rust type-safe que serializa para JSON para consumo no frontend.
O Que Você Irá 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
- Modals - Diálogos de confirmação e interações focadas
- Toasts - Notificações de status breves
Exemplo: Painel de Análise
Exemplo: Formulário de Registro
Como Funciona
┌─────────────────────────────────────────────────────────────────────────────┐
│ PASSO 1: Usuário solicita algo │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Usuário: "Eu quero criar uma conta" │
│ │
│ ↓ │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ AGENTE DE IA (LLM) │ │
│ │ "Devo exibir um formulário de cadastro" │ │
│ └──────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ PASSO 2: Agent chama a ferramenta render_form │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 📞 Chamada de Ferramenta: render_form({ │
│ title: "Cadastro", │
│ fields: [ │
│ {name: "email", type: "email"}, │
│ {name: "password", type: "password"} │
│ ] │
│ }) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ PASSO 3: Frontend renderiza o formulário │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 📋 Cadastro │ │
│ │ ──────────────────────────────────────────── │ │
│ │ Email: [________________________] │ │
│ │ Senha: [________________________] │ │
│ │ │ │
│ │ [ Cadastrar ] │ │
│ └─────────────────────────────────────────────────┘ │
│ │
│ ✅ Usuário vê um formulário interativo, preenche-o e clica em Cadastrar │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ PASSO 4: Envio do formulário é enviado de volta ao agent │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 📩 Evento: { │
│ type: "form_submit", │
│ data: { email: "user@example.com", password: "***" } │
│ } │
│ │
│ Agent: "Ótimo! Vou processar seu cadastro e exibir um alerta de sucesso" │
│ │
│ 📞 Chamada de Ferramenta: render_alert({ │
│ title: "Cadastro Concluído!", │
│ variant: "success" │
│ }) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Visão Geral
As ferramentas de interface de usuário (UI) permitem que os agents:
- Coletem entrada do usuário através de formulários dinâmicos com suporte a textarea
- Exibam informações com cards, alertas e notificações
- Apresentem dados em tabelas e gráficos interativos (Recharts)
- Mostrem progresso e estados de carregamento (spinner, skeleton)
- Criem layouts de dashboard com múltiplos componentes
- Solicitem confirmação do usuário via modais
- Exibam notificações toast para atualizações de status
Início Rápido
Adicione ao seu Cargo.toml:
[dependencies]
adk-rust = { version = "0.2.0", features = ["ui"] }
# Ou use crates individuais:
adk-ui = "0.2.0"
adk-agent = "0.2.0"
adk-model = "0.2.0"Uso Básico
use adk_rust::prelude::*;
use adk_rust::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.0-flash")?);
// Obtém todas as 10 ferramentas de UI
let ui_tools = UiToolset::all_tools();
// Cria um agente de IA com ferramentas de UI
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(())
}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
Exibe 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
Mostra 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
Cria 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
Exibe caixas de diálogo 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
Exibe breves notificações toast 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 Agent precisa:
let toolset = UiToolset::new()
.without_chart() // Desabilita gráficos
.without_table() // Desabilita tabelas
.without_progress() // Desabilita progresso
.without_modal() // Desabilita modais
.without_toast(); // Desabilita toasts
// Ou use apenas formulários
let forms_only = UiToolset::forms_only();Manipulando Eventos da UI
Quando os usuários interagem com a UI renderizada (enviam formulários, clicam em botões), eventos são enviados de volta para o Agent:
use adk_ui::{UiEvent, UiEventType};
// Estrutura UiEvent
pub struct UiEvent {
pub event_type: UiEventType, // FormSubmit, ButtonClick, InputChange
pub action_id: Option<String>,
pub data: Option<HashMap<String, Value>>,
}
// Converte para mensagem para o Agent
let message = ui_event.to_message();Streaming de Atualizações da UI
Para atualizações da 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 id opcionais para atualizações via streaming:
Átomos: Text, Button, Icon, Image, Badge Inputs: TextInput, NumberInput, Select, MultiSelect, Switch, DateInput, Slider, Textarea Layouts: Stack, Grid, Card, Container, Divider, Tabs Dados: Table, List, KeyValue, CodeBlock Visualização: Chart (barra, linha, área, pizza via Recharts) Feedback: Alert, Progress, Toast, Modal, Spinner, Skeleton
Cliente React
Uma implementação de referência em React é fornecida:
cd official_docs_examples/tools/ui_test
# Start the UI server
cargo run --bin ui_server
# In another terminal, start the React client
cd ui_react_client
npm install && npm run dev -- --hostO cliente React inclui:
- Tipos TypeScript que correspondem ao esquema Rust
- Renderizador de componentes para todos os 28 tipos
- Integração Recharts para gráficos interativos
- Suporte para renderização Markdown
- Suporte para modo escuro
- Tratamento de envio de formulários
- Componentes Modal e Toast
Arquitetura
┌─────────────┐ ┌─────────────┐
│ Agent │ ──[render_* tool]──│ UiResponse │
│ (LLM) │ │ (JSON) │
└─────────────┘ └──────┬──────┘
▲ │
│ │ SSE
│ ▼
│ ┌─────────────┐
└────── UiEvent ◄───────────│ Client │
(user action) │ (React) │
└─────────────┘Exemplos
Três exemplos demonstram ferramentas de UI:
| Exemplo | Descrição | Comando para Executar |
|---|---|---|
ui_agent | Demonstração no console | cargo run --bin ui_agent |
ui_server | Servidor HTTP com SSE | cargo run --bin ui_server |
ui_react_client | Frontend React | cd ui_react_client && npm run dev |
Execute a partir de official_docs_examples/tools/ui_test/.
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: ← Browser Tools | Próximo: MCP Tools →