הנאום המרכזי הבא של '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.

הערה: Gemini Cloud Assist נמצא כרגע בגרסת טרום-השקה פרטית. אתם לא צריכים להיכלל ברשימת ההיתרים כדי להריץ את ה-codelab הזה ב-Cloud Assist. כל השלבים ב-Cloud Assist מבודדים לשלב 8 (אופציונלי): שימוש ב-Cloud Assist Investigations – אם אין לכם עדיין גישה ל-Cloud Assist, דלגו על הדף הזה.

הדרישות

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

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

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

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

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

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

הגדרת הסביבה

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

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

gcloud auth login
gcloud auth application-default login

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

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

אם אתם נמצאים ברשימת ההיתרים ל-Gemini Cloud Assist (גרסת טרום-השקה פרטית), אתם צריכים להפעיל את ממשקי ה-API הנוספים האלה:

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 (סייר):

פותחים את 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

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

4. פריסת הסוכן של הסימולטור ל-Agent Runtime

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

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

uv sync

פריסה ל-Agent Runtime

1. מריצים את הפקודה 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...

רושמים את מזהה זמן הריצה של הסוכן שנוצר. תצטרכו את זה בהמשך!

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

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

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

1. עוברים אל מסוף Cloud Monitoring - Alerting.

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

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

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

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

שאילתת היומן הזו מחפשת יומנים של שגיאות בסוכן Agent Runtime, כאשר ReasoningEngine הוא שם ה-API הבסיסי של Agent Runtime.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

השלבים האלה רלוונטיים רק אם אתם נמצאים ברשימת ההיתרים של Gemini Cloud Assist (תצוגה מקדימה פרטית). אם לא, עוברים לדף הבא.

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

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

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

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

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

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

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

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

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

4. מזינים את ההנחיה הבאה ומקישים על 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 בתדירות מספקת כדי לסכם ביעילות את התשובות הענקיות של קריאות הכלים בכלי Simulator Agents.

כדי לפתור את הבעיה הזו, 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,
    ),
)

חשוב להגדיר את הערכים של token_threshold ושל event_retention_size.

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

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

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

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

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

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...

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

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

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

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

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

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

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

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

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

מחיקת המדיניות של Cloud Monitoring

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

12. 🎊 מזל טוב!

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

מה למדתם

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

השלבים הבאים

• מידע נוסף על Agent Runtime
• מידע נוסף על ערכה לפיתוח סוכנים (ADK)
• מידע נוסף על התראות ב-Cloud Monitoring
• מידע נוסף על Gemini Cloud Assist