تجربیات فرانت‌اند با ADK و A2UI

۱. مرور کلی

بیشتر عامل‌های هوش مصنوعی با متن پاسخ می‌دهند. در این آزمایشگاه کد، شما از A2UI استفاده خواهید کرد تا به عامل خود اجازه دهید به جای آن با یک رابط کاربری پاسخ دهد. عامل، کارت‌ها، لیست‌ها، دکمه‌ها و فرم‌ها را در JSON و با استفاده از کاتالوگی از اجزای استاندارد توصیف می‌کند و کلاینت آنها را با ویجت‌های بومی خود رندر می‌کند، بنابراین طرح‌بندی‌های جدید نیازی به کد frontend جدید ندارند.

شما عامل را با استفاده از کیت توسعه عامل (ADK) خواهید ساخت.

آنچه خواهید ساخت

یک داشبورد زیرساخت ابری آزمایشی در سه مرحله:

  1. یک عامل استاندارد که داده‌های منابع را به صورت متن ساده برمی‌گرداند
  2. یک عامل A2UI که همان داده‌های A2UI JSON ساختاریافته را برمی‌گرداند.
  3. یک عامل رندر شده که A2UI JSON را به عنوان اجزای رابط کاربری تعاملی در رابط کاربری توسعه‌یافته ADK نمایش می‌دهد.

عامل ADK A2UI

آنچه یاد خواهید گرفت

  • نحوه کار A2UI: 18 عنصر اولیه، پیام‌هایی که رابط کاربری را می‌سازند، و مدل کامپوننت مسطح
  • نحوه استفاده از A2UI SDK برای وادار کردن یک عامل ADK به تولید A2UI JSON
  • نحوه رندر کردن کامپوننت‌های A2UI در adk web

آنچه نیاز دارید

  • یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب
  • یک مرورگر وب مانند کروم
  • پایتون ۳.۱۲+ و uv ، اگر کد را به جای Cloud Shell روی دستگاه خودتان اجرا کنید

این آزمایشگاه کد برای توسعه‌دهندگان سطح متوسط ​​است که با پایتون و گوگل کلود آشنایی دارند.

تکمیل این آزمایشگاه کد تقریباً 20 دقیقه طول می‌کشد.

منابع ایجاد شده در این آزمایشگاه کد باید کمتر از ۵ دلار هزینه داشته باشند.

۲. محیط خود را آماده کنید

ایجاد یک پروژه ابری گوگل

  1. در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .
  2. مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

ویرایشگر Cloud Shell را شروع کنید

برای راه‌اندازی یک جلسه Cloud Shell از کنسول Google Cloud، روی Activate Cloud Shell در کنسول Google Cloud خود کلیک کنید.

این یک جلسه در پنل پایین کنسول Google Cloud شما راه‌اندازی می‌کند.

برای اجرای ویرایشگر، روی گزینه Open Editor در نوار ابزار پنجره Cloud Shell کلیک کنید.

فعال کردن APIها

در نوار ابزار ویرایشگر Cloud Shell، روی Terminal و New Terminal کلیک کنید، سپس دستور زیر را برای فعال کردن API های مورد نیاز اجرا کنید:

gcloud services enable aiplatform.googleapis.com

نصب وابستگی‌ها

در ترمینال، دستورات زیر را اجرا کنید تا یک پوشه برای این codelab ایجاد شود، که درون آن یک پوشه a2ui_agent برای کد عامل شما قرار دارد و کیت توسعه عامل (ADK) و A2UI SDK را نصب کنید:

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

uv یک محیط پایتون ایزوله برای این codelab ایجاد می‌کند، بنابراین نیازی به فعال کردن چیزی ندارید. دستورات پایتون را با uv run شروع کنید.

۳. عامل را بسازید

با یک عامل ADK استاندارد که متن ساده را برمی‌گرداند شروع کنید. این چیزی است که اکثر برنامه‌های عامل امروزی به آن شبیه هستند.

تنظیمات پروژه خود را پیکربندی کنید

در ترمینال، دستور زیر را اجرا کنید تا a2ui_agent/.env را با پروژه و موقعیت مکانی خود ایجاد کنید و ADK از طریق پروژه Google Cloud شما، Gemini را فراخوانی کند. ADK این فایل را به طور خودکار بارگذاری می‌کند، بنابراین تنظیمات در ترمینال‌های جدید نیز کار می‌کنند.

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],
)

۴. عامل را آزمایش کنید

ADK شامل یک رابط کاربری توسعه‌دهنده است که می‌توانید از آن برای تعامل و ارسال پیام به عامل خود در مرورگر برای آزمایش استفاده کنید.

رابط کاربری ADK dev را شروع کنید

در ترمینال ویرایشگر Cloud Shell خود، دستور زیر را برای شروع رابط کاربری ADK dev اجرا کنید:

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 dev را در مرورگر خود با فشردن کلیدهای Ctrl یا Cmd و کلیک روی آدرس اینترنتی محلیِ در حال آزمایش، یا با کلیک روی دکمه‌ی پیش‌نمایش وب و انتخاب پیش‌نمایش روی پورت ۸۰۸۰، باز کنید.

پس از مشاهده رابط کاربری ADK dev، از منوی کشویی a2ui_agent را انتخاب کنید.

ارسال نمونه سوالات

یک نمونه درخواست برای نماینده ارسال کنید:

What's running in my project?

حالا یک نمونه‌ی دیگر از اعلان را امتحان کنید، خروجی متنی بیشتری دریافت خواهید کرد:

Does anything need my attention?

مکالمه شما باید شبیه به شکل زیر باشد:

عامل متن ADK

جواب دقیق است، اما پر از متن و ابهام است.

۵. تولید A2UI JSON

سپس، عامل را از متن ساده به A2UI تغییر دهید.

کیت توسعه نرم‌افزار پایتون A2UI شامل یک تولیدکننده اعلان است که اعلان‌های سیستم را برای شما می‌نویسد. این کیت، کاتالوگ کامل اجزای A2UI، نام‌ها و انواع صحیح ویژگی‌ها و ساختار JSON را به LLM آموزش می‌دهد.

به‌روزرسانی عامل

محتویات 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() توضیحات نقش شما را با طرح کامل A2UI JSON و مثال‌های مختصر ترکیب می‌کند، بنابراین LLM دقیقاً می‌داند که چگونه خروجی خود را قالب‌بندی کند. نیازی نیست کاتالوگ کامپوننت را به صورت دستی بنویسید.

این آزمایشگاه کد از A2UI نسخه ۰.۸ ( version="0.8" ) استفاده می‌کند، که نسخه‌ای است که رندرکننده‌ی adk web A2UI از آن پشتیبانی می‌کند.

۶. خروجی JSON را آزمایش کنید

اگر هنوز رابط کاربری توسعه‌دهنده ADK را از قبل اجرا دارید، باید به‌طور خودکار تغییراتی را که در عامل خود ایجاد کرده‌اید، مجدداً بارگذاری کند.

a2ui_agent را انتخاب کنید، با کلیک روی +New Session در سمت راست بالای رابط کاربری ADK dev، یک جلسه جدید را شروع کنید، سپس همان پیام قبلی را ارسال کنید:

What's running in my project?

این بار، عامل به جای متن ساده، با A2UI JSON پاسخ می‌دهد. پیام‌های ساختاریافته‌ای مانند beginRendering و surfaceUpdate (و گاهی اوقات dataModelUpdate ) را در خروجی چت، در یک بلوک کد JSON مشاهده خواهید کرد.

ADK A2UI JSON

JSON یک رابط کاربری غنی با کارت‌ها، آیکون‌ها و دکمه‌ها را توصیف می‌کند، اما show_raw_json آن را به صورت متن نگه می‌دارد تا بتوانید آن را بخوانید. در مرحله بعد، به نحوه ساختار این JSON نگاه خواهید کرد و سپس show_raw_json حذف خواهید کرد تا آن را به عنوان اجزای واقعی رابط کاربری رندر کنید.

۷. A2UI را درک کنید

به JSON که عامل شما ایجاد کرده است نگاه کنید. A2UI سه نوع پیام برای ساخت رابط کاربری دارد. خروجی عامل شما ممکن است همیشه از هر سه استفاده نکند:

۱. شروع رندرینگ

یک سطح رندر ایجاد می‌کند و کامپوننت ریشه را نامگذاری می‌کند:

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

۲. به‌روزرسانی سطح

درخت کامپوننت را به صورت یک لیست مسطح با ارجاعات ID (نه تو در تو) ارسال می‌کند:

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

۳. به‌روزرسانی مدل داده

داده‌ها را جدا از ساختار ارسال می‌کند:

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

کامپوننت‌ها با استفاده از {"path": "key"} به داده‌ها متصل می‌شوند. می‌توانید داده‌ها را بدون ارسال مجدد درخت کامپوننت به‌روزرسانی کنید.

۱۸ موجود اولیه

دسته بندی

قطعات

طرح بندی

کارت، ستون، ردیف، لیست، زبانه‌ها، جداکننده، مودال

نمایش

متن، تصویر، آیکون، ویدئو، پخش‌کننده صوتی

ورودی

فیلد متنی، ورودی تاریخ و زمان، انتخاب چندگانه، چک باکس، اسلایدر

اکشن

دکمه

عامل، طرح‌بندی‌های مختلفی مانند نمای مرور، داشبورد اولویت‌دار یا فرم پیکربندی را از همین اجزا می‌سازد. برای جزئیات بیشتر در مورد هر یک، به مرجع اجزا مراجعه کنید.

۸. رندر کردن کامپوننت‌های A2UI

SDK، رابط کاربری A2UI را به صورت استاندارد در بر می‌گیرد. تگ‌ها. adk web آنها را تشخیص می‌دهد و کامپوننت‌ها را با رندرکننده‌ی داخلی A2UI خود رندر می‌کند. برای دیدن آن، show_raw_json را حذف کنید.

به‌روزرسانی عامل

محتویات a2ui_agent/agent.py را با موارد زیر جایگزین کنید. تنها تغییرات نسبت به مرحله قبل این است که تابع show_raw_json ، پارامتر after_model_callback آن و دو import که استفاده می‌کرد، از بین رفته‌اند:

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],
)

۹. رابط کاربری رندر شده را آزمایش کنید

اگر هنوز رابط کاربری توسعه‌دهنده ADK را از قبل اجرا دارید، باید به‌طور خودکار تغییراتی را که در عامل خود ایجاد کرده‌اید، مجدداً بارگذاری کند.

تب مرورگر را رفرش کنید، a2ui_agent را انتخاب کنید، سپس با کلیک روی +New Session در سمت راست بالای رابط کاربری ADK dev، یک جلسه جدید را شروع کنید و همان اعلان قبلی را ارسال کنید:

What's running in my project?

این بار، adk web اجزای A2UI را به عنوان رابط کاربری واقعی رندر می‌کند: کارت‌هایی با نشانگرهای وضعیت، جزئیات منابع و دکمه‌های عملیاتی.

عامل ADK A2UI

یک اعلان دیگر را امتحان کنید تا ببینید که چگونه عامل، یک رابط کاربری متفاوت را از همان مجموعه اولیه‌ها می‌سازد:

Does anything need my attention?

در نهایت، یک اعلان دیگر را امتحان کنید تا یک رابط کاربری متفاوت برای استقرار یک سرویس جدید ایجاد شود:

I need to deploy a new service

هر سه درخواست از عامل، ابزار و اجزای یکسانی استفاده می‌کنند، اما هر کدام رابط کاربری متفاوتی تولید می‌کنند که با آنچه شما خواسته‌اید مطابقت دارد.

۱۰. تمیز کردن

برای جلوگیری از اجرای سرورهای محلی، منابع را پاک کنید:

  • در ترمینالی که adk web در حال اجرا است، کلیدهای Ctrl+C را فشار دهید تا سرور عامل متوقف شود.

اگر پروژه‌ای را به‌طور خاص برای این آزمایشگاه کد ایجاد کرده‌اید، می‌توانید کل پروژه را حذف کنید:

gcloud projects delete <YOUR_PROJECT_ID>

۱۱. تبریک

شما یک عامل ADK ساختید که با استفاده از A2UI رابط کاربری غنی و تعاملی ایجاد می‌کند.

آنچه آموختید

  • A2UI پروتکلی با ۱۸ عنصر اولیه اعلانی و چند پیام ساده است که یک رابط کاربری (UI) می‌سازد.
  • کیت توسعه نرم‌افزار A2UI پیام‌های سیستمی تولید می‌کند که کاتالوگ اجزا را به LLM آموزش می‌دهد.
  • عامل، ابزار و عناصر اولیه یکسان، رابط‌های کاربری متفاوتی را برای اهداف مختلف تشکیل می‌دهند.
  • اجزای A2UI می‌توانند در طول توسعه مستقیماً در adk web رندر شوند.

یک رابط کاربری تولید (production frontend) بسازید

در این آزمایشگاه کد، شما A2UI را درون adk web برای توسعه و آزمایش رندر کردید.

برای محیط عملیاتی، شما می‌توانید با استفاده از یکی از رندرکننده‌های رسمی A2UI، یک رابط کاربری (frontend) بسازید:

پلتفرم

رندر کننده

نصب

وب (واکنش)

@a2ui/react

npm install @a2ui/react

وب (ادبیات)

@a2ui/lit

npm install @a2ui/lit

وب (انگولار)

@a2ui/angular

npm install @a2ui/angular

موبایل/دسکتاپ

کیت توسعه نرم‌افزاری GenUI فلاتر

شروع به کار

اسناد مرجع

قدم بعدی چیست؟

منابع آموزشی برای ساخت و استقرار عامل‌های سازمانی با Gemini Enterprise Agent Ready (GEAR) را بررسی کنید.