הנאום המרכזי הבא של '26 Developer Keynote: Debugging Agents At Scale'

1. מבוא

ב-Codelab הזה נסביר איך לנפות באגים בסוכני AI שפועלים ב-Google Cloud. תפרסו סוכן סימולטור ב-Agent Runtime, תשתמשו ב-Cloud Observability כדי לזהות בעיות, ותשתמשו ב-Gemini Cloud Assist וב-Antigravity IDE כדי לזהות את שורש הבעיה ולתקן שגיאות בזמן אמת.

קשת

ההנחה של ההדגמה הזו היא שרק הוספנו את ADK EventCompaction לסוכן Simulator. כך הסימולטור יכול לסכם מעת לעת את תהליך העבודה שלו באמצעות Gemini, ולצמצם את ההקשר הכולל שנשלח למודל בכל תור – וכך לשפר את איכות התשובות ולהפחית את העלויות הכוללות. אבל נגלה שיש באג ב-EventCompactionConfig שגורם לשגיאות בסוכן. ב-Codelab הזה נסביר איך אפשר למצוא בעיה כזו ולפתור אותה במהירות.

דחיסה

הפעולות שתבצעו:

פורסים את סוכן סימולטור המרתון אל Agent Runtime.
מגדירים התראה ב-Cloud Monitoring כדי לזהות שגיאות בסוכן.
חקירת שגיאות באמצעות Cloud Trace ו-Gemini Cloud Assist.
מאתרים את שורש הבעיה ומטפלים בה באמצעות Antigravity ו-MCP.

הדרישות

דפדפן אינטרנט כמו Chrome.
חשבון Google
‫Antigravity (תומך ב-Mac,‏ Linux ו-Windows)
‫Python 3.13 ואילך.
‫uv (כלי לניהול חבילות Python)

משך משוער: 45 דקות

עלות משוערת: פחות מ-5$

‫2. לפני שמתחילים

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

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

הגדרת הסביבה

פותחים את Antigravity ונכנסים לחשבון. אחר כך פותחים Terminal על ידי הקשה על cmd-shift-P (או על ctrl-shift-P) והקלדה של 'Create New Terminal' (יצירת Terminal חדש).

טרמינל

בטרמינל, מבצעים אימות ב-Google Cloud:

gcloud auth login
gcloud auth application-default login

מגדירים את מזהה הפרויקט:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
gcloud auth application-default set-quota-project $PROJECT_ID

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

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

gcloud services enable \
 aiplatform.googleapis.com \
 logging.googleapis.com \
 apphub.googleapis.com \
 cloudtrace.googleapis.com \
 telemetry.googleapis.com

gcloud services enable \
 geminicloudassist.googleapis.com \
 cloudaicompanion.googleapis.com

3. הגדרת הסוכן של הסימולטור

בשלב הזה, תשכפלו את מאגר ההדגמה ותגדירו את משתני הסביבה של סוכן הסימולטור.

שכפול המאגר

משכפלים את מאגר next-26-keynotes ועוברים לספריית ההדגמה:

git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/debugging-agents

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

הסוכן של הסימולטור משתמש בקובץ .env לצורך הגדרה.

מאתרים את הקובץ sample.env בצד ימין של חלון Antigravity (סייר):

explorer, אקספלורר

פותחים את sample.env ומעדכנים את השדה GCP_PROJECT_ID עם מזהה הפרויקט בפועל ב-Google Cloud. הקובץ אמור להיראות כך:

GCP_PROJECT_ID="YOUR_PROJECT_ID"
GCP_LOCATION="us-central1"
GOOGLE_GENAI_USE_VERTEXAI=TRUE
USE_VERTEXAI_SESSION_SERVICE=true
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false

4. פריסת הסוכן של הסימולטור בזמן ריצה של סוכן

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

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

uv sync

פריסה לזמן ריצה של סוכן

מריצים את הפקודה adk deploy. בשלב הזה, הסוכן שלכם נארז ונפרס ב-Google Cloud (Agent Runtime).

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

התהליך עשוי להימשך עד 5 דקות. בסופו של דבר אמור להופיע פלט כמו זה:

✅ Created Agent Runtime:
projects/1234567890/locations/us-central1/reasoningEngines/9876543210...

פותחים את מסוף Agent Runtime בדפדפן אינטרנט. אמור להופיע simulator_agent שפועל בזמן ריצה של סוכן, עם אוסף טלמטריה מופעל.

5. הגדרת מדיניות התראות

כדי לזהות שגיאות בזמן הריצה של הסוכן באופן אוטומטי, צריך ליצור התראה מבוססת-יומן במסוף Google Cloud.

עוברים אל המסוף Cloud Monitoring – Alerting.

לוחצים על עריכת ערוצי התראות. גוללים למטה לסוג Email ויוצרים ערוץ התראות באימייל כדי לשלוח לכתובת האימייל האישית. לוחצים על שמירה.

חוזרים למרכז הבקרה של ההתראות ולוחצים על Create Policy.
בצד ימין של המסך, לוחצים על יצירת התראה מבוססת-יומן.

תופנו אל Log Explorer. מדביקים את שאילתת היומן הבאה ומחליפים את הערך במזהה הפרויקט.

resource.type="aiplatform.googleapis.com/ReasoningEngine"
logName="projects/<YOUR_PROJECT_ID>/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr"
"ERROR"

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

הגדרת התראה שמבוססת על יומן. נותנים להתראה שם (כל שם), ואז מגדירים את רמת החומרה כשגיאה.

לוחצים על הבא בקטע 'הגדרת תדירות ההתראות' (משאירים את הגדרות ברירת המחדל).

בקטע מי צריך לקבל התראה?, מגדירים את ההתראה כך שתפעיל את ערוץ ההתראות באימייל שהגדרתם (כלומר, My Email).
לוחצים על שמירה.

6. הפעלת האירוע

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

במסוף Google Cloud, עוברים אל מסוף Agent Runtime.
לוחצים על simulator_agent.
בסרגל הכלים העליון, לוחצים על Playground (ארגז חול). תתחיל שיחה חדשה עם סוכן ADK.

בחלון הצ'אט של הסשן, מקלידים Test Simulation ומקישים על Enter כדי לשלוח את ההנחיה.

הפעולה הזו תתחיל את סימולציית המרתון, שבה אלפי רצים וירטואליים ירוצו במסלול המתוכנן. אפשר לראות כמה קריאות לכלים get_runner_telemetry ו-analyze_medical_risk, כי הסימולציה מעריכה כמה 'אזורים' של המירוץ.

תוך דקה בערך, אמור להגיע אימייל לתיבת הדואר הנכנס שלכם, עם התראה על אירוע חדש בסוכן.

לוחצים על View Incident (הצגת האירוע) כדי לפתוח את מסוף Cloud Monitoring. כדי לבדוק את הבעיה ב-Console, עוברים לדף הבא.

7. בדיקת האירוע במסוף

מעיינים באירוע במסוף Cloud Monitoring. אמורים להופיע יומני שגיאות שמגיעים מסוכן הסימולטור.

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

פותחים שוב את מסוף Agent Runtime. לוחצים על simulator_agent ופותחים את הכרטיסייה Traces.

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

לוחצים על הטווח האחרון בתצוגת המעקב. הוא אמור להיות אדום.
לוחצים על Stacktrace. יוצגו לכם יומני שגיאות שקשורים לקריאה למודל Gemini API. באופן ספציפי, שגיאה מסוג 400: Invalid Argument. האות הזה מצביע על בעיה ברמת הבקשה במטען הייעודי (payload) שסוכן הסימולטור שלח אל Gemini API.

8. [אופציונלי] שימוש ב-Cloud Assist Investigations לניפוי באגים

בטווח הזמן שבו התרחשה השגיאה, לוחצים על יומנים ואירועים. מחפשים את יומן הרישום Exception (חריגה) עם לחצן הניצוץ שלצידו. אחר כך לוחצים על חקירת יומן.

פעולה זו תתחיל חקירה של Cloud Assist בסרגל צד בצד ימין של המסך. טעינת הדף תימשך כ-3 עד 5 דקות.

אחרי שהתהליך מסתיים, פותחים את החקירה.

לעיון בסיכום החקירה

גוללים למטה וצופים בהיפותזות. ‫Gemini Cloud Assist אמור לזהות את השורה הספציפית בקובץ agent.py של הסוכן Simulator שגורמת לשגיאה 400 ב-Gemini API.

כדי להגיע לשורש הבעיה, נפתח את קוד המקור של הסוכן שלנו ונשתמש ב-Antigravity. ממשיכים לדף הבא.

9. שימוש ב-Antigravity כדי לזהות את שורש הבעיה ולתקן אותה

פותחים מחדש את Antigravity.
פותחים את המרכז לניהול נציגים בפינה השמאלית העליונה של המסך.

מוודאים שהמודל שמוגדר הוא Gemini 3 Flash ושהמצב הוא תכנון.

מזינים את ההנחיה הבאה ומקישים על Enter.

Why is the Simulator Agent failing to run in Agent Engine? 
We just added Events Compaction to the agent - could that be the cause? Search the ADK Python GitHub repository for relevant GitHub issues. https://github.com/google/adk-python/issues  - including issues that have been closed. 

For instance, you could query: is:issue eventscompactionconfig does not trigger summarization

Also look closely at the EventsCompactionConfig in agent.py.

אמור להופיע קטע שבו Antigravity בודק את הקוד ב-agent.py ומחפש בעיות רלוונטיות ב-GitHub:

הסיבה הבסיסית לשגיאת 400 ב-Gemini API היא שחורגים ממגבלת הטוקנים של הקשר הקלט של Gemini 3 Flash, שהיא בערך מיליון. הסיבה לכך היא שאנחנו לא מפעילים את EventCompaction בתדירות מספקת כדי לסכם ביעילות את התשובות הענקיות של קריאות הכלים של סוכני הסימולטור.

כדי לפתור את הבעיה הזו, Antigravity צריך להציע להוסיף פרמטר token_threshold ל-EventsCompactionConfig, כדי לדחוס את ההקשר בתוך כל הפעלה מדי פעם אחרי שמגיעים למספר מסוים של טוקנים.

הפתרון הזה תואם לפתרון שמוצע בבעיה הזו ב-GitHub.

החלת התיקון על agent.py.

מוודאים שמוצג משהו דומה לזה:

app = App(
    name="simulator_agent",
    root_agent=root_agent,
    events_compaction_config=EventsCompactionConfig(
        compaction_interval=3,
        overlap_size=1,
        summarizer=summarizer,
        token_threshold=200000,
        event_retention_size=2,
    ),
)

10. פריסה מחדש ואימות התיקון

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

פותחים את Antigravity –> New Terminal (טרמינל חדש).
מגדירים משתני סביבה. הערך של AGENT_RUNTIME_ID צריך להיות שם המשאב המלא של simulator_agent. אפשר למצוא את המידע הזה במסוף Agent Runtime – רשימת הסוכנים.

export AGENT_RUNTIME_ID="projects/x/locations/us-central1/reasoningEngines/x"
export PROJECT_ID="your-project-id"

פורסים מחדש את הסוכן:

uv run adk deploy agent_engine \
    --project="$PROJECT_ID" \
    --region="us-central1" \
    --otel_to_cloud \
    --agent_engine_id="$AGENT_RUNTIME_ID" \
    --env_file="sample.env" \
    --adk_app_object=app \
    simulator_agent

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

✅ Updated agent engine: projects/xxx/locations/us-central1/reasoningEngines/...
Cleaning up the temp folder: simulator_agent_tmp...

פותחים את מסוף Agent Runtime. פותחים מחדש את simulator_agent. לוחצים על Playground.
כותבים את אותה הנחיה: Test Simulation ואז מקישים על Enter.
הסימולציה המלאה של Marathon בשרת העורפי אמורה להימשך כמה דקות. אמורות להופיע כמה קריאות לכלים. בסופו של דבר, אמורה להתקבל תגובה כזו:

המשמעות היא שהסימולטור פעל בהצלחה. ✅

פותחים את תצוגת המעקב של סשן ה-ADK.
אמורים להופיע כל המקטעים 'הכחולים', ללא שגיאות אדומות. שימו לב שמספר הטוקנים הכולל בסשנים חורג מהמגבלה של מיליון טוקנים בהקשר של Gemini API. זה בסדר, כי עכשיו EventCompaction פועל מספיק פעמים בכל הפעלה, כדי לא לחרוג ממגבלת ההקשר הכוללת של קריאות למודלים בודדים.

🎊 איזה כיף! תיקנו את השגיאה בסוכן של הסימולטור!

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

כדי להימנע מחיובים בחשבון Google Cloud, מוחקים את המשאבים שנוצרו במהלך ה-codelab הזה.

מחיקת אפליקציית Agent Runtime

אפשר למחוק את המופע של Reasoning Engine דרך המסוף או באמצעות הפקודה gcloud (אם יש לכם את שם המשאב). כדי לפשט את התהליך, אפשר להשתמש במסוף:

עוברים לדף Agent Runtime.
בוחרים באפשרות simulator_agent –> לוחצים על סמל האפשרויות הנוספות (3 נקודות) בצד שמאל.
לוחצים על מחיקה.

מחיקת מדיניות Cloud Monitoring

נכנסים למסוף Cloud Monitoring -> Alerting.
גוללים למטה אל Policies (מדיניות) ולוחצים על סמל האפשרויות הנוספות (שלוש נקודות) כדי Delete (למחוק) את המדיניות.

12. 🎊 מזל טוב!

מעולה! הרגע סיימתם בהצלחה ניפוי באגים של סוכן AI ב-Google Cloud.

מה למדתם

איך פורסים סוכנים ל-Agent Runtime.
איך לזהות שגיאות באמצעות התראות של Cloud Monitoring.
איך בודקים אירועים פעילים באמצעות Cloud Logging ותצוגת המעקב של Agent Runtime.
איך חוקרים כשלים באמצעות Gemini Cloud Assist.
איך משתמשים ב-Antigravity כדי לזהות את שורש הבעיה ולתקן באגים בסוכן.
איך משפרים את דחיסת האירועים ב-ADK כדי לטפל בפניות של סוכנים שדורשות שימוש רב בכלים ונמשכות זמן רב.