تجارب الواجهة الأمامية باستخدام ADK وA2UI

1. نظرة عامة

يردّ معظم وكلاء الذكاء الاصطناعي بنص. في هذا الدرس التطبيقي حول الترميز، ستستخدم A2UI للسماح لوكيلك بالردّ باستخدام واجهة مستخدم بدلاً من ذلك. يصف الوكيل البطاقات والقوائم والأزرار والنماذج بتنسيق JSON باستخدام قائمة بالمكوّنات العادية، ويعرضها العميل باستخدام أدواته الأصلية، لذا لا تحتاج التنسيقات الجديدة إلى رمز جديد للواجهة الأمامية.

ستنشئ الوكيل باستخدام حزمة تطوير الوكلاء (ADK).

ما ستنشئه

لوحة بيانات وهمية للبنية التحتية للسحابة الإلكترونية في ثلاث مراحل:

  1. وكيل عادي يعرض بيانات الموارد كنص عادي
  2. وكيل A2UI يعرض البيانات نفسها التي يعرضها ملف JSON الخاص ببيانات A2UI المنظَّمة
  3. وكيل معروض يعرض ملف JSON الخاص بواجهة A2UI على شكل مكوّنات تفاعلية لواجهة المستخدم في واجهة المستخدم الخاصة بمجموعة أدوات تطوير ADK

وكيل ADK A2UI

أهداف الدورة التعليمية

  • طريقة عمل A2UI: 18 عنصرًا أساسيًا، والرسائل التي تنشئ واجهة مستخدم، ونموذج المكوّنات المسطّحة
  • كيفية استخدام حزمة تطوير البرامج (SDK) الخاصة بواجهة A2UI لطلب إنشاء ملف JSON خاص بواجهة A2UI من وكيل ADK
  • كيفية عرض مكوّنات A2UI في adk web

المتطلبات

  • مشروع Google Cloud تم تفعيل الفوترة فيه
  • متصفّح ويب، مثل Chrome
  • ‫Python 3.12 والإصدارات الأحدث وuv، إذا كنت ستشغّل الرمز البرمجي على جهازك بدلاً من Cloud Shell

هذا الدرس التطبيقي حول الترميز مخصّص للمطوّرين المتوسطي الخبرة الذين لديهم بعض المعرفة بلغة Python وGoogle Cloud.

يستغرق إكمال هذا الدرس التطبيقي حول الترميز حوالي 20 دقيقة.

يجب أن تكون تكلفة الموارد التي تم إنشاؤها في هذا الدرس التطبيقي حول الترميز أقل من 5 دولارات أمريكية.

2. إعداد البيئة

إنشاء مشروع على Google Cloud

  1. في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على السحابة الإلكترونية أو أنشِئ مشروعًا على السحابة الإلكترونية.
  2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع

بدء Cloud Shell Editor

لبدء جلسة Cloud Shell من "وحدة تحكّم Google Cloud"، انقر على تفعيل Cloud Shell في "وحدة تحكّم Google Cloud".

سيؤدي ذلك إلى بدء جلسة في اللوحة السفلية من "وحدة تحكّم Google Cloud".

لتشغيل المحرِّر، انقر على فتح المحرِّر في شريط الأدوات في نافذة Cloud Shell.

تفعيل واجهات برمجة التطبيقات

في شريط أدوات "محرّر Cloud Shell"، انقر على الوحدة الطرفية ووحدة طرفية جديدة، ثم نفِّذ الأمر التالي لتفعيل واجهات برمجة التطبيقات المطلوبة:

gcloud services enable aiplatform.googleapis.com

تثبيت الحِزم التابعة

في الوحدة الطرفية، شغِّل الأوامر التالية لإنشاء مجلد لهذا الدرس التطبيقي حول الترميز، مع مجلد a2ui_agent بداخله لرمز الوكيل، وثبِّت Agent Development Kit (ADK) وA2UI SDK:

mkdir -p ~/adk-a2ui/a2ui_agent
cd ~/adk-a2ui
uv init --bare
uv add google-adk a2ui-agent-sdk

تنشئ uv بيئة Python معزولة لهذا الدرس التطبيقي حول الترميز، لذا لن تحتاج إلى تفعيل أي شيء. ابدأ أوامر Python بالرمز uv run.

3- إنشاء الوكيل

ابدأ باستخدام وكيل ADK عادي يعرض نصًا عاديًا. هذا هو الشكل الذي تبدو عليه معظم تطبيقات الوكيل اليوم.

ضبط إعدادات مشروعك

في نافذة Terminal، نفِّذ الأمر التالي لإنشاء a2ui_agent/.env باستخدام مشروعك وموقعك الجغرافي، وللسماح لـ ADK باستدعاء Gemini من خلال مشروعك على Google Cloud. يحمّل "حزمة تطوير تطبيقات Android" هذا الملف تلقائيًا، لذا تعمل الإعدادات أيضًا في المحطات الطرفية الجديدة.

cat > ~/adk-a2ui/a2ui_agent/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_ENTERPRISE=True
EOF

تحديد الأداة والبيانات التجريبية

أنشئ الملف a2ui_agent/resources.py الذي يتضمّن المحتوى التالي. تعرض هذه الأداة قائمة بموارد السحابة الإلكترونية مع حالتها.

RESOURCES = [
    {
        "name": "auth-service",
        "type": "Cloud Run",
        "region": "us-west1",
        "status": "healthy",
        "cpu": "2 vCPU",
        "memory": "1 GiB",
        "instances": 3,
        "url": "https://auth-service-abc123.run.app",
        "last_deployed": "2026-04-18T14:22:00Z",
    },
    {
        "name": "events-db",
        "type": "Cloud SQL",
        "region": "us-east1",
        "status": "warning",
        "tier": "db-custom-8-32768",
        "storage": "500 GB SSD",
        "connections": 195,
        "version": "PostgreSQL 16",
        "issue": "Storage usage at 92%",
    },
    {
        "name": "analytics-pipeline",
        "type": "Cloud Run",
        "region": "us-west1",
        "status": "error",
        "cpu": "2 vCPU",
        "memory": "4 GiB",
        "instances": 0,
        "url": "https://analytics-pipeline-ghi789.run.app",
        "last_deployed": "2026-04-10T16:45:00Z",
        "issue": "CrashLoopBackOff: OOM killed",
    },
]

def get_resources() -> list[dict]:
    """Get all cloud resources in the current project.
    Returns a list of cloud infrastructure resources including their
    name, type, region, status, and type-specific details.
    Status is one of: healthy, warning, error. Resources with
    warning or error status include an 'issue' field describing
    the problem.
    """
    return RESOURCES

تحديد الوكيل

أنشئ الملف a2ui_agent/agent.py مع تضمين المحتوى التالي:

from google.adk.agents import Agent
from google.adk.models import Gemini
from google.genai import types
from .resources import get_resources

root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that reports on project resources.",
    instruction=(
        "You are a cloud infrastructure assistant. When users ask about their "
        "cloud resources, use the get_resources tool to fetch the current state. "
        "Summarize the results clearly in plain text."
    ),
    tools=[get_resources],
)

4. اختبار الوكيل

يتضمّن "حزمة تطوير التطبيقات" واجهة مستخدم للمطوّرين يمكنك استخدامها للتفاعل مع الدليل وإرسال طلبات إليه في المتصفّح بغرض الاختبار.

بدء واجهة مستخدم تطوير حزمة تطوير التطبيقات (ADK)

في نافذة Cloud Shell Editor، نفِّذ الأمر التالي لبدء واجهة مستخدم تطوير "حزمة تطوير التطبيقات" (ADK):

uv run adk web --port 8080 --allow_origins "*" --reload_agents

من المفترض أن تظهر لك رسالة مشابهة لما يلي:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8080.                         |
+-----------------------------------------------------------------------------+

فتح واجهة مستخدم مطوّري ADK

يمكنك فتح واجهة مستخدم أدوات المطوّرين في ADK في المتصفّح من خلال الضغط على Ctrl أو Cmd والنقر على عنوان URL للاختبار المحلي، أو من خلال النقر على الزر معاينة الويب واختيار المعاينة على المنفذ 8080.

بعد عرض واجهة مستخدم ADK Dev، انقر على a2ui_agent من القائمة المنسدلة.

إرسال نماذج الطلبات

أرسِل طلبًا نموذجيًا إلى الوكيل:

What's running in my project?

جرِّب الآن طلبًا آخر وستحصل على المزيد من النتائج النصية:

Does anything need my attention?

يجب أن تبدو محادثتك مشابهة لما يلي:

وكيل ADK النصي

الإجابة دقيقة، ولكنّها عبارة عن نص طويل.

5- إنشاء ملف JSON لواجهة A2UI

بعد ذلك، بدِّل الوكيل من نص عادي إلى A2UI.

تتضمّن حزمة تطوير البرامج (SDK) المستندة إلى لغة Python الخاصة بواجهة A2UI أداة إنشاء طلبات تكتب طلبات النظام نيابةً عنك. تعرّف هذه السمة نموذج اللغة الكبير على قائمة مكوّنات A2UI الكاملة، وأسماء الأنواع والخصائص الصحيحة، وبنية JSON.

تعديل الوكيل

استبدِل محتوى a2ui_agent/agent.py بما يلي:

from google.adk.agents import Agent
from google.adk.agents.callback_context import CallbackContext
from google.adk.models import Gemini
from google.adk.models.llm_response import LlmResponse
from google.genai import types
from a2ui.inference_formats.direct_json import DirectJsonFormat
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

a2ui_format = DirectJsonFormat(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = a2ui_format.prompt_generator.generate(
    role_description=(
        "You are a cloud infrastructure assistant. When users ask about "
        "their cloud resources, use the get_resources tool to fetch the "
        "current state."
    ),
    workflow_description=(
        "Analyze the user's request and return structured UI when appropriate."
    ),
    ui_description=(
        "Use cards for resource summaries, rows and columns for comparisons, "
        "icons for status indicators, and buttons for drill-down actions. "
        "Do NOT use markdown formatting in text values. Use the usageHint "
        "property for heading levels instead. "
        "Respond ONLY with the A2UI JSON array. Do NOT include any text "
        "outside the JSON. Put all explanations into Text components."
    ),
    include_schema=True,
    include_examples=True,
)


def show_raw_json(
    callback_context: CallbackContext,
    llm_response: LlmResponse,
) -> LlmResponse | None:
    """Show the A2UI JSON as text so you can read it, instead of rendering it."""
    if not llm_response.content or not llm_response.content.parts:
        return None
    for part in llm_response.content.parts:
        if part.text:
            part.text = (
                part.text
                .replace("<a2ui-json>", "```json\n")
                .replace("</a2ui-json>", "\n```")
            )
    return llm_response


root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
    after_model_callback=show_raw_json,
)

تعرض show_raw_json ملف JSON الخاص بواجهة A2UI كنص لتتمكّن من قراءته. ستزيلها لاحقًا للاطّلاع على عرض واجهة المستخدم.

تجمع طريقة prompt_generator.generate() بين وصف دورك ومخطط JSON الكامل الخاص بواجهة A2UI وأمثلة التلقين ببضعة أمثلة، لكي يعرف النموذج اللغوي الكبير كيفية تنسيق الناتج بدقة. لست بحاجة إلى كتابة قائمة المكوّنات يدويًا.

يستخدم هذا الدرس التطبيقي حول الترميز الإصدار 0.8 من A2UI (version="0.8")، وهو الإصدار الذي يتيحه عارض adk web A2UI.

6. اختبار الردّ بتنسيق JSON

إذا كانت واجهة مستخدم المطوّرين في "حزمة تطوير التطبيقات" لا تزال تعمل من قبل، من المفترض أن تعيد تحميل التغييرات التي أجريتها على الوكيل تلقائيًا.

انقر على a2ui_agent، وابدأ جلسة جديدة بالنقر على +جلسة جديدة في أعلى يسار واجهة مستخدم "حزمة تطوير التطبيقات"، ثم أرسِل الطلب نفسه كما كان من قبل:

What's running in my project?

في هذه المرة، يردّ الوكيل باستخدام A2UI JSON بدلاً من النص العادي. ستظهر لك رسائل منظَّمة، مثل beginRendering وsurfaceUpdate (وdataModelUpdate أحيانًا)، في ناتج المحادثة، وذلك في مجموعة رموز JSON.

ADK A2UI JSON

يصف ملف JSON واجهة مستخدم غنية تتضمّن بطاقات ورموزًا وأزرارًا، ولكن show_raw_json يحافظ على هذه العناصر كنص لتتمكّن من قراءتها. بعد ذلك، ستتعرّف على كيفية تنظيم ملف JSON هذا، ثم ستزيل show_raw_json لعرضه كمكوّنات فعلية لواجهة المستخدم.

7. التعرّف على A2UI

اطّلِع على ملف JSON الذي أنشأه الوكيل للتو. تتضمّن A2UI ثلاثة أنواع من الرسائل لإنشاء واجهة مستخدم. قد لا يستخدم الوكيل النطاقات الثلاثة كلها في كل مرة:

‫1. beginRendering

ينشئ هذا الرمز مساحة عرض ويسمّي المكوّن الجذر:

{"beginRendering": {"surfaceId": "default", "root": "main-column"}}

‫2. surfaceUpdate

إرسال شجرة المكوّنات كـ قائمة مسطّحة مع مراجع المعرّفات (غير متداخلة):

{"surfaceUpdate": {"surfaceId": "default", "components": [
  {"id": "main-column", "component": {"Column": {"children": {"explicitList": ["title", "card1"]}}}},
  {"id": "title", "component": {"Text": {"text": {"literalString": "My Resources"}, "usageHint": "h1"}}},
  {"id": "card1", "component": {"Card": {"child": "card1-content"}}},
  {"id": "card1-content", "component": {"Text": {"text": {"path": "service_name"}}}}
]}}

‫3. dataModelUpdate

إرسال البيانات بشكل منفصل عن البنية:

{"dataModelUpdate": {"surfaceId": "default", "contents": [
  {"key": "service_name", "valueString": "auth-service"},
  {"key": "status", "valueString": "healthy"}
]}}

ترتبط المكوّنات بالبيانات باستخدام {"path": "key"}. يمكنك تعديل البيانات بدون إعادة إرسال شجرة المكوّنات.

الأنواع الأساسية الـ 18

الفئة

المكونات

التصميم

بطاقة وعمود وصف وقائمة وعلامات تبويب وفاصل ونافذة مشروطة

الشبكة الإعلانية

Text, Image, Icon, Video, AudioPlayer

الإدخال

TextField وDateTimeInput وMultipleChoice وCheckBox وSlider

الإجراء

زرّ

ينشئ الوكيل تنسيقات مختلفة، مثل عرض التصفّح أو لوحة بيانات الأولوية أو نموذج الإعداد، من هذه المكوّنات نفسها. اطّلِع على مرجع المكوّنات للحصول على تفاصيل عن كل مكوّن.

8. عرض مكوّنات A2UI

تغلّف حزمة تطوير البرامج (SDK) واجهة A2UI بعلامات عادية. adk web يتعرّف عليها ويعرض المكوّنات باستخدام أداة العرض المدمجة في A2UI. للاطّلاع عليه، أزِل show_raw_json.

تعديل الوكيل

استبدِل محتوى a2ui_agent/agent.py بما يلي. التغييرات الوحيدة عن الخطوة السابقة هي أنّ الدالة show_raw_json والمعلمة after_model_callback وعمليتَي الاستيراد اللتين كانت تستخدمهما قد تمت إزالتهما:

from google.adk.agents import Agent
from google.adk.models import Gemini
from google.genai import types
from a2ui.inference_formats.direct_json import DirectJsonFormat
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

a2ui_format = DirectJsonFormat(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = a2ui_format.prompt_generator.generate(
    role_description=(
        "You are a cloud infrastructure assistant. When users ask about "
        "their cloud resources, use the get_resources tool to fetch the "
        "current state."
    ),
    workflow_description=(
        "Analyze the user's request and return structured UI when appropriate."
    ),
    ui_description=(
        "Use cards for resource summaries, rows and columns for comparisons, "
        "icons for status indicators, and buttons for drill-down actions. "
        "Do NOT use markdown formatting in text values. Use the usageHint "
        "property for heading levels instead. "
        "Respond ONLY with the A2UI JSON array. Do NOT include any text "
        "outside the JSON. Put all explanations into Text components."
    ),
    include_schema=True,
    include_examples=True,
)

root_agent = Agent(
    model=Gemini(
        model="gemini-3.8-flash",
        retry_options=types.HttpRetryOptions(attempts=5),
    ),
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
)

9. اختبار واجهة المستخدم المعروضة

إذا كانت واجهة مستخدم المطوّرين في "حزمة تطوير التطبيقات" لا تزال تعمل من قبل، من المفترض أن تعيد تحميل التغييرات التي أجريتها على الوكيل تلقائيًا.

أعِد تحميل علامة تبويب المتصفّح، وانقر على a2ui_agent، ثم ابدأ جلسة جديدة بالنقر على +جلسة جديدة في أعلى يسار واجهة مستخدم مطوّر ADK وأرسِل الطلب نفسه كما كان من قبل:

What's running in my project?

في هذه المرة، يعرض adk web مكونات A2UI كواجهة مستخدم فعلية: بطاقات تتضمّن مؤشرات الحالة وتفاصيل الموارد وأزرار الإجراءات.

وكيل ADK A2UI

جرِّب طلبًا مختلفًا لمعرفة كيف ينشئ الوكيل واجهة مستخدم مختلفة من المجموعة نفسها من العناصر الأساسية:

Does anything need my attention?

أخيرًا، جرِّب طلبًا آخر لإنشاء واجهة مستخدم مختلفة من أجل نشر خدمة جديدة:

I need to deploy a new service

تستخدم الطلبات الثلاثة نفسها الوكيل والأداة والمكوّنات نفسها، ولكن ينتج عن كل طلب واجهة مستخدم مختلفة تناسب ما طلبته.

10. تنظيف

لتجنُّب ترك الخوادم المحلية قيد التشغيل، عليك تنظيف الموارد باتّباع الخطوات التالية:

  • في نافذة الوحدة الطرفية التي يتم فيها تشغيل adk web، اضغط على Ctrl+C لإيقاف خادم الوكيل.

إذا أنشأت مشروعًا خصّيصًا لهذا الدرس التطبيقي حول الترميز، يمكنك حذف المشروع بأكمله باتّباع الخطوات التالية:

gcloud projects delete <YOUR_PROJECT_ID>

11. تهانينا

لقد أنشأت وكيل ADK ينشئ واجهة مستخدم تفاعلية غنية باستخدام A2UI.

ما تعلّمته

  • ‫A2UI هو بروتوكول يتضمّن 18 عنصرًا أساسيًا تعريفيًا وبعض الرسائل البسيطة التي تنشئ واجهة مستخدم.
  • تنشئ حزمة تطوير البرامج A2UI SDK طلبات من النظام تعلّم النموذج اللغوي الكبير كتالوج المكوّنات
  • يتألف الوكيل والأداة والعناصر الأساسية نفسها من واجهات مستخدم مختلفة لنوايا مختلفة
  • يمكن عرض مكوّنات A2UI مباشرةً في adk web أثناء التطوير

إنشاء واجهة أمامية للإنتاج

في هذا الدرس التطبيقي حول الترميز، عرضت A2UI داخل adk web لأغراض التطوير والاختبار.

بالنسبة إلى مرحلة الإنتاج، يمكنك إنشاء واجهة أمامية باستخدام أحد أدوات العرض الرسمية في A2UI:

النظام الأساسي

العارض

تثبيت

الويب (React)

@a2ui/react

npm install @a2ui/react

الويب (Lit)

@a2ui/lit

npm install @a2ui/lit

الويب (Angular)

@a2ui/angular

npm install @a2ui/angular

الجهاز الجوّال/الكمبيوتر

Flutter GenUI SDK

البدء

المستندات المرجعية

الخطوات التالية

استكشِف المراجع التعليمية لإنشاء وكلاء على مستوى المؤسسة ونشرهم باستخدام Gemini Enterprise Agent Ready (GEAR).