यूआई उपकरण

The adk-ui crate AI agents को tool calls के माध्यम से गतिशील रूप से समृद्ध उपयोगकर्ता इंटरफेस उत्पन्न करने में सक्षम बनाता है। Agents फ़ॉर्म, कार्ड, अलर्ट, टेबल, चार्ट और बहुत कुछ प्रस्तुत कर सकते हैं - यह सब एक प्रकार-सुरक्षित Rust API के माध्यम से जो JSON के लिए क्रमबद्ध होता है frontend उपयोग।

आप क्या बनाएंगे

मुख्य अवधारणाएँ:

• फ़ॉर्म - विभिन्न फ़ील्ड प्रकारों के साथ उपयोगकर्ता इनपुट एकत्र करें
• कार्ड - एक्शन बटन के साथ जानकारी प्रदर्शित करें
• टेबल - पंक्तियों/स्तंभों में संरचित डेटा प्रस्तुत करें
• चार्ट - बार, लाइन, एरिया, पाई चार्ट के साथ डेटा को विज़ुअलाइज़ करें
• अलर्ट - सूचनाएं और स्थिति संदेश दिखाएं
• मोडल - पुष्टि संवाद और केंद्रित इंटरैक्शन
• टोस्ट - संक्षिप्त स्थिति सूचनाएं
• प्रोटोकॉल अंतरसंचालन - UI को A2UI, AG-UI, या MCP ऐप्स पेलोड के रूप में उत्सर्जित करें

उदाहरण: एनालिटिक्स डैशबोर्ड

उदाहरण: पंजीकरण फ़ॉर्म

---

यह कैसे काम करता है

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

---

अवलोकन

UI टूल एजेंटों को इसकी अनुमति देते हैं:

• टेक्स्टएरिया समर्थन के साथ डायनामिक फ़ॉर्म के माध्यम से उपयोगकर्ता इनपुट एकत्र करें
• कार्ड, अलर्ट और सूचनाओं के साथ जानकारी प्रदर्शित करें
• तालिकाओं और इंटरैक्टिव चार्ट (Recharts) में डेटा प्रस्तुत करें
• प्रगति और लोडिंग स्थिति (स्पिनर, स्केलेटन) दिखाएं
• कई कंपोनेंट के साथ डैशबोर्ड लेआउट बनाएँ
• मोडल के माध्यम से उपयोगकर्ता की पुष्टि का अनुरोध करें
• स्थिति अपडेट के लिए टोस्ट सूचनाएँ प्रदर्शित करें

त्वरित शुरुआत

अपने Cargo.toml में जोड़ें:

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

मूल उपयोग

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)

ये उपकरण A2UI v0.9 JSONL को A2UI renderers के साथ संगतता के लिए उत्सर्जित करते हैं।

render_screen (एकल सतह)

{
  "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 (बहु-खंड पृष्ठ)

{
  "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 (कैटलॉग + टोकन + टेम्प्लेट)

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

A2UI JSONL का उपभोग करने के लिए React रेंडरर का उपयोग करें:

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" />;
}

उपलब्ध उपकरण

render_form

उपयोगकर्ता इनपुट एकत्र करने के लिए इंटरैक्टिव फ़ॉर्म रेंडर करें।

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

इस रूप में प्रस्तुत होता है:

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

फ़ील्ड प्रकार: text, email, password, number, date, select, multiselect, switch, slider, textarea

render_card

वैकल्पिक एक्शन बटन के साथ जानकारी कार्ड प्रदर्शित करें।

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

बटन प्रकार: primary, secondary, danger, ghost, outline

render_alert

सूचनाएं और स्थिति संदेश दिखाएं।

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

प्रकार: info, success, warning, error

render_confirm

कार्रवाइयों से पहले उपयोगकर्ता की पुष्टि का अनुरोध करें।

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

सारणीबद्ध डेटा प्रदर्शित करें।

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

डेटा विज़ुअलाइज़ेशन बनाएँ।

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

चार्ट प्रकार: bar, line, area, pie

render_progress

वैकल्पिक चरणों के साथ कार्य प्रगति दिखाएं।

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

कई अनुभागों के साथ डैशबोर्ड लेआउट बनाएं।

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

अनुभाग प्रकार: stats, table, chart, alert, text

render_modal

पुष्टि या केंद्रित इंटरैक्शन के लिए मोडल डायलॉग प्रदर्शित करें।

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

आकार: small, medium, large, full

render_toast

स्थिति अपडेट के लिए संक्षिप्त टोस्ट सूचनाएं दिखाएं।

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

प्रकार: info, success, warning, error

फ़िल्टर्ड उपकरण

केवल वही उपकरण चुनें जिनकी आपके एजेंट को आवश्यकता है:

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

UI घटनाओं को संभालना

जब उपयोगकर्ता रेंडर किए गए UI (फॉर्म सबमिट करते हैं, बटन क्लिक करते हैं) के साथ इंटरैक्ट करते हैं, तो इवेंट एजेंट को वापस भेजे जाते हैं:

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

UI अपडेट्स को स्ट्रीम करना

रीयल-टाइम UI अपडेट्स के लिए, कंपोनेंट्स को ID द्वारा पैच करने के लिए UiUpdate का उपयोग करें:

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

संचालन: Replace, Patch, Append, Remove

घटक स्कीमा

सभी 28 घटक प्रकार स्ट्रीमिंग अपडेट के लिए वैकल्पिक id फ़ील्ड का समर्थन करते हैं:

परमाणु: Text, Button, Icon, Image, Badge इनपुट्स: TextInput, NumberInput, Select, MultiSelect, Switch, DateInput, Slider, Textarea लेआउट्स: Stack, Grid, Card, Container, Divider, Tabs डेटा: Table, List, KeyValue, CodeBlock दृश्यीकरण: चार्ट (बार, लाइन, एरिया, पाई Recharts के माध्यम से) प्रतिक्रिया: अलर्ट, प्रोग्रेस, टोस्ट, मोडल, स्पिनर, स्केलेटन

रिएक्ट क्लाइंट

एक संदर्भ रिएक्ट कार्यान्वयन स्टैंडअलोन adk-ui रिपॉजिटरी में प्रदान किया गया है:

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

रिएक्ट क्लाइंट में शामिल हैं:

• TypeScript Rust स्कीमा से मेल खाने वाले प्रकार
• सभी 28 प्रकारों के लिए कंपोनेंट रेंडरर
• इंटरैक्टिव चार्ट के लिए Recharts एकीकरण
• Markdown रेंडरिंग समर्थन
• डार्क मोड समर्थन
• फॉर्म सबमिशन हैंडलिंग
• मॉडल और टोस्ट घटक

वास्तुकला

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

प्रोटोकॉल अंतरसंचालनीयता

सभी 13 रेंडर टूल protocol तर्क के माध्यम से प्रोटोकॉल-जागरूक आउटपुट का समर्थन करते हैं:

जब protocol को छोड़ा जाता है, तो tools अपने डिफ़ॉल्ट आउटपुट फ़ॉर्मेट का उपयोग करते हैं (अधिकांश tools के लिए लेगेसी UiResponse JSON, A2UI render_screen/render_page/render_kit के लिए)।

प्रोटोकॉल चयन के साथ उदाहरण:

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

इंटरॉप एडेप्टर

adk-ui में प्रोटोकॉल रूपांतरण के लिए एडेप्टर प्रिमिटिव्स शामिल हैं:

• A2uiAdapter — कैनोनिकल सतहों को A2UI JSONL में रूपांतरित करता है
• AgUiAdapter — AG-UI इवेंट पेलोड में रूपांतरित करता है
• McpAppsAdapter — MCP Apps संसाधन पेलोड में रूपांतरित करता है

ये सभी टूलों में सुसंगत रूपांतरण के लिए एक साझा UiProtocolAdapter trait लागू करते हैं।

अप्रचलन समय-सीमा

विरासत में मिला adk_ui runtime profile में अप्रचलन मेटाडेटा शामिल है:

प्रतिस्थापन: a2ui, ag_ui, mcp_apps

यह मेटाडेटा UI_PROTOCOL_CAPABILITIES स्थिरांकों के माध्यम से उपलब्ध होता है और adk-server इसे /api/ui/capabilities पर प्रस्तुत करता है। क्षमता प्रतिक्रिया भी implementationTier, specTrack, summary, और limitations रिपोर्ट करती है ताकि क्लाइंट हाइब्रिड या संगतता उपसमूहों को पूरी तरह से नेटिव प्रोटोकॉल समर्थन से अलग कर सकें।

जब adk-server होस्ट-फेसिंग बाउंड्री होता है, तो यह /api/ui/initialize, /api/ui/message, /api/ui/update-model-context, /api/ui/notifications/poll, /api/ui/notifications/resources-list-changed, और /api/ui/notifications/tools-list-changed पर अतिरिक्त MCP Apps ब्रिज हेल्पर भी उजागर करता है। ये एंडपॉइंट मौजूदा ADK runtime को संरक्षित रखते हैं। अनुबंध और सीधे अनुरोध निकायों को या JSON-RPC-जैसे लिफाफों को ui/... विधियों के साथ स्वीकार करते हैं।

रनटाइम उपभोक्ताओं के लिए, adk-server निम्नलिखित का भी समर्थन करता है:

• AG-UI-नेटिव SSE सीरियलाइज़ेशन के लिए x-adk-ui-transport: protocol_native या uiTransport: "protocol_native"
• मौजूदा newMessage के अतिरिक्त input / agUiInput के माध्यम से AG-UI डुअल-पाथ अनुरोध इनपुट
• MCP ऐप्स /api/run_sse के अंदर एन्वलप को mcpAppsInitialize, mcpAppsRequest, और mcpAppsInitialized के माध्यम से ब्रिज करते हैं

ये अतिरिक्त सुविधाएँ वैकल्पिक हैं। मौजूदा /api/run और /api/run_sse उपभोक्ता सामान्य ADK रैपर प्राप्त करना जारी रखेंगे जब तक वे स्पष्ट रूप से एक मूल AG-UI ट्रांसपोर्ट मोड का अनुरोध नहीं करते।

फ्रेमवर्क-स्वामित्व वाले MCP एप्लिकेशन टूल प्रतिक्रियाओं के लिए, adk-server::ui_types अब उजागर करता है:

• McpUiBridgeSnapshot टाइप्ड होस्ट/ऐप ब्रिज स्थिति के लिए
• McpUiToolResult योगात्मक प्रतिक्रिया लिफाफे के लिए
• McpUiToolResultBridge के लिए bridge metadata (protocolVersion, structuredContent, hostInfo, hostCapabilities, hostContext, appInfo, appCapabilities, initialized)

जब bridge/session state को एक Tool प्रतिक्रिया में शामिल किया जा रहा हो, तो McpUiBridgeSnapshot::build_tool_result(...) को प्राथमिकता दें। यह संगतता-उन्मुख hosts के लिए resourceUri और इनलाइन html fallbacks को संरक्षित रखते हुए Tool-परिणाम के आकार को मानकीकृत करता है।

एम्बेडेड या ब्राउज़र-होस्ट मैपिंग के लिए, योगात्मक HTTP ब्रिज होस्ट/ऐप प्रवाह से इस प्रकार मेल खाता है:

• 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
• कतारबद्ध होस्ट सूचनाएँ -> /api/ui/notifications/poll

प्रत्यक्ष /api/ui/* ब्रिज एंडपॉइंट्स MCP ऐप्स होस्ट के लिए पसंदीदा जीवनचक्र पथ हैं। रनटाइम-साइड MCP ऐप्स अनुरोध फ़ील्ड मिश्रित या पुराने क्लाइंट्स के लिए एक अतिरिक्त संगतता पथ के रूप में उपलब्ध रहते हैं।

उदाहरण

स्टैंडअलोन adk-ui repo में चलाने योग्य UI उदाहरण शामिल हैं:

उन उदाहरणों को adk-ui रिपॉजिटरी से चलाएँ ताकि Rust और React पैकेज एक ही रिलीज़ लाइन पर रहें।

नमूना प्रॉम्प्ट

इन प्रॉम्प्ट के साथ UI टूल का परीक्षण करें:

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

---

पिछला: ← Browser Tools | अगला: MCP Tools →