חוויות קצה קדמי עם ADK ו-A2UI

1. סקירה כללית

רוב אפליקציות הנציגים מחזירות טקסט פשוט. A2UI משנה את זה. זהו פרוטוקול עם 18 פרימיטיבים הצהרתיים של ממשק משתמש, שמאפשרים לסוכן ליצור ממשקים עשירים ואינטראקטיביים. הלקוח מעבד אותם באופן מקורי. אין צורך בקוד חדש לחלק הקצה לכל פריסה.

בשיעור Codelab הזה נשתמש בערכה לפיתוח סוכנים (ADK) כדי ליצור את הסוכן וב-A2UI כדי ליצור את ממשק המשתמש.

מה תפַתחו

לוח בקרה של תשתית ענן בשלושה שלבים:

סוכן רגיל שמחזיר נתוני משאבים כטקסט פשוט
סוכן A2UI שמחזיר את אותם נתונים כמו JSON מובנה של A2UI
סוכן שעבר רינדור שמציג את ה-JSON של A2UI כרכיבי ממשק משתמש אינטראקטיביים בממשק המשתמש למפתחים של ADK

סוכן ADK A2UI

מה תלמדו

איך A2UI פועל: 18 פרימיטיבים, 3 סוגי הודעות, מודל רכיבים שטוח
איך משתמשים ב-A2UI SDK כדי להנחות סוכן ADK ליצור JSON של A2UI
איך מעבדים רכיבי A2UI ב-adk web

הדרישות

פרויקט ב-Google Cloud שהחיוב בו מופעל
דפדפן אינטרנט כמו Chrome
‫Python 3.12 ואילך

שיעור ה-Codelab הזה מיועד למפתחים ברמת ביניים שיש להם היכרות מסוימת עם Python ו-Google Cloud.

השלמת ה-codelab הזה תיקח בערך 15-20 דקות.

העלות של המשאבים שנוצרו ב-codelab הזה צריכה להיות פחות מ-5$.

2. הגדרת הסביבה

יצירת פרויקט ב-Google Cloud

במסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט ב-Google Cloud או יוצרים פרויקט.
הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט

הפעלת Cloud Shell Editor

כדי להפעיל סשן של Cloud Shell ממסוף Google Cloud, לוחצים על Activate Cloud Shell במסוף Google Cloud.

סשן יופעל בחלונית התחתונה של מסוף Google Cloud.

כדי לפתוח את העורך, לוחצים על Open Editor בסרגל הכלים שבחלון של Cloud Shell.

הגדרה של משתני סביבה

בסרגל הכלים של Cloud Shell Editor, לוחצים על Terminal (טרמינל) ואז על New Terminal (טרמינל חדש). מריצים את הפקודות הבאות כדי להגדיר את הפרויקט והמיקום, ולהגדיר את ADK לשימוש ב-Gemini ב-Vertex AI.

export GOOGLE_CLOUD_PROJECT=<INSERT_YOUR_GCP_PROJECT_HERE>
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

הפעלת ממשקי ה-API

בטרמינל, מריצים את הפקודה הבאה כדי להפעיל את ממשקי ה-API הנדרשים:

gcloud services enable aiplatform.googleapis.com

התקנת יחסי תלות

בטרמינל, מריצים את הפקודה הבאה כדי להתקין את הגרסה העדכנית של Agent Development Kit (ערכת פיתוח סוכנים, ADK):

pip install -U google-adk a2ui-agent-sdk
export PATH="$HOME/.local/bin:$PATH"

3. יצירת הסוכן

מתחילים עם סוכן ADK רגיל שמחזיר טקסט פשוט. כך נראות רוב האפליקציות של הסוכנים כיום.

יצירת תיקייה של סוכן

יוצרים תיקייה בשם a2ui_agent שתכיל את קוד המקור של הסוכן והכלים.

הגדרת כלי ונתוני הדמיה

יוצרים את 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 .resources import get_resources

root_agent = Agent(
    model="gemini-3-flash-preview",
    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 כולל ממשק משתמש למפתחים שמאפשר לקיים אינטראקציה עם הסוכן ולשלוח לו הנחיות בדפדפן לצורך בדיקה.

הפעלת ממשק המשתמש של ADK לפיתוח

בטרמינל של Cloud Shell Editor, מריצים את הפקודה הבאה כדי להפעיל את ממשק המשתמש של ADK dev:

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

אמורה להופיע הודעה דומה לזו:

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

פתיחת ממשק המשתמש של ADK dev

כדי לפתוח את ממשק המשתמש של ADK בדפדפן, לוחצים על Ctrl או על Cmd ואז על כתובת ה-URL של הבדיקה המקומית, או לוחצים על הלחצן Web Preview (תצוגה מקדימה באינטרנט) ובוחרים באפשרות Preview on Port 8080 (תצוגה מקדימה ביציאה 8080).

בתצוגת ממשק המשתמש של ADK Dev, בוחרים באפשרות a2ui_agent מהתפריט הנפתח.

שליחת הנחיות לדוגמה

שולחים לסוכן הנחיה לדוגמה:

What's running in my project?

עכשיו ננסה הנחיה לדוגמה אחרת ונקבל פלט טקסט נוסף:

Does anything need my attention?

השיחה שלכם אמורה להיראות כך:

סוכן ADK Text

יופיע קיר של טקסט. מדויק, אבל לא חוויית משתמש מעולה.

5. יצירת JSON של ממשק משתמש מבוסס-AI

מה אם הסוכן יוכל לתאר ממשק משתמש במקום להציג טקסט? ‫A2UI הוא פרוטוקול שמאפשר לסוכנים ליצור ממשקים אינטראקטיביים מקטלוג של 18 פרימיטיבים. הלקוח מעבד אותם באופן מקורי.

‫A2UI Python SDK כולל מנהל סכימות שיוצר בשבילכם הנחיות למערכת. הוא מלמד את מודל ה-LLM את הקטלוג המלא של רכיבי A2UI, את שמות המאפיינים והסוגים הנכונים ואת מבנה ה-JSON.

עדכון הסוכן

מחליפים את התוכן של a2ui_agent/agent.py בתוכן הבא:

from google.adk.agents import Agent
from a2ui.schema.manager import A2uiSchemaManager
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources

schema_manager = A2uiSchemaManager(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = schema_manager.generate_system_prompt(
    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-3-flash-preview",
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
)

השיטה generate_system_prompt() משלבת את תיאור התפקיד עם סכימת ה-JSON המלאה של A2UI ועם דוגמאות של few-shot, כדי שמודל ה-LLM יידע בדיוק איך לעצב את הפלט שלו. לא צריך לכתוב את קטלוג הרכיבים באופן ידני.

6. בדיקת פלט ה-JSON

אם עדיין פועל אצלכם ממשק המשתמש של ADK dev מהשלבים הקודמים, הוא אמור לטעון מחדש באופן אוטומטי את השינויים שביצעתם בסוכן.

בוחרים באפשרות a2ui_agent, מתחילים סשן חדש בלחיצה על +סשן חדש בפינה השמאלית העליונה של ממשק המשתמש של ADK למפתחים, ואז שולחים את אותה הנחיה כמו קודם:

What's running in my project?

הפעם, הנציג מגיב באמצעות JSON של A2UI במקום טקסט פשוט. בפלט של הצ'אט יוצגו הודעות מובנות שמכילות את beginRendering, surfaceUpdate ו-dataModelUpdate.

‫ADK A2UI JSON

קובץ ה-JSON מתאר ממשק משתמש עשיר עם כרטיסים, סמלים ולחצנים, אבל adk web מציג אותו כטקסט גולמי. בשלב הבא תגרמו לו לעבור רינדור כרכיבים בפועל בממשק המשתמש.

7. הסבר על A2UI

מעיינים בקובץ ה-JSON שהסוכן יצר. תראו שהיא מכילה שלושה סוגים של הודעות. כל תגובה של ממשק משתמש מבוסס-AI בנויה באותו מבנה:

‫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 הפרימיטיבים

קטגוריה	רכיבים
פריסה	כרטיס, עמודה, שורה, רשימה, כרטיסיות, קו הפרדה, חלון קופץ
רשת המדיה	טקסט, תמונה, סמל, סרטון, נגן אודיו
קלט	TextField, ‏ DateTimeInput, ‏ MultipleChoice, ‏ CheckBox, ‏ Slider
פעולה	כפתור

הסוכן יוצר פריסות שונות מאותו קטלוג. פרטים מלאים על כל פרימיטיב מופיעים במאמר בנושא הפניה לרכיבים. תצוגת עיון, מרכז בקרה של עדיפות וטופס הגדרה – כולם משתמשים באותם 18 פרימיטיבים. לא נדרשים רכיבי frontend חדשים.

8. עיבוד רכיבי A2UI

הסוכן יוצר JSON תקין של ממשק משתמש מבוסס-AI, אבל adk web מציג אותו כטקסט גולמי. כדי להציג אותו כרכיבי ממשק משתמש בפועל, צריך כלי קטן שממיר את פלט ה-JSON של A2UI של הסוכן לפורמט שמעבד התצוגה המובנה של adk web מצפה לו.

יצירת כלי העיבוד A2UI

יוצרים את הקובץ a2ui_agent/a2ui_utils.py עם התוכן הבא:

import json
import re
from google.genai import types
from google.adk.agents.callback_context import CallbackContext
from google.adk.models.llm_response import LlmResponse

def _wrap_a2ui_part(a2ui_message: dict) -> types.Part:
    """Wrap a single A2UI message for rendering in adk web."""
    datapart_json = json.dumps({
        "kind": "data",
        "metadata": {"mimeType": "application/json+a2ui"},
        "data": a2ui_message,
    })
    blob_data = (
        b"<a2a_datapart_json>"
        + datapart_json.encode("utf-8")
        + b"</a2a_datapart_json>"
    )
    return types.Part(
        inline_data=types.Blob(
            data=blob_data,
            mime_type="text/plain",
        )
    )

def a2ui_callback(
    callback_context: CallbackContext,
    llm_response: LlmResponse,
) -> LlmResponse | None:
    """Convert A2UI JSON in text output to rendered components."""
    if not llm_response.content or not llm_response.content.parts:
        return None
    for part in llm_response.content.parts:
        if not part.text:
            continue
        text = part.text.strip()
        if not text:
            continue
        if not any(k in text for k in ("beginRendering", "surfaceUpdate", "dataModelUpdate")):
            continue
        # Strip markdown fences
        if text.startswith("```"):
            text = text.split("\n", 1)[-1]
            if text.endswith("```"):
                text = text[:-3].strip()
        # Find where JSON starts (skip conversational prefix)
        json_start = None
        for i, ch in enumerate(text):
            if ch in ("[", "{"):
                json_start = i
                break
        if json_start is None:
            continue
        json_text = text[json_start:]
        # raw_decode parses JSON and ignores trailing text
        try:
            parsed, _ = json.JSONDecoder().raw_decode(json_text)
        except json.JSONDecodeError:
            # Handle concatenated JSON objects: {"a":1} {"b":2}
            try:
                fixed = "[" + re.sub(r'\}\s*\{', '},{', json_text) + "]"
                parsed, _ = json.JSONDecoder().raw_decode(fixed)
            except json.JSONDecodeError:
                continue
        if not isinstance(parsed, list):
            parsed = [parsed]
        a2ui_keys = {"beginRendering", "surfaceUpdate", "dataModelUpdate", "deleteSurface"}
        a2ui_messages = [msg for msg in parsed if isinstance(msg, dict) and any(k in msg for k in a2ui_keys)]
        if not a2ui_messages:
            continue
        new_parts = [_wrap_a2ui_part(msg) for msg in a2ui_messages]
        return LlmResponse(
            content=types.Content(role="model", parts=new_parts),
            custom_metadata={"a2a:response": "true"},
        )
    return None

כלי השירות הזה מבצע שתי פעולות:

מחולץ JSON של A2UI מפלט הטקסט של הסוכן
עוטף כל הודעה של A2UI בפורמט שמעבד ה-A2UI המובנה של adk web מצפה לו

עדכון הסוכן

מחליפים את התוכן של a2ui_agent/agent.py בתוכן הבא. השינוי היחיד מהשלב הקודם הוא הייבוא של a2ui_callback והפרמטר after_model_callback בסוכן:

from google.adk.agents import Agent
from a2ui.schema.manager import A2uiSchemaManager
from a2ui.basic_catalog.provider import BasicCatalog
from .resources import get_resources
from .a2ui_utils import a2ui_callback

schema_manager = A2uiSchemaManager(
    version="0.8",
    catalogs=[BasicCatalog.get_config("0.8")],
)

instruction = schema_manager.generate_system_prompt(
    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-3-flash-preview",
    name="cloud_dashboard",
    description="A cloud infrastructure assistant that renders rich A2UI interfaces.",
    instruction=instruction,
    tools=[get_resources],
    after_model_callback=a2ui_callback,
)

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

כל הנחיה מועברת לאותו סוכן, לאותו כלי ולאותם 18 רכיבים פרימיטיביים. אבל כל הנחיה מניבה ממשק משתמש שונה למטרה שונה.

10. הסרת המשאבים

כדי למנוע הפעלה של שרתים מקומיים, צריך לנקות את המשאבים:

בטרמינל שבו פועל adk web, מקישים על Ctrl+C כדי לעצור את שרת הסוכן.

אם יצרתם פרויקט במיוחד בשביל ה-Codelab הזה, אתם יכולים למחוק את הפרויקט כולו:

gcloud projects delete ${GOOGLE_CLOUD_PROJECT}

11. מזל טוב

יצרתם סוכן ADK שמייצר ממשק משתמש עשיר ואינטראקטיבי באמצעות A2UI.

מה למדתם

‫A2UI הוא פרוטוקול עם 18 פרימיטיבים הצהרתיים ו3 סוגי הודעות
ה-SDK של A2UI יוצר הנחיות למערכת שמלמדות את ה-LLM את קטלוג הרכיבים
אותו סוכן, כלי ופרימיטיבים מרכיבים ממשקי משתמש שונים למטרות שונות
אפשר לעבד רכיבי A2UI ישירות ב-adk web במהלך הפיתוח

פיתוח קצה קדמי לסביבת ייצור

בשיעור Codelab הזה, עיבדתם את 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	איך מתחילים

חוויות קצה קדמי עם ADK ו-A2UI

1. סקירה כללית

מה תפַתחו

מה תלמדו

הדרישות

2. הגדרת הסביבה

יצירת פרויקט ב-Google Cloud

הפעלת Cloud Shell Editor

הגדרה של משתני סביבה

הפעלת ממשקי ה-API

התקנת יחסי תלות

3. יצירת הסוכן

יצירת תיקייה של סוכן

הגדרת כלי ונתוני הדמיה

הגדרת הסוכן

4. בדיקת הנציג

הפעלת ממשק המשתמש של ADK לפיתוח

פתיחת ממשק המשתמש של ADK dev

שליחת הנחיות לדוגמה

5. יצירת JSON של ממשק משתמש מבוסס-AI

עדכון הסוכן

6. בדיקת פלט ה-JSON

7. הסבר על A2UI

‫1. beginRendering

‫2. surfaceUpdate

‫3. dataModelUpdate

‫18 הפרימיטיבים

8. עיבוד רכיבי A2UI

יצירת כלי העיבוד A2UI

עדכון הסוכן

9. בדיקת ממשק המשתמש שעבר רינדור

10. הסרת המשאבים

11. מזל טוב

מה למדתם

פיתוח קצה קדמי לסביבת ייצור

מסמכי עזר