1. סקירה כללית
רוב סוכני ה-AI עונים בהודעות טקסט. ב-Codelab הזה נשתמש ב-A2UI כדי לאפשר לסוכן להשיב באמצעות ממשק משתמש. הסוכן מתאר כרטיסים, רשימות, לחצנים וטפסים ב-JSON, באמצעות קטלוג של רכיבים סטנדרטיים, והלקוח מעבד אותם באמצעות הווידג'טים המקוריים שלו, כך שלא צריך קוד חדש לחלק הקדמי של האתר בשביל פריסות חדשות.
תבנו את הסוכן באמצעות ערכה לפיתוח סוכנים (ADK).
מה תפַתחו
לוח בקרה מדמה של תשתית ענן בשלושה שלבים:
- סוכן רגיל שמחזיר נתוני משאבים כטקסט פשוט
- סוכן A2UI שמחזיר את אותם נתונים כמו JSON מובנה של A2UI
- סוכן שעבר רינדור שמציג את ה-JSON של A2UI כרכיבי ממשק משתמש אינטראקטיביים בממשק המשתמש של ADK למפתחים

מה תלמדו
- איך A2UI פועל: 18 פרימיטיבים, ההודעות שיוצרות ממשק משתמש ומודל הרכיבים השטוח
- איך משתמשים ב-A2UI SDK כדי להנחות סוכן ADK ליצור JSON של A2UI
- איך מעבדים רכיבי A2UI ב-
adk web
הדרישות
- פרויקט ב-Google Cloud שהחיוב בו מופעל
- דפדפן אינטרנט כמו Chrome
- Python 3.12+ ו-uv, אם מריצים את הקוד במחשב שלכם במקום ב-Cloud Shell
שיעור ה-Codelab הזה מיועד למפתחים ברמת ביניים שיש להם היכרות מסוימת עם Python ו-Google Cloud.
השלמת ה-codelab הזה תימשך כ-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.
הפעלת ממשקי ה-API
בסרגל הכלים של Cloud Shell Editor, לוחצים על Terminal (טרמינל) ואז על New Terminal (טרמינל חדש), ומריצים את הפקודה הבאה כדי להפעיל את ממשקי ה-API הנדרשים:
gcloud services enable aiplatform.googleapis.com
התקנת יחסי תלות
בטרמינל, מריצים את הפקודות הבאות כדי ליצור תיקייה לשיעור ה-Codelab הזה, עם תיקייה בשם 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 מבודדת ל-Codelab הזה, כך שלא צריך להפעיל שום דבר. מוסיפים את הקידומת uv run לפקודות Python.
3. בניית הסוכן
מתחילים עם סוכן ADK רגיל שמחזיר טקסט פשוט. כך נראות רוב אפליקציות הסוכנים כיום.
הגדרת הגדרות הפרויקט
במסוף, מריצים את הפקודה הבאה כדי ליצור את a2ui_agent/.env עם הפרויקט והמיקום שלכם, וכדי ש-ADK יתקשר עם Gemini דרך פרויקט הענן שלכם ב-Google Cloud. ה-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],
)
4. בדיקת הסוכן
ADK כולל ממשק משתמש למפתחים שמאפשר לכם לקיים אינטראקציה עם הסוכן ולשלוח לו הנחיות בדפדפן לצורך בדיקה.
הפעלת ממשק המשתמש של ADK למפתחים
בטרמינל של Cloud Shell Editor, מריצים את הפקודה הבאה כדי להפעיל את ממשק המשתמש של 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 dev
כדי לפתוח את ממשק המשתמש של ADK בדפדפן, לוחצים על כתובת האתר של הבדיקה המקומית תוך כדי לחיצה על Ctrl או על Cmd, או לוחצים על הלחצן Web Preview (תצוגה מקדימה באינטרנט) ובוחרים באפשרות Preview on Port 8080 (תצוגה מקדימה ביציאה 8080).
בתצוגת ממשק המשתמש של ADK Dev, בוחרים באפשרות a2ui_agent מהתפריט הנפתח.
שליחת פרומפטים לדוגמה
שולחים לסוכן הנחיה לדוגמה:
What's running in my project?
עכשיו ננסה פרומפט לדוגמה אחר ונקבל פלט טקסט נוסף:
Does anything need my attention?
השיחה שלכם אמורה להיראות כך:

התשובה מדויקת, אבל היא מופיעה כטקסט ארוך וצפוף.
5. יצירת קובץ JSON של A2UI
בשלב הבא, מעבירים את הסוכן מטקסט פשוט לממשק משתמש מבוסס-AI.
A2UI Python SDK כולל מחולל הנחיות שכותב בשבילכם הנחיות למערכת. הוא מלמד את ה-LLM את קטלוג הרכיבים המלא של 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 ודוגמאות עם כמה דוגמאות (few-shot), כדי שמודל ה-LLM יידע בדיוק איך לעצב את הפלט שלו. אתם לא צריכים לכתוב את קטלוג הרכיבים באופן ידני.
בשיעור Codelab הזה נשתמש ב-A2UI גרסה 0.8 (version="0.8"), שהיא הגרסה שנתמכת על ידי רכיב העיבוד של adk web A2UI.
6. בדיקת פלט ה-JSON
אם ממשק המשתמש של ADK למפתחים עדיין פועל מהפעם הקודמת, הוא אמור לטעון מחדש באופן אוטומטי את השינויים שביצעתם לסוכן.
בוחרים באפשרות a2ui_agent, מתחילים סשן חדש בלחיצה על +סשן חדש בפינה השמאלית העליונה של ממשק המשתמש של ADK למפתחים, ואז שולחים את אותה הנחיה כמו קודם:
What's running in my project?
הפעם, הסוכן מגיב באמצעות JSON של A2UI במקום טקסט פשוט. בפלט של הצ'אט יופיעו הודעות מובנות כמו beginRendering ו-surfaceUpdate (ולפעמים dataModelUpdate) בבלוק קוד 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 הפרימיטיבים
קטגוריה | רכיבים |
פריסה | כרטיס, עמודה, שורה, רשימה, כרטיסיות, קו מפריד, חלון קופץ |
רשת המדיה | טקסט, תמונה, סמל, סרטון, נגן אודיו |
קלט | 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. בדיקת ממשק המשתמש שעבר רינדור
אם ממשק המשתמש של ADK למפתחים עדיין פועל מהפעם הקודמת, הוא אמור לטעון מחדש באופן אוטומטי את השינויים שביצעתם לסוכן.
מרעננים את כרטיסיית הדפדפן, בוחרים באפשרות a2ui_agent, ואז מתחילים סשן חדש בלחיצה על +סשן חדש בפינה השמאלית העליונה של ממשק המשתמש של ADK למפתחים, ושולחים את אותה הנחיה כמו קודם:
What's running in my project?
הפעם, adk web מעבד את רכיבי הממשק של A2UI כממשק משתמש בפועל: כרטיסים עם אינדיקטורים של סטטוס, פרטי משאבים ולחצני פעולה.

כדאי לנסות פרומפט אחר כדי לראות איך הסוכן יוצר ממשק משתמש שונה מאותה קבוצה של רכיבים בסיסיים:
Does anything need my attention?
לבסוף, נסו פרומפט אחר כדי ליצור ממשק משתמש שונה לפריסת שירות חדש:
I need to deploy a new service
כל שלושת ההנחיות משתמשות באותו סוכן, כלי ורכיבים, אבל כל אחת מהן יוצרת ממשק משתמש שונה שמתאים למה שביקשתם.
10. ניקוי
כדי למנוע הפעלה של שרתים מקומיים, צריך לנקות את המשאבים:
- בטרמינל שבו פועל
adk web, מקישים על Ctrl+C כדי לעצור את שרת הסוכן.
אם יצרתם פרויקט במיוחד בשביל ה-Codelab הזה, אתם יכולים למחוק את הפרויקט כולו:
gcloud projects delete <YOUR_PROJECT_ID>
11. מזל טוב
פיתחתם סוכן ADK שמייצר ממשק משתמש עשיר ואינטראקטיבי באמצעות A2UI.
מה למדתם
- A2UI הוא פרוטוקול עם 18 פרימיטיבים הצהרתיים וכמה הודעות פשוטות שיוצרות ממשק משתמש
- ערכת ה-SDK של A2UI יוצרת הנחיות למערכת שמלמדות את מודל ה-LLM את קטלוג הרכיבים
- אותו סוכן, כלי ופרימיטיבים יוצרים ממשקי משתמש שונים למטרות שונות
- אפשר לעבד רכיבי A2UI ישירות ב-
adk webבמהלך הפיתוח
יצירת קצה קדמי לסביבת הייצור
בשיעור Codelab הזה, רינדרתם את A2UI בתוך adk web לצורך פיתוח ובדיקה.
לצורך הפקה, צריך ליצור קצה קדמי באמצעות אחד ממנועי הרינדור הרשמיים של A2UI:
פלטפורמה | מפיק | התקנה |
אינטרנט (React) |
|
|
אינטרנט (Lit) |
|
|
אינטרנט (Angular) |
|
|
בנייד או במחשב | Flutter GenUI SDK |
מסמכי עזר
- מפרט ומסמכים של A2UI
- מאגר GitHub של A2UI
- הכלי לעיבוד הממשק של A2UI
- חומרי עזר בנושא ADK
- שילוב ADK A2UI
המאמרים הבאים
במסגרת Gemini Enterprise Agent Ready (GEAR), תוכלו לעיין במקורות מידע שיעזרו לכם ליצור ולפרוס סוכני AI ברמת הארגון.