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

تمكّن حزمة adk-ui عملاء AI من إنشاء واجهات مستخدم غنية ديناميكيًا من خلال tool calls. يمكن للعملاء عرض النماذج، البطاقات، التنبيهات، الجداول، الرسوم البيانية، والمزيد - كل ذلك من خلال Rust API آمن من ناحية الأنواع (type-safe) والذي يتم تسلسله إلى JSON للاستخدام في الواجهة الأمامية.

ما ستقوم ببنائه

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

النماذج (Forms) - لجمع مدخلات المستخدم بأنواع حقول مختلفة
البطاقات (Cards) - لعرض المعلومات مع أزرار الإجراءات
الجداول (Tables) - لعرض البيانات المنظمة في صفوف/أعمدة
الرسوم البيانية (Charts) - لتصوير البيانات باستخدام الرسوم البيانية الشريطية، الخطية، المساحية، والدائرية
التنبيهات (Alerts) - لإظهار الإشعارات ورسائل الحالة
النوافذ المنبثقة (Modals) - مربعات حوار التأكيد والتفاعلات المركزة
إشعارات التوست (Toasts) - إشعارات حالة موجزة

مثال: لوحة تحكم التحليلات

مثال: نموذج التسجيل

كيف يعمل

┌─────────────────────────────────────────────────────────────────────────────┐
│ الخطوة 1: يطلب المستخدم شيئًا ما                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   المستخدم: "أرغب في التسجيل للحصول على حساب"                                 │
│                                                                             │
│                              ↓                                              │
│                                                                             │
│   ┌──────────────────────────────────────┐                                  │
│   │         وكيل الذكاء الاصطناعي (LLM)              │                                  │
│   │  "يجب أن أعرض نموذج تسجيل" │                                  │
│   └──────────────────────────────────────┘                                  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ الخطوة 2: يقوم الوكيل باستدعاء أداة render_form                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   📞 استدعاء الأداة: render_form({                                               │
│     title: "تسجيل",                                                  │
│     fields: [                                                               │
│       {name: "email", type: "email"},                                       │
│       {name: "password", type: "password"}                                  │
│     ]                                                                       │
│   })                                                                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ الخطوة 3: الواجهة الأمامية تعرض النموذج                                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌─────────────────────────────────────────────────┐                       │
│   │  📋 تسجيل                               │                       │
│   │  ────────────────────────────────────────────  │                       │
│   │  البريد الإلكتروني:    [________________________]          │                       │
│   │  كلمة المرور: [________________________]          │                       │
│   │                                                │                       │
│   │  [           تسجيل           ]              │                       │
│   └─────────────────────────────────────────────────┘                       │
│                                                                             │
│   ✅ يرى المستخدم نموذجًا تفاعليًا، يملأه، ثم ينقر على تسجيل           │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ الخطوة 4: يتم إرسال إرسال النموذج مرة أخرى إلى الوكيل                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   📩 حدث: {                                                               │
│     type: "form_submit",                                                    │
│     data: { email: "user@example.com", password: "***" }                    │
│   }                                                                         │
│                                                                             │
│   الوكيل: "رائع! سأقوم بمعالجة تسجيلك وعرض تنبيه نجاح"  │
│                                                                             │
│   📞 استدعاء الأداة: render_alert({                                              │
│     title: "اكتمل التسجيل!",                                        │
│     variant: "success"                                                      │
│   })                                                                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

نظرة عامة

تتيح أدوات UI للوكلاء ما يلي:

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

البدء السريع

أضف إلى ملف Cargo.toml الخاص بك:

[dependencies]
adk-rust = { version = "0.2.0", features = ["ui"] }
# Or use individual crates:
adk-ui = "0.2.0"
adk-agent = "0.2.0"
adk-model = "0.2.0"

الاستخدام الأساسي

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")?);

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

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

render_form

لعرض نماذج تفاعلية لجمع مدخلات المستخدم.

{
  "title": "نموذج التسجيل",
  "description": "أنشئ حسابك",
  "fields": [
    {"name": "username", "label": "اسم المستخدم", "type": "text", "required": true},
    {"name": "email", "label": "البريد الإلكتروني", "type": "email", "required": true},
    {"name": "password", "label": "كلمة المرور", "type": "password", "required": true},
    {"name": "newsletter", "label": "الاشتراك في النشرة الإخبارية", "type": "switch"}
  ],
  "submit_label": "تسجيل"
}

يُعرض كـ:

┌─────────────────────────────────────────────────┐
│  📋 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": "تم تأكيد الطلب",
  "description": "الطلب رقم #12345",
  "content": "تم تقديم طلبك بنجاح. تاريخ التسليم المتوقع: 15 ديسمبر 2025.",
  "actions": [
    {"label": "تتبع الطلب", "action_id": "track", "variant": "primary"},
    {"label": "إلغاء", "action_id": "cancel", "variant": "danger"}
  ]
}

أنواع الأزرار: primary, secondary, danger, ghost, outline

render_alert

لعرض الإشعارات ورسائل الحالة.

{
  "title": "الدفع بنجاح",
  "description": "تمت معالجة دفعتك بقيمة 99.00 دولارًا.",
  "variant": "success"
}

الأنواع: info, success, warning, error

render_confirm

لطلب تأكيد المستخدم قبل الإجراءات.

{
  "title": "حذف الحساب",
  "message": "هل أنت متأكد أنك تريد حذف حسابك؟ لا يمكن التراجع عن هذا الإجراء.",
  "confirm_label": "حذف",
  "cancel_label": "الاحتفاظ بالحساب",
  "variant": "danger"
}

render_table

لعرض البيانات الجدولية.

{
  "title": "الطلبات الأخيرة",
  "columns": [
    {"header": "معرف الطلب", "accessor_key": "id"},
    {"header": "التاريخ", "accessor_key": "date"},
    {"header": "المبلغ", "accessor_key": "amount"},
    {"header": "الحالة", "accessor_key": "status"}
  ],
  "data": [
    {"id": "#12345", "date": "2025-12-10", "amount": "$99.00", "status": "تم التسليم"},
    {"id": "#12346", "date": "2025-12-11", "amount": "$149.00", "status": "تم الشحن"}
  ]
}

render_chart

لإنشاء تصورات البيانات.

{
  "title": "المبيعات الشهرية",
  "chart_type": "bar",
  "x_key": "month",
  "y_keys": ["revenue", "profit"],
  "data": [
    {"month": "يناير", "revenue": 4000, "profit": 2400},
    {"month": "فبراير", "revenue": 3000, "profit": 1398},
    {"month": "مارس", "revenue": 5000, "profit": 3800}
  ]
}

أنواع الرسوم البيانية: bar, line, area, pie

render_progress

لعرض تقدم المهمة مع خطوات اختيارية.

{
  "title": "تثبيت التبعيات",
  "value": 65,
  "description": "جارٍ تثبيت الحزمة 13 من 20...",
  "steps": [
    {"label": "تنزيل", "completed": true},
    {"label": "استخراج", "completed": true},
    {"label": "تثبيت", "current": true},
    {"label": "تكوين", "completed": false}
  ]
}

render_layout

لإنشاء تخطيطات لوحة معلومات متعددة الأقسام.

{
  "title": "حالة النظام",
  "description": "نظرة عامة على صحة النظام الحالية",
  "sections": [
    {
      "title": "الخدمات",
      "type": "stats",
      "stats": [
        {"label": "خادم API", "value": "سليم", "status": "operational"},
        {"label": "قاعدة البيانات", "value": "متدهورة", "status": "warning"},
        {"label": "الذاكرة المؤقتة", "value": "معطلة", "status": "error"}
      ]
    },
    {
      "title": "الأخطاء الأخيرة",
      "type": "table",
      "columns": [{"header": "الوقت", "key": "time"}, {"header": "الخطأ", "key": "error"}],
      "rows": [{"time": "10:30", "error": "انتهت مهلة الاتصال"}]
    }
  ]
}

أنواع الأقسام: stats, table, chart, alert, text

render_modal

لعرض مربعات حوار مشروطة (modal) للتأكيدات أو التفاعلات المركزة.

{
  "title": "تأكيد الحذف",
  "message": "هل أنت متأكد أنك تريد حذف هذا العنصر؟ لا يمكن التراجع عن هذا الإجراء.",
  "size": "medium",
  "closable": true,
  "confirm_label": "حذف",
  "cancel_label": "إلغاء",
  "confirm_action": "delete_confirmed"
}

الأحجام: small, medium, large, full

render_toast

لعرض إشعارات عابرة (toast) موجزة لتحديثات الحالة.

{
  "message": "تم حفظ الإعدادات بنجاح",
  "variant": "success",
  "duration": 5000,
  "dismissible": true
}

الأنواع: info, success, warning, error

أدوات مُصفّاة

اختر فقط الأدوات التي يحتاجها الـ Agent الخاص بك:

let toolset = UiToolset::new()
    .without_chart()      // تعطيل الرسوم البيانية
    .without_table()      // تعطيل الجداول
    .without_progress()   // تعطيل شريط التقدم
    .without_modal()      // تعطيل النماذج المشروطة
    .without_toast();     // تعطيل رسائل التوست

// أو استخدم النماذج فقط
let forms_only = UiToolset::forms_only();

التعامل مع أحداث واجهة المستخدم (UI Events)

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

use adk_ui::{UiEvent, UiEventType};

// بنية UiEvent
pub struct UiEvent {
    pub event_type: UiEventType,  // FormSubmit, ButtonClick, InputChange
    pub action_id: Option<String>,
    pub data: Option<HashMap<String, Value>>,
}

// تحويل إلى رسالة للـ Agent
let message = ui_event.to_message();

بث تحديثات واجهة المستخدم (UI Updates)

لتحديثات واجهة المستخدم في الوقت الفعلي، استخدم UiUpdate لتصحيح المكونات بواسطة المعرّف (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()),
    })),
};

العمليات: Replace, Patch, Append, Remove

مخطط المكونات

تدعم جميع أنواع المكونات الـ 28 حقول id الاختيارية لتحديثات البث:

الذرات (Atoms): Text, Button, Icon, Image, Badge المدخلات (Inputs): TextInput, NumberInput, Select, MultiSelect, Switch, DateInput, Slider, Textarea التخطيطات (Layouts): Stack, Grid, Card, Container, Divider, Tabs البيانات (Data): Table, List, KeyValue, CodeBlock التصور (Visualization): Chart (bar, line, area, pie via Recharts) الملاحظات (Feedback): Alert, Progress, Toast, Modal, Spinner, Skeleton

عميل React

يتم توفير تطبيق مرجعي لـ React:

cd official_docs_examples/tools/ui_test

# ابدأ خادم واجهة المستخدم (UI server)
cargo run --bin ui_server

# في طرفية أخرى، ابدأ عميل React
cd ui_react_client
npm install && npm run dev -- --host

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

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

البنية

┌─────────────┐                    ┌─────────────┐
│   Agent     │ ──[render_* tool]──│ UiResponse  │
│  (نموذج لغة كبير)      │                    │   (JSON)    │
└─────────────┘                    └──────┬──────┘
       ▲                                  │
       │                                  │ SSE
       │                                  ▼
       │                           ┌─────────────┐
       └────── UiEvent ◄───────────│   Client    │
              (إجراء المستخدم)        │  (React)    │
                                   └─────────────┘

أمثلة

توضح ثلاثة أمثلة أدوات واجهة المستخدم (UI):

مثال	الوصف	أمر التشغيل
`ui_agent`	عرض توضيحي عبر وحدة التحكم	`cargo run --bin ui_agent`
`ui_server`	خادم HTTP مع SSE	`cargo run --bin ui_server`
`ui_react_client`	واجهة React الأمامية	`cd ui_react_client && npm run dev`

شغّل من official_docs_examples/tools/ui_test/.

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

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

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