פריסת סוכן ADK ל-Agent Runtime באמצעות Agents CLI

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

בשיעור Codelab הזה נסביר איך להעביר סוכן ADK 2.0 מסביבת פיתוח מקומית לפריסה ברמת ייצור. תשתמשו ב-agents-cli כדי לארוז, לאמת ולארח את תהליך העבודה מבוסס הגרף בשידור חי ב-Agent Runtime ב-Google Cloud.

כדי לבחון את תהליך הפריסה הזה, תיצרו אב טיפוס מקומי של הסוכן Ambient Expense Agent מאפס לפני שתפרסו אותו בענן. (למידע נוסף על תכנון הלוגיקה הבסיסית של הסוכן הזה, אפשר לעיין בסדנאות ה-Codelab הבסיסיות באתר האירועים של Kaggle). הסוכן Ambient Expense Agent מייעל את דיווח ההוצאות של העובדים על ידי אישור מיידי של תביעות רגילות, וסימון הוצאות גדולות יותר לבדיקה על ידי אדם. מתחת לפני השטח, הוא משתמש בתהליך עבודה מבוסס-גרף של ADK 2.0 כדי לתאם את השלבים האלה של אישורים אוטומטיים וניתוח סיכונים.

מה תלמדו

  • איך מכינים את פרויקט Ambient Expense Agent המקומי לאירוח בענן.
  • איך ליצור את קובצי התיאור של הפריסה ואת עטיפות הייצור הנדרשות.
  • איך מבצעים הרצות ניסיון ופורסים את הקוד ישירות אל Agent Runtime.
  • איך עוקבים אחרי עקבות הביצוע של סוכן הייצור באמצעות Cloud Trace.

הדרישות

  • פרויקט פעיל ב-Google Cloud עם חיוב מופעל.
  • gcloud SDK מותקן ומאומת.
  • מנהל החבילות uv מותקן.
  • ‫Google Antigravity IDE מותקן.

דרישות מוקדמות

ב-Codelab הזה אנחנו יוצאים מנקודת הנחה שאתם מכירים את הנושאים הבאים:

  • ניווט במערכת באמצעות טרמינל.
  • מושגים בסיסיים בפיתוח ב-Python.
  • מושגים בסיסיים ב-Google Cloud.

2. הגדרת הסביבה של Google Cloud

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

‫👉 Prompt Antigravity:

Help me set up my Google Cloud environment. Connect to my project
`YOUR_PROJECT_ID` in the global region, authenticate, and enable the necessary
generative platform APIs (aiplatform.googleapis.com, cloudtrace.googleapis.com,
cloudbuild.googleapis.com, agentregistry.googleapis.com).

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

3. הגדרת Agents CLI ו-ADK Skills

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

‫👉 מעתיקים את ההנחיה הבאה ומדביקים אותה ב-Antigravity:

Install the agents-cli toolchain and its ADK skills so you can help me build
an ADK agent. Run "uvx google-agents-cli setup", then confirm with
"agents-cli info" and tell me which skills are now available.

כש-Antigravity מריץ את ההנחיה הזו, הוא מריץ את הפקודה uvx google-agents-cli setup בטרמינל כדי להתקין את ה-CLI ואת היכולות הנלוות שלו. לאחר מכן, הוא מריץ את הפקודה agents-cli info כדי לאמת את ההתקנה ומציג את הכישורים החדשים של הדומיין (כמו google-agents-cli-deploy ו-google-agents-cli-workflow) ישירות בצ'אט.

4. יצירת פרויקט של סוכן

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

‫👉 Prompt Antigravity:

Use Agents CLI to build a local prototype for an ambient expense agent that
streamlines employee expense reporting by instantly approving standard claims
while flagging larger expenses for review. Ensure the graph workflow is
compatible with ADK 2.0 and includes an `auto_approve` node that automatically
approves expenses under $100, and a `review_agent` node that triggers a
human-in-the-loop pause (`RequestInput`) for expenses of $100 or more.

כש-Antigravity מריץ את ההנחיה הזו, הוא משתמש בכישורי ה-scaffolding שהותקנו לאחרונה כדי להריץ את agents-cli scaffold create expense-agent --adk בטרמינל. לאחר מכן, הוא יאמת את קוד האב-טיפוס שנוצר ויבצע בו התאמות כדי לוודא ש-expense-agent מיישם בצורה נכונה את סף האישור האוטומטי של $100 ואת תהליך הבדיקה שכולל התערבות אנושית, במסגרת תהליך העבודה הגרפי של ערכת פיתוח הסוכן (ADK).

5. הכנה לפריסה בסביבת הייצור

‫Agent Runtime הוא שירות מנוהל לחלוטין של Google Cloud שמאפשר לפרוס סוכני AI בסביבת ייצור, לנהל אותם ולהרחיב אותם. Agent Runtime מטפל במורכבויות התפעוליות של אירוח, ומציע סביבה עם שמירת מצב (stateful) עם תכונות כמו ניהול סשנים, זיכרון לטווח ארוך וארגז חול מאובטח להרצת קוד.

למה כדאי לבצע פריסה ל-Agent Runtime?

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

כשפורסים את הסוכן ב-Agent Runtime, תהליך העבודה מועבר לסביבת Google Cloud מנוהלת לחלוטין שפועלת כל הזמן. כך נוצרת נקודת קצה מאובטחת בשרת העורפי שפעילה מסביב לשעון. ב-Codelab הבא תבנו קצה קדמי לאינטרנט שמתחבר ישירות לנקודת הקצה הזו בענן, וכך תעניקו לסוכן שלכם כתובת URL ציבורית.

בנוסף, Agent Runtime מספק תשתית ייעודית שעברה אופטימיזציה במיוחד לסוכני AI, ומציע יכולות מובנות כמו:

  • ביצוע מנוהל עם שמירת מצב: ניהול סשנים מובנה ושמירת זיכרון לטווח ארוך לאורך תפניות בשיחה.
  • ארגז חול מאובטח: הרצת קוד שנוצר על ידי סוכן וקריאות דינמיות לכלים בסביבות מבודדות באופן בטוח.
  • ניראות (observability) ברמת הארגון: סטרימינג של טלמטריה מוכן לשימוש ישירות אל Cloud Trace ו-Cloud Logging.

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

‫👉 Prompt Antigravity:

Scaffold the production deployment files for Agent Runtime.

כש-Antigravity מריץ את ההנחיה הזו, הוא מריץ את agents-cli scaffold enhance --deployment-target agent_runtime --yes בספריית הבסיס של הפרויקט. הפקודה הזו סורקת את הספרייה ויוצרת באופן אוטומטי:

  • ‫app/agent_runtime_app.py: עטיפת השירות ברמת הייצור.
  • ‫deployment_metadata.json: סכימת הפריסה שמשמשת את Agent Runtime להתחלת הרצת משאבים.

הלוגיקה המרכזית של הסוכן ב-app/agent.py נשארת ללא שינוי ושמורה.

6. אריזה ואימות מקומי

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

‫👉 Prompt Antigravity:

Lock my python dependencies and run a dry-run deployment to check for any
configuration or dependency issues.

כש-Antigravity מריץ את ההנחיה הזו, הוא קודם מריץ את הפקודה uv lock במסוף כדי ליצור קובץ נעילה דטרמיניסטי, וכך לוודא שגרסאות הספריות בענן עקביות. לאחר מכן, המערכת מריצה את agents-cli deploy --dry-run כדי לאמת את תוקף ההגדרה ולראות תצוגה מקדימה של שלבי הפריסה בלי להקצות משאבי ענן. אפשר לעיין בפלט של ההרצה היבשה במסוף כדי לוודא שכל הקבצים וההגדרות נכונים.

7. פריסה ל-Agent Runtime

פורסים את סוכן ההוצאות במצב אווירה ב-Agent Runtime.

‫👉 Prompt Antigravity:

Deploy this agent to Agent Runtime.

כש-Antigravity מבצע את ההנחיה הזו, הוא מפעיל את מיומנות google-agents-cli-deploy ומריץ את agents-cli deploy --project YOUR_PROJECT_ID --region us-west1. תהליך האריזה, ההעלאה והקצאת Agent Runtime נמשך בדרך כלל 5-10 דקות. ‫Antigravity יעקוב אחרי התקדמות הפריסה במסוף, וכשהיא תסתיים, יוצג URL של נקודת הקצה הפעילה.

💡 טיפ למקצוענים (ניהול חלונות זמן קצובים לתפוגה): אם אתם מעדיפים לא לנעול את המסוף במהלך פריסות ארוכות, אתם יכולים להנחות את Antigravity להשתמש בדגל --no-wait כדי להתחיל את הפריסה באופן אסינכרוני, ולבדוק את ההתקדמות מאוחר יותר באמצעות agents-cli deploy --status.

8. בדיקת הסוכן

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

‫👉 מבקשים מ-Antigravity לאמת את המנוע שמוטמע בשידור חי:

Test my deployed Agent Runtime engine with two test cases: first a standard
meal expense of $50 to verify automatic approval, and second, a client dinner
expense of $150 to verify that the human-in-the-loop pause is triggered.

אפשר גם לבדוק את הסוכן באופן ידני באמצעות תצוגה מקדימה של Cloud Console Playground. כדי לפתוח את המגרש:

  1. בתפריט הניווט של מסוף Google Cloud, בוחרים באפשרות Agent Platform (פלטפורמת הסוכנים) > Deployments (פריסות).
  2. בוחרים את הסוכן שפרסתם מרשימת הפריסות.
  3. לוחצים על הלחצן Playground כדי לפתוח את ממשק הצ'אט האינטראקטיבי לבדיקה.

‫👉 כדי לבדוק את האישור האוטומטי (עד 100$), מעתיקים את מטען ה-JSON הייעודי הבא לתיבת הצ'אט:

{"data": {"amount": 50.0, "submitter": "user@example.com", "category": "meals", "description": "Lunch", "date": "2026-06-04"}}

אתם אמורים לקבל תגובת JSON שבה מוצג הפלט של הצומת auto_approve עם הסטטוס 'אושר'.

תגובת JSON שמראה אישור אוטומטי של הוצאה בסך 50$.

‫👉 כדי לבדוק את התהליך של Human-in-the-Loop (HITL), מדביקים את מטען ה-JSON הייעודי הבא.

{"data": {"amount": 150.0, "submitter": "user@example.com", "category": "meals", "description": "Client dinner", "date": "2026-06-04"}}

הפעולה הזו תפעיל את הסוכן review_agent, תציג את אזהרת ההתראה ואז תשהה את ההרצה ותציג RequestInput (Human-in-the-loop) כדי לבקש אישור.

תגובת JSON עם בקשה למידע נוסף על הוצאה בסך 150$.

9. מעקב ותצפית על סוכן הייצור

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

  1. בדיקת עקבות: פותחים את מסוף Cloud Trace כדי לבדוק מפות של עסקאות בזמן אמת, לנתח את זמני האחזור ולראות את שלבי ההפעלה של הכלי.
  2. יומני ביקורת: אפשר להשתמש ב-Cloud Logging כדי לבדוק את הפלט הרגיל ואת עקבות המחסנית של האבחון בזמן אמת.

מסוף Cloud Logging שבו מוצג אישור להוצאה בסך 50$.

  1. נתונים מצטברים מ-Analytics: אם ההגדרה --bq-analytics הופעלה במהלך יצירת התשתית, אפשר להריץ שאילתות ביומנים ב-BigQuery באמצעות SQL כדי לראות את יחסי האישור ואת מגמות התפתחות השיחות.

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

SELECT
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')) AS approved_count,
  COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)rejected')) AS rejected_count,
  COUNT(1) AS total_processed,
  SAFE_DIVIDE(COUNTIF(REGEXP_CONTAINS(response_text, r'(?i)approved')), COUNT(1)) AS approval_ratio
FROM
  `[YOUR_PROJECT_ID].[YOUR_DATASET_ID].v_agent_response`
WHERE
  agent = 'expense_processor';

10. (אופציונלי) אימות הרישום ב-Agent Registry

כדי לאפשר לשירותים, למפתחים או לסוכנים אחרים בארגון שלכם לגלות את סוכן ההוצאות שלכם ולהשתמש בו בצורה בטוחה, צריך לרשום אותו במרשם הסוכנים של הארגון (Gemini Enterprise).

הפריסה של הסוכן ל-Agent Runtime גורמת לרישום אוטומטי שלו ב-Agent Registry. כל עדכון או מחיקה של הסוכן שלכם ב-Agent Runtime יסתנכרנו אוטומטית גם עם Agent Registry.

‫👉 מבקשים מ-Antigravity לאמת את הרישום האוטומטי של הסוכן:

Verify that my deployed expense agent is automatically registered in the Gemini
Enterprise Agent Registry.

כש-Antigravity מריץ את ההנחיה הזו, הוא מריץ את agents-cli publish gemini-enterprise --list בטרמינל. השאילתה הזו מחפשת במאגר הסוכנים ומציגה רשימה של כל סוכני Gemini Enterprise הרשומים בפרויקט, כדי שתוכלו לוודא שסוכן הוצאות הסביבה פעיל וניתן לאיתור בכל הארגון.

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

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

‫👉 Prompt Antigravity:

Clean up all my deployed cloud resources. Use the Agent Runtime ID from
deployment_metadata.json to delete the engine from Vertex AI, remove the local
deployment_metadata.json file, and delete the container image repository from
Artifact Registry.

כשמריצים את ההנחיה הזו ב-Antigravity, התהליך כולו של ניקוי המשאבים מתבצע באופן אוטומטי:

  1. מחיקת הסוכן שפרסתם: התהליך מתחיל בקריאה של deployment_metadata.json כדי לקבל את מזהה זמן הריצה של הסוכן המרוחק, ואז מוחק באופן אוטומטי את מופע המנוע הפעיל מ-Vertex AI.
  2. ניקוי סביבת העבודה המקומית: הפקודה הזו מסירה את קובץ deployment_metadata.json הלא פעיל מהתיקייה הראשית של הפרויקט.
  3. ניקוי Artifact Registry: הפקודה gcloud artifacts docker images delete מופעלת כדי להסיר מ-Artifact Registry את קובצי האימג' של הקונטיינרים שנוצרו, וכך לפנות מקום באחסון בענן.

12. מזל טוב

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

מה למדתם

  • הגדרה של Google Cloud: הגדרת פרטי הכניסה לפרויקט והפעלת ממשקי ה-API הנדרשים של הפלטפורמה.
  • כלים ומיומנויות: התקנה של agents-cli וטעינה של מיומנויות נלוות של ADK ב-Antigravity.
  • Production Scaffolding: פיגומים של Agent Runtime שנוצרו עבור סוכן ADK 2.0.
  • אימות מקומי: יצירת קובצי נעילה דטרמיניסטיים (uv lock) והרצת בדיקות ללא שינוי.
  • פריסה בענן: אירוח הסוכן שלכם בשידור חי בתשתית מנוהלת של Agent Runtime.
  • יכולת צפייה וניתוח: מעקב אחר ביצוע ב-Cloud Trace וניתוח טלמטריה ב-BigQuery.
  • גילוי ארגונים: רישום אוטומטי מאומת במאגר הסוכנים של הארגון.

מה השלב הבא?

  • ביצוע ניתוח ב-BigQuery: אפשר להריץ שאילתות ביומני הטלמטריה של הסוכן ב-BigQuery כדי לנתח את יחסי האישור ומגמות של תחלופת מידע בשיחה לאורך זמן.
  • ‫Vibe to Live Codelab: שימוש ב-Google Antigravity כדי לפתח לקוח frontend ב-Cloud Run ולחבר אותו ישירות לנקודת הקצה של ה-backend של Agent Runtime בשידור חי.

איך מקבלים את התג Kaggle 5-Day AI Agents 🎉

השלמתם את שיעור ה-Lab הזה כחלק מקורס אינטנסיבי בן 5 ימים בנושא סוכני AI: כתיבת קוד עם Google ב-Kaggle? לקבלת תג על השלמת הקורס:

איך מקבלים את התג 5-Day AI Agents

קובצי עזר