أدوات واجهة المستخدم

يمكّن adk-ui crate AI Agents من إنشاء واجهات مستخدم غنية ديناميكيًا من خلال استدعاءات الأدوات. يمكن لـ Agents عرض نماذج، بطاقات، تنبيهات، جداول، رسوم بيانية، والمزيد - كل ذلك من خلال Rust API آمن من حيث النوع يتم تسلسله إلى JSON لـ استهلاك الواجهة الأمامية.

ما ستبنيه

المفاهيم الأساسية:

• النماذج - جمع مدخلات المستخدم بأنواع حقول مختلفة
• البطاقات - عرض المعلومات مع أزرار الإجراءات
• الجداول - تقديم البيانات المنظمة في صفوف/أعمدة
• الرسوم البيانية - تصور البيانات باستخدام الرسوم البيانية الشريطية والخطية والمساحية والدائرية
• التنبيهات - عرض الإشعارات ورسائل الحالة
• النوافذ المنبثقة - مربعات حوار التأكيد والتفاعلات المركزة
• الإشعارات العابرة - إشعارات حالة موجزة
• التوافقية بين البروتوكولات - إصدار واجهة المستخدم كـ 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"                                                      │
│   })                                                                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

نظرة عامة

تسمح أدوات واجهة المستخدم للوكلاء بما يلي:

• جمع مدخلات المستخدم من خلال النماذج الديناميكية مع دعم حقول النص المتعدد
• عرض المعلومات باستخدام البطاقات والتنبيهات والإشعارات
• تقديم البيانات في جداول ومخططات تفاعلية (Recharts)
• إظهار التقدم وحالات التحميل (spinner, skeleton)
• إنشاء تخطيطات لوحة القيادة بمكونات متعددة
• طلب تأكيد المستخدم عبر النماذج المنبثقة (modals)
• عرض إشعارات التوست (toast notifications) لتحديثات الحالة

بدء سريع

أضف إلى 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.

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 (catalog + tokens + templates)

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

استخدم React renderer لاستهلاك 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" />;
}

الأدوات المتاحة

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

التعامل مع أحداث واجهة المستخدم

عندما يتفاعل المستخدمون مع واجهة المستخدم المعروضة (إرسال النماذج، النقر على الأزرار)، يتم إرسال الأحداث مرة أخرى إلى الوكيل:

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

تحديثات واجهة المستخدم المتدفقة

لتحديثات واجهة المستخدم في الوقت الفعلي، استخدم 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 component types تدعم optional id fields لـ streaming updates:

الذرات: نص، زر، أيقونة، صورة، شارة المدخلات: TextInput، NumberInput، تحديد، MultiSelect، مفتاح تبديل، DateInput، شريط تمرير، منطقة نص التخطيطات: مكدس، شبكة، بطاقة، حاوية، فاصل، علامات تبويب البيانات: جدول، قائمة، KeyValue، CodeBlock التصور: مخطط (شريطي، خطي، مساحي، دائري عبر Recharts) الملاحظات: تنبيه، تقدم، إشعار منبثق، نافذة مشروطة، مؤشر تحميل، هيكل عظمي

عميل React

يتم توفير تطبيق React مرجعي في المستودع المستقل adk-ui:

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

يتضمن عميل React ما يلي:

• TypeScript أنواع مطابقة لـ Rust schema
• عارض المكونات لجميع الأنواع الـ 28
• تكامل Recharts للرسوم البيانية التفاعلية
• دعم عرض Markdown
• دعم الوضع الداكن
• معالجة إرسال النماذج
• مكونات مشروطة وإشعارية

البنية

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

التوافقية بين البروتوكولات

تدعم جميع أدوات العرض الـ 13 إخراجًا واعيًا بالبروتوكول من خلال الوسيطة protocol:

عندما يتم حذف protocol، تستخدم الأدوات تنسيق الإخراج الافتراضي الخاص بها (تنسيق 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 مشتركة لتحويل متسق عبر جميع الأدوات.

الجدول الزمني للإهمال

يحمل ملف تعريف وقت التشغيل القديم adk_ui بيانات تعريف الإهمال:

البدائل: a2ui، ag_ui، mcp_apps

تُعرض هذه البيانات الوصفية عبر ثوابت UI_PROTOCOL_CAPABILITIES، وينشرها adk-server في /api/ui/capabilities. يُبلغ استجابة القدرة أيضًا عن implementationTier, specTrack, summary, و limitations حتى يتمكن العملاء من التمييز بين المجموعات الفرعية الهجينة أو المتوافقة عن دعم البروتوكول الأصلي بالكامل.

عندما adk-server يمثل الحدود المواجهة للمضيف، فإنه يعرض أيضًا مساعدات جسر Apps إضافية MCP عند /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. تحافظ نقاط النهاية هذه على الـ runtime الحالي ADK. عقود وتقبل إما نصوص طلبات مباشرة أو مغلفات شبيهة بـ JSON-RPC مع أساليب ui/....

للمستهلكين في وقت التشغيل، يدعم adk-server أيضًا:

• x-adk-ui-transport: protocol_native أو uiTransport: "protocol_native" لـ AG-UI-native SSE serialization
• مدخلات طلب المسار المزدوج لـ AG-UI عبر input / agUiInput بجانب newMessage الحالي
• MCP التطبيقات تربط المغلفات داخل /api/run_sse عبر mcpAppsInitialize، mcpAppsRequest، و mcpAppsInitialized

هذه الإضافات اختيارية. يستمر مستهلكو /api/run و /api/run_sse الحاليون في تلقي غلاف ADK العام ما لم يطلبوا صراحةً وضع نقل AG-UI الأصلي.

بالنسبة لاستجابات أداة تطبيقات MCP المملوكة للإطار، adk-server::ui_types يكشف الآن:

• McpUiBridgeSnapshot لحالة جسر المضيف/التطبيق المكتوبة
• McpUiToolResult لمغلف الاستجابة الإضافي
• McpUiToolResultBridge لبيانات تعريف الجسر (protocolVersion, structuredContent, hostInfo, hostCapabilities, hostContext, appInfo, appCapabilities, initialized)

يُفضل McpUiBridgeSnapshot::build_tool_result(...) عند ترويج bridge/session state إلى استجابة Tool. هذا يوحد شكل نتيجة الـ Tool مع الحفاظ على resourceUri و inline html حلول بديلة للمضيفين الموجهين نحو التوافق.

بالنسبة لتعيينات المضمنة أو المستضافة في المتصفح، يتوافق الجسر الإضافي 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/* المباشرة هي المسار المفضل لدورة حياة مضيفي Apps MCP. تظل حقول طلب Apps MCP من جانب وقت التشغيل متاحة كمسار توافق إضافي للعملاء المختلطين أو القدامى.

أمثلة

مستودع adk-ui المستقل يحتوي على أمثلة واجهة المستخدم القابلة للتشغيل:

قم بتشغيل هذه الأمثلة من مستودع adk-ui لتبقى حزم Rust و React على نفس خط الإصدار.

أمثلة على المطالبات

اختبر أدوات واجهة المستخدم باستخدام هذه المطالبات:

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

---

السابق: ← أدوات المتصفح | التالي: MCP الأدوات →