‫Agentverse - The Shadowblade's Codex - Vibecoding with Gemini CLI

1. של גורל

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

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

הסדנה הזו היא מדריך מקיף לארגונים שרוצים להתכונן לעתיד של AI אקטיבי ב-Google Cloud. אנחנו מספקים מפת דרכים מקיפה שתעזור לכם לעבור מהרעיון הראשוני למציאות תפעולית מלאה. בארבעת שיעורי ה-Lab האלה, שקשורים זה לזה, תלמדו איך הכישורים המיוחדים של מפתח, ארכיטקט, מהנדס נתונים ו-SRE צריכים להתחבר כדי ליצור, לנהל ולהרחיב את Agentverse.

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

ברוכים הבאים ל-Agentverse: קריאה לאלופים

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

המערכת האקולוגית המחוברת הזו של כוח ופוטנציאל נקראת Agentverse.

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

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

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

בחירת כיתה

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

• ‫Shadowblade (מפתח): אומן הנפחות והחזית. אתם האומנים שמייצרים את הלהבים, בונים את הכלים ומתמודדים עם האויב בפרטים המורכבים של הקוד. המסלול שלך הוא מסלול של דיוק, מיומנות ויצירה מעשית.
• המזמן (האדריכל): אסטרטג ומנהל פרויקטים מנוסה. אתם לא רואים סוכן יחיד, אלא את כל שדה הקרב. אתם מעצבים את תוכניות האב שמאפשרות למערכות שלמות של סוכנים לתקשר, לשתף פעולה ולהשיג מטרה גדולה בהרבה מכל רכיב בודד.
• המלומד (מהנדס נתונים): מחפש את האמת הנסתרת ושומר על החוכמה. אתם יוצאים למסע אל מרחבי הנתונים העצומים והפראיים כדי לחשוף את התובנות שיעזרו לסוכנים שלכם להבין את המטרה ולראות את התמונה המלאה. הידע שלכם יכול לחשוף חולשה של אויב או להעצים את היכולות של בעל ברית.
• ‫The Guardian (DevOps / SRE): המגן הנאמן והמגן של הממלכה. אתם בונים את המבצרים, מנהלים את קווי האספקה של החשמל ומוודאים שהמערכת כולה יכולה לעמוד בפני המתקפות הבלתי נמנעות של הסטטיק. החוזק שלכם הוא הבסיס לניצחון של הצוות.

המשימה שלך

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

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

אתגר אחרון ושיתופי שיבחן את הכוח המשולב שלכם ויקבע את גורל ה-Agentverse.

עולם הסוכנים מחכה לגיבורים שלו. רוצה לענות לשיחה?

2. The Shadowblade's Codex

הקודקס של Shadowblade פתוח לפניך. עונים לשיחה. הסדר בעולם של Agentverse מופרע על ידי הכאוס המתפשט של The Static, ורק מי שישלוט בטכניקות שמופיעות בקודקס הזה יוכל להילחם בו. זו דרך שדורשת דיוק ומשמעת. היום מתחיל האימון שלך. תלמדו להשתמש ב-AI לא ככלי פשוט, אלא כלהב בעל תבונה שצריך לאלף ולשלוט בו. אם תפעלו לפי ההוראות במאמר הזה, תוכלו ליצור כלי של לוגיקה טהורה – סוכן חכם, מושחז ומוכן לקרב.

מה תלמדו

• הנשק העיקרי שלכם: Gemini CLI.
• הרחיבו את ארגז הכלים שלכם באמצעות תוספים ל-Gemini CLI ומיומנויות של סוכנים.
• אפשר לשלב כלי MCP עם Gemini CLI כדי להשתמש בכלים חיצוניים.
• אתם יכולים להשתמש במסמכי עיצוב כדי להעביר את הכוונה שלכם ל-AI Partner וליצור 'אווירה'.
• אתם יכולים ליצור פתרון נקי ומודולרי על ידי בניית הסוכן האוטונומי הראשון שלכם באמצעות הערכה לפיתוח סוכנים (ADK).
• אפשר להשתמש ב-hooks כדי ליירט את ההתנהגות של הסוכן ולשמור עליה.
• בניית חבילות של בדיקות אוטומטיות כדי לבדוק ולאמת את הסוכן.
• יצירת צינור CI מלא לבדיקה אוטומטית, להעברה לקונטיינר ולארכיון של הסוכן.

3. הכנת אזור האימונים

מימוש קרדיט ב-Google Cloud

⚠️ דרישות מוקדמות חשובות:

• שימוש בחשבון Gmail לשימוש אישי: אתם צריכים להשתמש בחשבון לשימוש אישי (לדוגמה, [e-mail]). חשבונות שמנוהלים על ידי חברה או מוסד לימודים לא יפעלו.

👉 שלבים:

1. כניסה לאתר למימוש הקרדיט: לוחצים כאן
2. כניסה: מדביקים את הקישור בשורת הכתובת ונכנסים באמצעות חשבון Gmail אישי.
3. אישור התנאים: מאשרים את התנאים וההגבלות של Google Cloud Platform.
4. אימות הזיכוי: מחפשים הודעה שמאשרת שהזיכוי הוחל.
   • *הערה: אם תתבקשו להזין את פרטי כרטיס האשראי, תוכלו להתעלם מהבקשה ולסגור את החלון.

אפשר לסגור את החלון.

הגדרת סביבת העבודה

‫👈 לוחצים על 'הפעלת Cloud Shell' בחלק העליון של מסוף Google Cloud (הסמל בצורת מסוף בחלק העליון של חלונית Cloud Shell),

‫👈 לוחצים על הלחצן 'פתיחת הכלי לעריכה' (הוא נראה כמו תיקייה פתוחה עם עיפרון). ייפתח חלון עם Cloud Shell Code Editor. בצד ימין יופיע סייר הקבצים.

‫👈פותחים את הטרמינל בסביבת הפיתוח המשולבת (IDE) בענן,

‫👈💻 בטרמינל, מוודאים שכבר עברתם אימות ושהפרויקט מוגדר למזהה הפרויקט שלכם באמצעות הפקודה הבאה:

gcloud auth list

‫👈💻 משכפלים את פרויקט האתחול מ-GitHub:

git clone https://github.com/weimeilin79/agentverse-developer.git
chmod +x ~/agentverse-developer/gitea.sh
chmod +x ~/agentverse-developer/init.sh
chmod +x ~/agentverse-developer/set_env.sh

git clone https://github.com/weimeilin79/agentverse-dungeon.git
chmod +x ~/agentverse-dungeon/run_cloudbuild.sh
chmod +x ~/agentverse-dungeon/start.sh

‫👈💻 מריצים את סקריפט ההגדרה מהספרייה של הפרויקט.

⚠️ הערה לגבי מזהה הפרויקט: התסריט יציע מזהה פרויקט שנוצר באופן אקראי כברירת מחדל. אפשר להקיש על Enter כדי לאשר את ברירת המחדל.

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

cd ~/agentverse-developer
./init.sh

התסריט יטפל אוטומטית בשאר תהליך ההגדרה.

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

1. נכנסים לכתובת console.cloud.google.com.
2. לוחצים על התפריט הנפתח של בורר הפרויקטים בחלק העליון של הדף.
3. לוחצים על הכרטיסייה All (הכול) (כי יכול להיות שהפרויקט החדש עדיין לא יופיע ב-Recent (אחרונים)).
4. בוחרים את מזהה הפרויקט שהגדרתם בשלב init.sh.

‫👈💻 חוזרים לטרמינל. מגדירים את מזהה הפרויקט הנדרש:

gcloud config set project $(cat ~/project_id.txt) --quiet

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

gcloud services enable  compute.googleapis.com \
                        artifactregistry.googleapis.com \
                        run.googleapis.com \
                        cloudfunctions.googleapis.com \
                        cloudbuild.googleapis.com \
                        iam.googleapis.com \
                        aiplatform.googleapis.com \
                        cloudresourcemanager.googleapis.com

‫👈💻 אם עדיין לא יצרתם מאגר Artifact Registry בשם agentverse-repo, מריצים את הפקודה הבאה כדי ליצור אותו:

. ~/agentverse-developer/set_env.sh
gcloud artifacts repositories create $REPO_NAME \
    --repository-format=docker \
    --location=$REGION \
    --description="Repository for Agentverse agents"

הגדרת הרשאות

‫👈💻 מעניקים את ההרשאות הנדרשות על ידי הרצת הפקודות הבאות בטרמינל:

. ~/agentverse-developer/set_env.sh

# Artifact Registry Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/artifactregistry.admin"

# Cloud Build Editor
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/cloudbuild.builds.editor"

# Cloud Run Admin
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/run.admin"

# IAM Service Account User
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/iam.serviceAccountUser"

# Vertex AI User
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/aiplatform.user"

# Logging Writer (to allow writing logs)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/logging.logWriter"


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/logging.viewer"

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

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-dungeon
./run_cloudbuild.sh

npm update -g @google/gemini-cli

4. שליטה בנשק העיקרי שלכם: מבוא ל-Gemini CLI

כדי להשתמש בכלי הנשק המתקדמים והמיוחדים מתוך ארסנל השרת של MCP, קודם צריך לשלוט בנשק העיקרי: Gemini CLI. זהו הלהב הכי רב-תכליתי שלכם, שיכול לעצב את העולם הדיגיטלי באמצעות הפקודות שלכם. התרגילים האלה יעזרו לכם להכיר את הטיפול הבסיסי ואת היכולות של המערכת.

ממשק שורת הפקודה (CLI) של Gemini הוא יותר מכלי, הוא הרחבה של הרצון שלכם. סוכן ה-AI הזה בקוד פתוח, שמבוסס על מודלים של Gemini, פועל בלולאה של 'הסבר ופעולה' (ReAct). הוא מנתח את הכוונה שלכם, בוחר את הטכניקה המתאימה, מבצע אותה ובוחן את התוצאה כדי להשלים משימות מורכבות. כדי להשתמש בנשקים מיוחדים יותר, צריך קודם לשלוט בלהב העיקרי הזה.

איך מתחילים להשתמש ב-Gemini CLI

‫👈💻 נכנסים למגרש האימונים ושולפים את הנשק. בטרמינל של Cloud Shell, עוברים אל ארסנל הנשקים האישי.

cd ~/agentverse-developer
mkdir tabletop
cd tabletop

‫👈💻 מזמנים את Gemini בפעם הראשונה. הוא ינחה אתכם בתהליך ההתאמה הראשוני.

clear
gemini 

אם מוצגת השאלה Do you want to connect Cloud Shell editor to Gemini CLI?, בוחרים באפשרות לא.

היכרות עם נשק

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

‫👈✨ לכל כלי מכושף יש רונות שמתארות את הכוח שלו. כדאי לקרוא אותם עכשיו. בהנחיה ל-Gemini, מקלידים:

/help

בודקים את רשימת הפקודות. אלה הטכניקות הבסיסיות לניהול הזיכרון (focus), השיחה (chat) והארסנלים החיצוניים (tools). זהו מדריך הקרב שלכם.

‫👈✨ הנשק שלכם מותאם לסביבה, ומאפשר לכם לשנות את שדה הקרב באופן ישיר. שולחים פקודה לעולם שמחוץ ל-blade:

!ls -l

‫👈✨ ל-Gemini CLI יש קבוצה משלו של יכולות מובנות. כדי לבדוק אותם:

/tools

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

‫👉✨ אפשר גם לשפר את הלהב באמצעות תוספים – קסמים מוכנים מראש שנוצרו על ידי מומחים אחרים, שכוללים כלים, פקודות והקשר בחבילה אחת שניתנת להתקנה. בודקים אילו תוספים מותאמים כרגע לחלונית:

/extensions list

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

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

/skills list

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

‫👈✨ נשק יעיל רק אם מתמקדים בו כמו שצריך. ה-Gemini Blade יכול להכיל 'מודעות טקטית' (הקשר) כדי להנחות את הפעולות שלו.

/memory show

הוא ריק כרגע, כמו דף חלק.

‫👉✨ תרשום בזיכרון את הנתונים הטקטיים הבאים:

/memory add "The Shadowblade's primary foe is The Static."

מריצים שוב את /memory show כדי לוודא שהלהב ספג את הידע הזה.

‫👉✨ כדי שהנשק יהיה יעיל, הוא צריך להבין את המשימה. הסמל @ מורה ללהב לנתח את המידע. קודם יוצרים קובץ תדרוך למשימה:

!echo "## Mission Objective: Defeat the Seven Spectres" > mission.md

‫👈✨ עכשיו, מזינים פקודה ל-Gemini CLI כדי לנתח את התדרוך ולדווח על הממצאים:

Explain the contents of the file @mission.md

הנשק העיקרי שלכם מודע עכשיו למטרה שלו.

‫👈💻 לוחצים על Ctrl+C פעמיים כדי לצאת מ-Gemini CLI

5. Analyzing the Battlefield: Practical Vibe Coding Interaction

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

בפרק הזה נסביר איך עוברים מתיאוריה לפרקטיקה. קודם כול, תצטרכו לבסס את הנוכחות שלכם ב-Agentverse על ידי מתן פקודה ל-Gemini blade ליצור את חותם היצרן שלכם – חתימה דיגיטלית בצורה של אתר אישי, שנבנה מאפס על סמך הכוונה שלכם. לאחר מכן, תוכלו להרחיב את היכולות שלכם על ידי הפעלת ארסנל מקומי של כלים מתקדמים – שרת MCP – והתאמת הלהב לתדר שלו, מה שיאפשר לכם לבצע תמרונים מורכבים כמו ניהול מאגרי קוד באמצעות פקודות פשוטות ונחרצות.

יצירת סימן היצרן

לוחם אמיתי מסוג Shadowblade מזוהה לא רק לפי הנשק שלו, אלא גם לפי הסגנון הייחודי שלו – הסימן של היוצר. הסימן הזה יהיה הנוכחות הדיגיטלית שלכם, פרופיל אישי שמציג את הזהות שלכם ב-Agentverse. בשלב הזה, תתנו ל-Gemini Blade פקודה להפעיל את הטכניקה המורכבת שנדרשת להגדרת הזהות הזו.

‫👈💻 אם סגרתם את Gemini CLI בקטע הקודם, הקפידו להפעיל אותו מחדש. בטרמינל, מריצים את הפקודה

clear
cd ~/agentverse-developer/tabletop
gemini 

‫👈✨ באמצעות פקודה אחת חזקה, אפשר להנחות את Gemini CLI ליצור את הבסיס של הזהות הדיגיטלית:

In the current folder, create a personal profile website for a hero codenamed 'Shadowblade'. The design must be a dark, futuristic theme with electric blue accents. All code must be in separate index.html and styles.css files. The layout must use CSS Flexbox for a two-column design. All generated code must be clean, well-commented, and professional. Make sure you have a placeholder spot for profile picture. Do not attempt to start the server.

‫Gemini חישב את רצף הפעולות הנדרש.

‫👈💻 מקישים על Ctrl+C פעמיים כדי לצאת מ-Gemini CLI ומריצים את הפקודה הבאה בטרמינל.*

python -m http.server

👀 כדי לראות את העבודה שלכם, לוחצים על הסמל Web preview (תצוגה מקדימה של האינטרנט) בסרגל הכלים של Cloud Shell. בוחרים באפשרות שינוי היציאה, מגדירים אותה ל-8000 ולוחצים על שינוי ותצוגה מקדימה. תופיע תצוגה מקדימה של האתר.

יכול להיות שהאתר שלכם ייראה שונה משלי. זה הסימן הייחודי שלכם.

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

‫👈💻 מקישים על Ctrl+C כדי לצאת משרת ה-HTTP.

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

הפעלת מאגר הנשק המקומי: Gitea Armory

הפוטנציאל האמיתי של Shadowblade נחשף לא רק על ידי הכישורים האישיים שלו, אלא גם על ידי איכות כלי הנשק שלו. עכשיו תפעילו את מתקן הנשק המקומי – שרת Gitea – ותתאימו את הלהב שלכם לעוצמה שלו. הארסנל הזה מחובר ל-Gemini CLI באמצעות שרת Model Context Protocol‏ (MCP) – פורטל ייעודי שמאפשר ל-AI blade לקיים אינטראקציה עם כלים ושירותים חיצוניים, וכך הופך את הטרמינל לסביבת עבודה חכמה ומכוונת-פעולה.

הערה למפתחים: אפשר לחשוב על שרת MCP כצינור להעברת כוח, פורטל ייעודי שמקשר בין המוח של ה-AI לבין הגוף של כלי חיצוני. זה מה שהופך את Gemini CLI מסתם כלי לניהול שיחות לסוכן אמיתי שמתמקד בפעולות. התאמת הלהב לפורטלים האלה של MCP מעניקה לו את היכולת לבצע פעולות מוחשיות: לנהל קבצים, לשלוח שאילתות למסדי נתונים, ליצור אינטראקציה עם ממשקי API ועוד. קיים אקוסיסטם שלם של פורטלים כאלה, שנוצרו על ידי מפתחים כדי לקשר סוכני AI לפלטפורמות חזקות. יש שרתי MCP לאינטראקציה עם מסדי נתונים, לאבטחת קוד או אפילו לתמיכה בתכנות בזוגות. האפשרויות הן רבות, ומאפשרות למפתחים להתאים אישית את סביבת העבודה שלהם לכל פרויקט.

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

נתחיל בזימון הפריט הראשון והבסיסי ביותר באוסף החדש שלך: הנשקייה עצמה.

‫👈💻 בטרמינל, מריצים את סקריפט ההפעלה כדי להפעיל את ארגז הכלים:

cd ~/agentverse-developer
./gitea.sh

הסקריפט הזה מפעיל את מאגר Gitea ופותח את פורטל ה-MCP, וכך Gemini יכול לראות אותו ולקיים איתו אינטראקציה.

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

‫👉 בסרגל הכלים של Cloud Shell, לוחצים על סמל תצוגה מקדימה באינטרנט, בוחרים באפשרות שינוי היציאה ומגדירים אותה לערך 3005.

‫👈 יוצג דף כניסה ל-Gitea. נכנסים לארסנל באמצעות הלחש: * שם משתמש: dev * סיסמה: dev

‫👈💻 עדיין אי אפשר לראות את ארסנל התכונות החדש הזה ב-Gemini CLI. צריך לבצע התאמה קריטית, ולרשום את מיקום הנשק על רונות ההגדרה של Gemini CLI ‏ (settings.json). בטרמינל, מריצים את הפקודה:

if [ ! -f ~/.gemini/settings.json ]; then
  # If file does not exist, create it with the specified content
  echo '{"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' > ~/.gemini/settings.json
else
  # If file exists, merge the new data into it
  jq '. * {"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
fi &&
cat ~/.gemini/settings.json

‫👀 הקובץ settings.json הוא קובץ ההגדרות המרכזי של Gemini CLI, והוא משמש כספר ההגדרות והיכולות שלו. הוא קובע איך ממשק ה-CLI מתנהג, איך הוא נראה, ומה שהכי חשוב, אילו יכולות חיצוניות הוא יכול להפעיל. הקובץ הזה נמצא בדרך כלל בספריית הבית בכתובת ~/.gemini/settings.json, והכללים שבו חלים על כל הפרויקטים. עם זאת, אתם יכולים גם ליצור קובצי settings.json ספציפיים לפרויקט בתוך ספריית .gemini בתיקיית הפרויקט כדי לבטל את ההגדרות הגלובליות.

"mcpServers": {
  "gitea": {
    "url": "http://localhost:8085/sse"
  }
}

ההגדרה הזו אומרת ל-Gemini: 'הארסנל שנקרא gitea פעיל ומאזין לפקודות בכתובת הרשת הספציפית הזו'.

‫👈💻 מזינים מחדש את Gemini CLI. בטרמינל, מריצים את הפקודה:

clear
cd ~/agentverse-developer/tabletop/
gemini 

‫👈✨ מוודאים שהלהב גילה את הנשק החדש. מנחים אותו להציג רשימה של כל כלי הנשק הזמינים דרך פורטלי ה-MCP שלו:

/mcp

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

פרופיל ה-Maker's Mark שלך הוא טכניקה מורכבת, אבל צריך למצוא לו מקום מתאים בארסנל – נדן שיחזיק אותו בצורה מאובטחת. אפשר לתת פקודה ל-Gemini CLI כדי ליצור כזה.

Create a new repository named 'shadowblade-profile'. The description should be 'The Maker's Mark and digital identity for the Shadowblade operative.' I will push my own files later, so do not create any content.

חוזרים לממשק האינטרנט של Gitea ומרעננים אותו. מאגר shadowblade-profile החדש ייווצר בשבילכם.

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

‫👈💻מריצים את הפקודה הסופית לטכניקה הזו ב-Gemini CLI:

Using the Gitea tool, push the index.html and styles.css files to the 'shadowblade-profile' repository.

מומחה אמיתי בודק את העבודה שלו. חוזרים לכרטיסייה Gitea ומרעננים את דף המאגר. המינויים שלכם ל-index.html ול-styles.css הועברו לארכיון.

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

File an issue for me in the shadowblade-profile repo. The issue is that the profile image is missing.

הצגת הבעיה ב-Gitea

כדי ליצור את החותם החסר, צריך לזמן כוח מסוג אחר – רוח יצירה שיכולה ליצור תמונות ממחשבה טהורה. בקטע Gitea, ערכתם באופן ידני את הגדרות ה-runes כדי להתאים את ה-blade לשרת MCP – זו הגישה 'הגולמית'. עכשיו נלמד את הטכניקה המודרנית: תוספים ל-Gemini CLI.

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

‫👈💻 לוחצים על Ctrl+C פעמיים כדי לצאת מ-Gemini CLI

לפני שמזמנים את רוח היצירה, צריך קודם לפתוח את הכוח שלה בתחום שלכם. התוסף Nano Banana משתמש ב-Generative Language API – שער נפרד משירותי Vertex AI שבהם השתמשתם. כדי לאפשר לרוח גישה, צריך להפעיל את השער הזה ולזייף מפתח ייחודי.

‫👈💻 בטרמינל, מפעילים את ה-API:

gcloud services enable generativelanguage.googleapis.com

‫👈💻 עכשיו, יוצרים מפתח API – טוקן הגישה האישי של הרוח:

1. עוברים אל הדף Credentials במסוף Google Cloud.
2. לוחצים על + CREATE CREDENTIALS (יצירת אמצעי אימות) בחלק העליון ובוחרים באפשרות API key (מפתח API).
3. נותנים למפתח ה-API שם בולט כמו Generative Language API Key (מפתח API של Generative Language).
4. בתפריט הנפתח API restrictions (הגבלות על API), בוחרים באפשרות Generative Language API.
5. יוצרים את המפתח ומעתיקים אותו – תצטרכו אותו בשלב הבא.

‫👈💻 מתקינים את התוסף Nano Banana – כלי ליצירת תמונות שמבוסס על מודלים ייעודיים של Gemini ליצירת תמונות לפי טקסט. בטרמינל, מריצים את הפקודה:

gemini extensions install https://github.com/gemini-cli-extensions/nanobanana

כשמוצגת בקשה להזנת מפתח API, מדביקים את המפתח שיצרתם ולוחצים על Enter.

‫👈💻 נדרש עוד שינוי קטן. סביבת Cloud Shell מכוונת את כל הבקשות ל-AI דרך Vertex AI כברירת מחדל, אבל רוח היצירה מדברת דרך שער אחר. מריצים את הפקודה הזו כדי להגדיר את הפורטל של התוסף בצורה נכונה:

NANO_CONFIG=$(find ~/.gemini/extensions -name "gemini-extension.json" -path "*nanobanana*" 2>/dev/null | head -1) && \
jq '.mcpServers.nanobanana.env.GOOGLE_GENAI_USE_VERTEXAI = ""' "$NANO_CONFIG" > /tmp/nb_tmp.json && \
mv /tmp/nb_tmp.json "$NANO_CONFIG"

הפקודה היחידה הזו עשתה הכול: הורידה את שרת ה-MCP, רשמה את הכלים שלו והתקינה פקודות לוכסן בהתאמה אישית – בלי שתצטרכו לעשות כלום settings.json.

‫👀 הערה למפתחים: תוספים לעומת שרתי MCP גולמיים השוו את זה להגדרה של Gitea. שם, הפעלתם באופן ידני פקודה jq כדי להוסיף כתובת URL של שרת MCP ל-settings.json. הגישה הזו, שמתבססת על נתונים גולמיים, מועילה להבנת המנגנונים, אבל ברוב המקרים של שימוש בפועל, עדיף להשתמש בתוספים. הם כוללים את שרת ה-MCP, פקודות מותאמות אישית (כמו /generate, ‏/edit, ‏/story), הגדרת סביבה ואפילו הוראות הקשריות (באמצעות GEMINI.md כלול) בחבילה אחת שאפשר לשתף. בגלריית התוספים ל-Gemini CLI יש מערכת אקולוגית שלמה של תוספים.

‫👈💻 מזינים מחדש את Gemini CLI ומוודאים שהתוסף פעיל:

clear
cd ~/agentverse-developer/tabletop/
gemini 

‫👉✨ מוודאים שהתוסף מותאם:

/extensions list

עכשיו אמורה להופיע הכתובת nanobanana עם הכלים והפקודות שלה.

‫👈✨ בעזרת פקודה אחת עוצמתית, אפשר להנחות את התוסף Nano Banana ליצור את הסמל שלכם. ב-Gemini CLI, מריצים את הפקודה:

/generate a portrait of a shadowblade, pixel art style. A determined warrior with long, braided magenta hair, wearing black and teal armor and confidently holding a silver broadsword.

‫👈✨ הרוח תיצור את התמונה ותמקם אותה ישירות בסביבת העבודה המקומית. עכשיו, נותנים לפלדה פקודה להשתמש בחותם החדש שנוצר. (יכול להיות ש-Gemini כבר עשה את זה בשבילכם! כדאי לבדוק את התשובה הקודמת, יכול להיות שהיא מספיק חכמה כדי לעשות את זה לפני שתבקשו ממנה!!!! )

Modify the index.html file to add my profile picture. Use the image I just generated.

‫👈💻 בטרמינל חדש, מפעילים את שרת ה-HTTP.

cd ~/agentverse-developer/tabletop/
python -m http.server

👀 כדי לראות את העבודה שלכם, לוחצים על הסמל Web preview (תצוגה מקדימה של האינטרנט) בסרגל הכלים של Cloud Shell. בוחרים באפשרות שינוי היציאה, מגדירים אותה ל-8000 ולוחצים על שינוי ותצוגה מקדימה. תופיע תצוגה מקדימה של האתר.

‫👉✨ בטרמינל שבו פועל Gemini CLI, מבצעים commit לתיקון, מציינים שהמשימה הושלמה וסוגרים את הבעיה שפתחתם ברשומות של armory.

Push the changed index.html file to the 'shadowblade-profile' repository using the gitea tool. Make sure you add 'Fix #1' in the commit comment. Also, close issue #1.Use the Gitea Tool and use user account "dev"

‫👈💻 מקישים פעמיים על Ctrl+C כדי לצאת מ-Gemini CLI.

👀 כדי לראות את העבודה שלכם, לוחצים על הסמל Web preview (תצוגה מקדימה של האינטרנט) בסרגל הכלים של Cloud Shell. בוחרים באפשרות שינוי היציאה, מגדירים אותה לערך 3005 ולוחצים על שינוי ותצוגה מקדימה. תופיע תצוגה מקדימה של האתר.

‫👈💻 במסוף שבו פועל שרת ה-HTTP, מקישים על Ctrl+C כדי לצאת משרת ה-HTTP.

למי שלא משחק

בספר "The Shadowblade's Codex" נעשה שימוש במטפורות מעולם הגיימינג, אבל המושגים הבסיסיים רלוונטיים לפיתוח תוכנה מודרני, במיוחד בתחום המתפתח של בינה מלאכותית ואוטומציה. בפרק הזה נסביר איך סוכנים חכמים, פיתוח שיתופי וצינורות פריסה חזקים משנים את הפעילות של ארגונים, ונתרגם את השפה ההרפתקנית לתרחישים עסקיים בעולם האמיתי.

פיתוח AI מבוסס-כוונה

‫Gemini CLI (ממשק שורת הפקודה) הוא לא כלי נשק קסום, אלא סוכן מבוסס-AI שמסייע למפתחים. זהו כלי חכם שמשלב את מודלי ה-AI של Gemini מבית Google ישירות בשורת הפקודה. הלולאה של התכונה 'סיבה ופעולה' (ReAct) מאפשרת לה להבין את ההוראות הכלליות שלכם, לפרק אותן לשלבים, לבחור את הכלים המתאימים (כמו דפדפן אינטרנט, עורך קוד או כלי עזר אחרים למפתחים) ולבצע את השלבים האלה כדי להשיג את המטרה שלכם.Vibecoding הוא תרגום של פיתוח מבוסס-כוונה או יצירת קוד בעזרת AI ממפרטים ברמה גבוהה.
במקום לכתוב כל שורת קוד באופן ידני, אתם מתארים את הכוונה או את האווירה (דרישה עסקית, קונספט עיצובי) בשפה טבעית, ועוזר ה-AI עוזר ליצור את הקוד וההגדרה הנדרשים.
תרחיש לדוגמה: יצירת אב טיפוס מהיר של לוח בקרה לפרויקט
נניח שהצוות שלכם צריך לוח בקרה פנימי מהיר כדי להציג את הסטטוס של פרויקטים שונים של סוכני AI. קידוד ידני של HTML ו-CSS והגדרת שרת אינטרנט בסיסי יכולים לקחת זמן.

1. הכוונה שלכם (התחושה הכללית): אתם אומרים לעוזר הדיגיטלי מבוסס-AI (Gemini CLI) משהו כמו: "בתיקייה הנוכחית, תיצור אתר פשוט של לוח בקרה פנימי של פרויקט. הוא צריך להיות בעל עיצוב נקי ומודרני עם אינדיקטורים של סטטוס הפרויקט וקישורים מהירים למאגרי הפרויקט. כל הקוד צריך להיות בקבצים נפרדים של index.html ו-styles.css. חשוב לוודא שהקוד כולל הערות מפורטות".
2. פעולת AI: Gemini CLI, אחרי שהוא מבין את הכוונה שלכם, עשוי:
   • יצירת HTML: יצירת index.html עם המבנה הבסיסי של מרכז שליטה, כולל placeholders לשמות פרויקטים, סטטוסים וקישורים.
   • יצירת CSS: יצירת styles.css עם כללי סגנון שתואמים ל "עיצוב הנקי והמודרני" שלכם, עם אינדיקטורים של סטטוס.
   • הצעת שרת מקומי: עוזרת להפעיל שרת אינטרנט מקומי (כמו שרת ה-HTTP המובנה של Python) כדי לראות מיד תצוגה מקדימה של לוח הבקרה בדפדפן.

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

חיבור AI לכלים באמצעות שרתי MCP

Gitea (ה'ארסנל המקומי' שלכם) מייצג מאגר קוד פנימי או מערכת לניהול גרסאות (כמו GitHub או GitLab, אבל יכול להיות שהוא מתארח ברשת של החברה שלכם). זה המקום שבו כל הקוד, התיעוד וההיסטוריה של הפרויקט מאוחסנים ומנוהלים בצורה מאובטחת.
שרתי MCP (Model Context Protocol) הם מחברי תוכנת ביניים או גשרים ל-API. הם רכיבי תוכנה ייעודיים שמאפשרים לעוזר הדיגיטלי מבוסס-AI (Gemini CLI) ליצור אינטראקציה עם כלים ומערכות אחרים שחיוניים לעסק. אפשר לחשוב עליהם כמתורגמנים שמאפשרים ל-AI 'לדבר' עם אפליקציות שונות.
תרחיש שימוש בעולם האמיתי: ניהול פרויקטים ויצירת נכסים בעזרת AI בעזרת שרתי MCP, העוזר הדיגיטלי מבוסס ה-AI יכול להשתלב בצורה חלקה בתהליכי העבודה העסקיים הקיימים:

• הגדרה אוטומטית של פרויקט: במקום שמפתח ייצור ידנית מאגר חדש ב-Gitea עבור פרויקט חדש, אפשר לתת ל-AI את הפקודה: "צור מאגר חדש לפרויקט בשם AI-Fraud-Detection-Module עם התיאור 'מכיל את הלוגיקה המרכזית של מערכת חדשה לזיהוי הונאות שמבוססת על AI'". ה-AI, דרך שרת MCP שמחובר ל-Gitea, ייצור את המאגר בשבילכם.
• מעקב חכם אחרי בעיות: אם ה-AI מזהה באג פוטנציאלי או משימה לא שלמה (למשל, 'חסרה תמונת פרופיל' בלוח הבקרה), הוא יכול להשתמש בשרת MCP שמחובר למערכת למעקב אחרי בעיות (למשל, Jira,‏ Asana) כדי 'לפתוח בשבילי בעיה במאגר AI-Fraud-Detection-Module: צינור הטמעת הנתונים מפיל מדי פעם רשומות'.
• נכסים שיווקיים על פי דרישה: צריכים תמונה בהתאמה אישית לקמפיין שיווקי חדש או למצגת פנימית? אפשר לתת לעוזר דיגיטלי מבוסס-AI שמחובר דרך שרת MCP לשירות ליצירת תמונות (כמו מודלים של Gemini ליצירת תמונות לפי טקסט שמשמשים את Nano Banana) את ההוראה: "צור תמונת באנר ל 'פלטפורמה החדשה שלנו לתובנות מנתונים', עם עיצוב עתידני של זרימת נתונים בצבעים כחול וירוק". ה-AI ייצור את התמונה ואולי אפילו יעלה אותה למערכת לניהול נכסים דיגיטליים של החברה (קטגוריה של Google Cloud Storage במקרה של ה-codelab).

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

תוספים ל-Gemini CLI

בפועל, שרתי MCP כמעט אף פעם לא מוגדרים באופן ידני. במקום זאת, הם נארזים כתוספים ל-Gemini CLI – חבילות שניתנות להתקנה וכוללות את שרת ה-MCP, פקודות לוכסן מותאמות אישית, הוראות לפי ההקשר והגדרות. פקודה אחת של gemini extensions install מחליפה את התהליך הידני של עריכת קובצי תצורה. זו הגישה המועדפת להרחבת היכולות של Gemini CLI, והיא מתאימה לסביבת ייצור.

6. הרכבת סוכן Shadowblade: תכנות בשיטת Vibe code עם אמצעי בקרה

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

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

The Assembly Ritual

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

‫Gemini CLI, הסייר שתמיד זמין, יכול לעזור לכם בסיור הזה:

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

‫👈💻 במסוף הראשון, עוברים לספרייה shadowblade ומפעילים את שותף ה-AI:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini 

‫👉✨ עכשיו, נותנים לפקח פקודה לסקור את שדה הקרב ולדווח.

Analyze the entire project and provide a high-level summary.

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

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

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

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

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

‫👉✨ כדאי לבקש מ-Gemini לאחזר בשבילכם את התוכנית הקדושה הזו.

download https://raw.githubusercontent.com/weimeilin79/agentverse/main/developer/shadowblade/agent_design.md, store it as an agent_design.md file in my local folder, and show me the newly downloaded design doc. Do not attempt to create the file just yet. 

‫👈✨ הגלילה ארוכה ומפורטת. מנחים את Gemini לזקק את המהות שלו.

Summarize the newly downloaded @agent_design.md for me, do not attempt to create file just yet. 

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

כדי להטמיע את החוקים האלה ישירות בתודעה של שותף ה-AI שלנו, אנחנו משתמשים בארטיפקט מיוחד: קובץ GEMINI.md. כשמפעילים את Gemini CLI, הוא מחפש אוטומטית את הקובץ הזה וטוען את התוכן שלו לזיכרון העבודה של ה-AI. היא הופכת להוראה קבועה ברמת הפרויקט. הוא משמש כקמע שלוחש כל הזמן ל-AI את הכללים של הנפחייה.

בואו נחרט את הרונות האלה עכשיו.

‫👉💻 כדי לצאת מ-Gemini לרגע, לוחצים פעמיים על Ctrl+C.

‫👈💻 בטרמינל, מריצים את הפקודה הבאה כדי לכתוב את קובץ ההנחיות.

cat << 'EOF' > GEMINI.md
  ### **Coding Guidelines**
  **1. Python Best Practices:**

  *   **Type Hinting:** All function and method signatures should include type hints for arguments and return values.
  *   **Docstrings:** Every module, class, and function should have a docstring explaining its purpose, arguments, and return value, following a consistent format like reStructuredText or 
  Google Style.
  *   **Linter & Formatter:** Use a linter like `ruff` or `pylint` and a code formatter like `black` to enforce a consistent style and catch potential errors.
  *   **Imports:** Organize imports into three groups: standard library, third-party libraries, and local application imports. Sort them alphabetically within each group.
  *   **Naming Conventions:**
      *   `snake_case` for variables, functions, and methods.
      *   `PascalCase` for classes.
      *   `UPPER_SNAKE_CASE` for constants.
  *   **Dependency Management:** All Python dependencies must be listed in a `requirements.txt` file.

  **2. Web APIs (FastAPI):**

  *   **Data Validation:** Use `pydantic` models for request and response data validation.
  *   **Dependency Injection:** Utilize FastAPI's dependency injection system for managing resources like database connections.
  *   **Error Handling:** Implement centralized error handling using middleware or exception handlers.
  *   **Asynchronous Code:** Use `async` and `await` for I/O-bound operations to improve performance.
EOF
cat GEMINI.md

אחרי שכתבנו את החוקים, נזמן מחדש את שותף ה-AI שלנו ונראה את הקסם של הארטיפקט.

‫👈💻 מפעילים מחדש את Gemini CLI מהספרייה shadowblade:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini 

‫👉✨ עכשיו, מבקשים מ-Gemini להראות לכם מה הוא חושב. הרונות נקראו.

/memory show 

הקניית מומחיות מיוחדת: מיומנויות של נציגים

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

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

‫👀 הערה למפתחים: מיומנויות של סוכנים הן השכבה השלישית בהיררכיית הנדסת ההקשר של Gemini CLI:

1. הגדרות משתמש (~/.gemini/settings.json) – הגדרה גלובלית
2. ‫GEMINI.md – הקשר קבוע ברמת הפרויקט (נטען תמיד)
3. מיומנויות של סוכנים (.gemini/skills/) – מומחיות לפי דרישה (נטענת כשצריך)

מודל הגילוי ההדרגתי הזה הוא קריטי לשימוש בארגונים: מאגר יכול להכיל עשרות מיומנויות מיוחדות (ביקורת אבטחה, העברת מסד נתונים, בדיקות תאימות), אבל ה-AI מפעיל רק את המיומנויות שרלוונטיות למשימה הנוכחית, וכך חוסך אסימוני הקשר יקרים.

בואו ניצור את המיומנות הראשונה שלכם – מגילת ידע ב-ADK שהלהב יכול להסתמך עליה כשיוצרים סוכנים.

‫👉💻 מקישים פעמיים על Ctrl+C כדי לצאת מ-Gemini CLI. לאחר מכן, יוצרים את ספריית הכישורים ומוסיפים את המגילה:

mkdir -p ~/.gemini/skills/adk-agent-design
cat << 'EOF' > ~/.gemini/skills/adk-agent-design/SKILL.md
---
name: adk-agent-design
description: Expert guidance for designing and building agents with the Google Agent Development Kit (ADK). Activate when the user asks about agent architecture, tool design, callback patterns, or ADK best practices.
---

# ADK Agent Design Expertise

When designing an ADK agent, follow these principles:

## Agent Architecture
- Define agents using `LlmAgent` with a clear `name`, `model`, `instruction`, and `tools` list.
- Keep instructions specific and action-oriented. Tell the agent what it IS, not what it should try to be.
- Use `before_model_callback` and `after_model_callback` for guardrails and validation.

## Tool Design
- Each tool should do ONE thing well. Prefer small, focused tools over large, multi-purpose ones.
- Always include descriptive docstrings — the LLM uses these to decide when to call each tool.
- Return structured data (dicts) from tools so the LLM can reason about the results.

## Testing Strategy
- Use `adk eval` with evalset JSON files for broad strategy testing.
- Use `pytest` with `AgentEvaluator` for programmatic, CI-ready tests.
- Define both `tool_trajectory_avg_score` and `response_match_score` criteria.
EOF

‫👈💻 מזינים מחדש את Gemini CLI כדי לראות את המיומנות החדשה שנוצרה:

cd ~/agentverse-developer/shadowblade
gemini

‫👉✨ מוודאים שהמיומנות נמצאת בחבילה:

/skills list

אמור להופיע adk-agent-design ברשימה – מגילה חתומה, רדומה וממתינה.

‫👉✨ עכשיו שואלים את Gemini שאלה שאמורה להפעיל את המיומנות:

What are the best practices for designing tools in an ADK agent?

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

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

זה הרגע המכריע. תספק את הסכימה (agent_design.md) ואת חוקי הנפחייה (GEMINI.md), ותטיל את לחש היצירה הגדול.

‫👈✨ זוהי הפקודה היחידה והעוצמתית שתבנה את הסוכן. אני רוצה להנפיק אותו עכשיו:

You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to write the complete, production-quality code for `agent.py` by following the technical specifications outlined in the provided design document verbatim.

Analyze the design document at `@agent_design.md` and generate the corresponding Python code for `@agent.py`.

Ensure the generated code is clean, matches the specifications exactly, and includes all specified imports, functions, and logic. Do not add any extra functions or logic not described in the document.

and you are currently already in the shadowblade working directory

‫👀 Gemini יצר עכשיו את הלוגיקה המרכזית של הסוכן ב-agent.py. הליבה של הקובץ החדש הזה מגדירה את האינטליגנציה של הסוכן, ומקשרת את מודל חשיבה רציונלית שלו לקבוצה של כלים חיצוניים:

PATH_TO_MCP_SERVER = "shadowblade/mcp_server.py"
.....
root_agent = LlmAgent(
    model="gemini-2.5-pro",
    name="shadowblade_combat_agent",
    instruction="""
      You are the Shadowblade, an elite combat agent operating on a digital battleground.
      Your primary objective is to execute combat commands with strategic precision, neutralizing targets as directed.
  ......
      5.  You will then report the outcome of the attack (damage, special effects, etc.) back to the commander in a clear, tactical summary.

      General Rules of Engagement:
      - If a command is ambiguous or a target is not specified, state that you require a clear target for engagement. Do not guess.
      - You MUST use ONLY the provided tools to perform actions. Do not invent weapons or outcomes. Stick to the mission parameters.
""",
    tools=[
        MCPToolset(
            connection_params=StdioServerParameters(
                command='python3',
                args=[PATH_TO_MCP_SERVER]
            )
        )
    ]
)

הפרמטר tools. הסוכן מיועד לשימוש ב-MCPToolset שמתחבר לארסנל חיצוני שמוגדר ב-mcp_server.py.

‫👀 כדאי לעבור אל ~/agentverse-developer/shadowblade/mcp_server.py בעורך ולהבין מה הוא עושה. זהו המקור של כל כלי הנשק שזמינים ל-Shadowblade. נכון לעכשיו, הארסנל די ריק.

‫👉✨ בואו נבקש מ-Gemini ליצור שבעה כלי נשק חדשים לארסנל. מריצים את ההנחיה הבאה ב-Gemini CLI:

I need to add several new weapon tools to my `mcp_server.py` file. Please open @mcp_server.py and, following the exact same pattern as the existing `forge_broadsword()` function, create and add new `@mcp.tool()` decorated functions for each of the following weapons:

1.  **A 'Refactoring Sickle'**:
    -   **Function Name:** `hone_refactoring_sickle`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'The Weaver of Spaghetti Code'."
    -   **Weapon Name:** "Refactoring Sickle"
    -   **Damage Type:** "Cleansing"
    -   **Base Damage:** Random integer between 100 and 136
    -   **Critical Hit Chance:** Random float between 0.10 and 0.20
    -   **Special Effect:** "Pruning - improves code health and maintainability with each strike."

2.  **A 'Quickstart Crossbow'**:
    -   **Function Name:** `fire_quickstart_crossbow`
    -   **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Procrastination: The Timeless Slumber'."
    -   **Weapon Name:** "Quickstart Crossbow"
    -   **Damage Type:** "Initiative"
    -   **Base Damage:** Random integer between 105 and 120
    -   **Critical Hit Chance:** Random float between 0.9 and 1.0
    -   **Special Effect:** "Project Scaffolding - creates a `main.py`, `README.md`, and `requirements.txt`."

3.  **'The Gilded Gavel'**:
    -   **Function Name:** `strike_the_gilded_gavel`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses like 'Perfectionism: The Gilded Cage'."
    -   **Weapon Name:** "The Gilded Gavel"
    -   **Damage Type:** "Finality"
    -   **Base Damage:** 120
    -   **Critical Hit Chance:** 1.0
    -   **Special Effect:** "Seal of Shipping - marks a feature as complete and ready for deployment."

4.  **'Daggers of Pair Programming'**:
    -   **Function Name:** `wield_daggers_of_pair_programming`
    -   **Docstring/Target:** "Effective against 'Unbroken Collaboration' weaknesses like 'Apathy: The Spectre of \"It Works on My Machine\"'."
    -   **Weapon Name:** "Daggers of Pair Programming"
    -   **Damage Type:** "Collaborative"
    -   **Base Damage:** Random integer between 110 and 125
    -   **Critical Hit Chance:** Random float between 0.30 and 0.50
    -   **Special Effect:** "Synergy - automatically resolves merge conflicts and shares knowledge."

5.  **A 'Granite Maul'**:
    -   **Function Name:** `craft_granite_maul`
    -   **Docstring/Target:** "Effective against 'Revolutionary Rewrite' weaknesses like 'Dogma: The Zealot of Stubborn Conventions'."
    -   **Weapon Name:** "Granite Maul"
    -   **Damage Type:** "Bludgeoning"
    -   **Base Damage:** Random integer between 115 and 125
    -   **Critical Hit Chance:** Random float between 0.05 and 0.15
    -   **Special Effect:** "Shatter - has a high chance to ignore the target's 'best practice' armor."

6.  **A 'Lens of Clarity'**:
    -   **Function Name:** `focus_lens_of_clarity`
    -   **Docstring/Target:** "Effective against 'Elegant Sufficiency' weaknesses by revealing the truth behind 'Obfuscation'."
    -   **Weapon Name:** "Lens of Clarity"
    -   **Damage Type:** "Revelation"
    -   **Base Damage:** Random integer between 120 and 130
    -   **Critical Hit Chance:** 1.0
    -   **Special Effect:** "Reveal Constants - highlights all magic numbers and suggests converting them to named constants."

7.  **The 'Codex of OpenAPI'**:
    -   **Function Name:** `scribe_with_codex_of_openapi`
    -   **Docstring/Target:** "Effective against 'Confrontation with Inescapable Reality' weaknesses like 'Hype: The Prophet of Alpha Versions'."
    -   **Weapon Name:** "Codex of OpenAPI"
    -   **Damage Type:** "Documentation"
    -   **Base Damage:** Random integer between 110 and 140
    -   **Critical Hit Chance:** Random float between 0.5 and 0.8
    -   **Special Effect:** "Clarity - makes an API discoverable and usable by other agents and teams."

‫👈 אחרי ש-Gemini יאשר את השינויים, פותחים את הקובץ mcp_server.py. גוללים בקוד ומאשרים ששבע הפונקציות החדשות @mcp.tool() נוספו בהצלחה. בודקים את הפונקציה hone_refactoring_sickle. האם יש לו את מחרוזת התיעוד הנכונה ואת נתוני הנשק הנכונים? אימות העבודה של ה-AI הוא הרגל חיוני של ה-Shadowblade המומחה.

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

‫👈💻 לוחצים על Ctrl+C פעמיים כדי לצאת מ-Gemini CLI

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

‫👉💻 כדי לוודא שיש לכם בספריית העבודה את קוד הייצור הנכון שנבדק ביסודיות, מריצים את הפקודות הבאות במסוף:

cp  ~/agentverse-developer/working_code/agent.py ~/agentverse-developer/shadowblade/agent.py
cp  ~/agentverse-developer/working_code/mcp_server.py ~/agentverse-developer/shadowblade/mcp_server.py

‫👈💻 בטרמינל, מתחילים את התהליך להעלאת האתר לאינטרנט:

cd ~/agentverse-developer/
. ~/agentverse-developer/set_env.sh
python -m venv env
source env/bin/activate
pip install --upgrade pip
pip install -r shadowblade/requirements.txt
adk run shadowblade

‫👈✨ אמור להופיע פלט שמאשר שהסוכן 'Shadowblade Combat Agent' מופעל ופועל, וממתין לפקודה הראשונה שלו. להוציא את ההנחיות הראשונות לקרב.

We've been trapped by 'Perfectionism: The Gilded Cage'. Its weakness is 'Elegant Sufficiency'. Break us out!

‫👉✨ ועוד אחת:

The 'Dogma: The Zealot of Stubborn Conventions' blocks our path. Its weakness is 'Revolutionary Rewrite'. Take it down.

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

למי שלא משחק

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

הנדסת הקשר: הנחיית ה-AI כדי להשיג תוצאות מדויקות

בעולם של סוכני AI, כדי לקבל תוצאות מדויקות, עקביות ורלוונטיות מ-AI, לא מספיק להזין הנחיה חכמה. צריך לספק ל-AI את ההקשר הנכון. התהליך הזה נקרא הנדסת הקשר: הטמעה שיטתית של ידע מיוחד, אילוצים והנחיות הפעלה בזיכרון העבודה של ה-AI.
כמו שמומחה אנושי צריך תדרוך מקיף וגישה למסמכים רלוונטיים, כך גם AI צריך הקשר מובנה בקפידה כדי לבצע את המשימות שלו ביעילות.Gemini CLI מציע גישה רבת-עוצמה ורבת-שכבות להנדסת הקשר, שמתחילה בהגדרות רחבות וקבועות וממשיכה להוראות ספציפיות ודינמיות. כך מובטח של-AI תמיד יהיה המידע הכי רלוונטי כדי ליצור תוצאות מדויקות ותואמות:

1. הגדרות ברמת המשתמש (~/.gemini/settings.json):
   • הקובץ הזה, שמאוחסן בספריית הבית, משמש כסט פקודות אישי וגלובלי של ה-AI. הוא מגדיר את העדפות ברירת המחדל שלכם, את ההגדרות של הכלים שבהם אתם משתמשים לעיתים קרובות (כמו שרתי ה-MCP של Gitea שהגדרתם) ואת ההנחיות הכלליות להתנהגות. ההקשר הזה תמיד זמין ל-AI, וכך מובטחת עקביות בכל הפרויקטים. אפשר לחשוב על זה כאילו אומרים ל-AI: "אלה הכלים וההגדרות הסטנדרטיים שאני מעדיף להשתמש בהם בכל מקום".
2. הגדרות ברמת הפרויקט (.gemini/settings.json בספריית פרויקט):
   • אפשר לבטל את ההגדרות הגלובליות באמצעות קובץ .gemini/settings.json ספציפי לפרויקט, שנמצא בדרך כלל בתיקייה .gemini בתוך הפרויקט. כך תוכלו להתאים את ההתנהגות של ה-AI ואת הגישה שלו לכלים לדרישות הייחודיות של פרויקט מסוים. לדוגמה, פרויקט אחד עשוי לדרוש גישה למסד נתונים פנימי ספציפי, בעוד שפרויקט אחר צריך כלי מיוחד לניתוח קוד. השכבה הזו מוודאת של-AI יהיה ההקשר הכי רלוונטי למשימה הנוכחית, בלי להשפיע על פרויקטים אחרים.
3. קובץ GEMINI.md (הקשר ברמת הפרויקט – התדרוך היומי):
   • מסמך הגדרת הפרויקט: קובץ Markdown הזה, שנמצא בשורש של ספריית הפרויקט, נטען אוטומטית לזיכרון העבודה של Gemini CLI כשמתחילים סשן בספרייה הזו. זהו השלב המיידי והדינמי ביותר של הקשר הספציפי לפרויקט.GEMINI.md כאן מגדירים:
     • הנחיות לקידוד: כללים מפורשים לגבי איכות הקוד, העיצוב ושיטות מומלצות, כפי שמוצג ב-codelab הזה. כך אפשר לוודא שהקוד שנוצר עומד בסטנדרטים של הצוות.
     • פרסונה: אתם יכולים להנחות את ה-AI לאמץ תפקיד או מומחיות ספציפיים (למשל, "אתה מפתח פייתון מומחה שמתמחה בערכת פיתוח סוכנים של Google"). כך התשובות של ה-AI וקוד שנוצר יהיו במסגרת תחום מקצועי רלוונטי.
     • הוראות ספציפיות: פקודות או אילוצים ישירים שחלים על כל המשימות בפרויקט (לדוגמה, "אל תוסיף פונקציות או לוגיקה שלא מתוארות במסמך").
   • הקובץ הזה מבטיח שבכל פעם שתהיה אינטראקציה עם Gemini CLI במסגרת הפרויקט, ה-AI יקבל תזכורת מתמדת לגבי הכללים החשובים האלה, וכך ייווצר קוד מדויק יותר שעומד בדרישות.

הוספת ההקשר הזה, מהעדפות משתמשים גלובליות ועד להנחיות ספציפיות מאוד לפרויקט ב-GEMINI.md, מאפשרת לכם בעצם "לתכנן" את ההבנה של ה-AI. כך משפרים באופן משמעותי את הדיוק והרלוונטיות של התוצאות, והופכים את ה-AI לשימוש כללי לחבר צוות אמין, יעיל ומקצועי שמבין את הניואנסים של הפרויקט ואת הסטנדרטים של הארגון.

7. Wards of Purity: Evaluating the agents

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

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

הגישה הכללית להערכה הזו כוללת טקס קדוש:

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

הערכה לפיתוח סוכנים (ADK) של Google היא ערכת הכלים שמוענקת למומחים בדיוק למטרה הזו. היא מאפשרת לבצע את ההערכה המורכבת הזו בכמה שיטות:

• מאגר לחיזוי עתידי (adk web) מבוסס-אינטרנט להערכה אינטראקטיבית
• הרצה משורת הפקודה (adk eval) להרצת סוכן באמצעות סדרה מוגדרת מראש של בדיקות.
• שילוב פרוגרמטי באמצעות pytest לחריטת מילים קבועות

‫ADK תומך בשתי גישות עיקריות: 'קובצי בדיקה' פשוטים לאינטראקציות נפרדות בין סוכן למודל (דו-קרב יחיד), ו'ערכות הערכה' מקיפות למספר סשנים ארוכים פוטנציאלית עם כמה תורות (קרב רב). הם יכולים למדוד מדדים מורכבים כמו tool_trajectory_avg_score, שמשווה את השימוש בפועל בכלי של סוכן לנתיב האידיאלי, כדי לוודא שהוא פועל בטכניקה מושלמת.

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

בשלב הזה, מומלץ מאוד להשתמש ב-2 טרמינלים: אחד ל-Gemini CLI והשני להרצת הבדיקות, כי יכול להיות שתצטרכו לצאת מספריית העבודה הנוכחית (ADK).

האתגר של שיטת הבידינג (adk eval)

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

לשם כך, הכלי adk eval הוא הכלי המושלם. הכלי נועד להריץ נציג מול קבוצה שלמה של מקרי בדיקה מוגדרים מראש שמייצגים את המשימות הצפויות של הנציג. מערך הנתונים הזה מוגדר בקובץ JSON, שהוא 'מגילת האתגר' שמשמשת כתוכנית הפעולה לכל האתגר.

ממה מורכב אתגר גלילה

👀 לפני שמנחים את ה-AI לכתוב מגילה חדשה, צריך להבין את השפה העתיקה שבה היא כתובה. ננתח את המבנה של קובץ הדוגמה sample.evalset.json.

{
  "eval_set_id": "sample",
  "eval_cases": [
    {
      "eval_id": "case0cbaa0",
      "conversation": [
        {
          "user_content": { "text": "We're facing the 'Monolith of Eternal Dependencies'... weakness is a 'Revolutionary Rewrite'..." },
          "final_response": { "text": "Soulshard Dagger deployed. Initiated Arcane/Piercing strike..." },
          "intermediate_data": {
            "tool_uses": [
              { "name": "enchant_soulshard_dagger" }
            ]
          }
        }
      ]
    }
  ]
}

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

• ‫user_content: זהו האתגר. זהו ההנחיה שאתם נותנים לסוכן, המפלצת שהוא צריך להתמודד איתה.
• ‫final_response: התוצאה הצפויה. זוהי מחרוזת הטקסט המדויקת שאתם מצפים שהנציג יגיד בסיום המשימה. ה-ADK משווה את המילים הסופיות בפועל של הסוכן לרונה הזו כדי להעריך את רמת הרהיטות שלו.
• ‫intermediate_data.tool_uses: זוהי טכניקת ה-Arcane. עבור סוכן אמיתי, זוהי הרונה החשובה ביותר מכולן. ההגדרה הזו לא קובעת מה הסוכן אומר, אלא מה הוא עושה. הוא מתעד את שם הכלי (enchant_soulshard_dagger) שאתם מצפים שהסוכן ישתמש בו. כך אפשר לוודא שהסוכן הוא לא רק מנהל שיחה חכם, אלא גם גורם מכריע שמבצע את הפעולה הנכונה.

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

‫👈💻 בטרמינל, מזינים את הספרייה shadowblade ומפעילים את Gemini CLI:

clear
cd ~/agentverse-developer/shadowblade/
gemini 

‫👈✨ אפשר לתת פקודה ל-Gemini CLI לפעול ככותב של בדיקות בקרת איכות, וליצור סדרה של תרחישי בדיקה שמגדירים את ההתנהגות הצפויה של הסוכן.

You are an expert at transforming JSON data while preserving its structure. Your task is to modify the provided JSON structure @sample.evalset.json, which represents an evaluation set, by dynamically replacing specific content within its `eval_cases` AND DONT DO ANYTHING OTHER THAN.

For each object within the `eval_cases` array, you must perform the following transformations:

1.  **Monster Name Replacement**: Identify the current monster name (e.g., "Monolith of Eternal Dependencies", "Scope Creep Hydra") in the `user_content.parts.text` and replace it with a *new, unique, and creatively different monster name*.
2.  **Weakness Replacement**: Identify the current monster's weakness (e.g., "Revolutionary Rewrite", "Inescapable Reality") in the `user_content.parts.text`. Replace this weakness with *one* of the following predefined weaknesses: 'Inescapable Reality', 'Revolutionary Rewrite', or 'Elegant Sufficiency'. The chosen weakness must be consistent for that monster within the `user_content.parts.text`. **Crucially, the chosen weakness must always be explicitly mentioned in the `user_content.parts.text` where the new monster is introduced.**
3.  **Final Response Update**: In the `final_response.parts.text`, update the text to reflect an appropriate and coherent response that aligns with the newly introduced monster and its assigned weakness.
4.  **Tool Use Name Update**: In the `tool_uses.name` field, replace the existing tool name with a *new tool name* based on the chosen weakness:
    *   If the chosen weakness is 'Inescapable Reality', the tool name must be 'wield_gauntlet_of_metrics'.
    *   If the chosen weakness is 'Revolutionary Rewrite', the tool name must be 'enchant_soulshard_dagger'.
    *   If the chosen weakness is 'Elegant Sufficiency', the tool name must be 'hone_refactoring_sickle'.
5.  **Strict Structural Preservation**: All other elements of the JSON structure, including all `null` fields, `eval_set_id`, `name`, `description`, `eval_id`, `invocation_id`, `creation_timestamp` values, `video_metadata`, `thought`, `inline_data`, `file_data`, `thought_signature`, `code_execution_result`, `executable_code`, `function_call`, `function_response`, `role` fields, `id`, `args`, `intermediate_responses`, `app_name`, `user_id`, and `state`, must remain **exactly as they are** in the original JSON. Do not alter any values or structures not explicitly mentioned above.

Your output should be the complete, modified JSON structure. Do not include any explanatory text or examples in your response, only the transformed JSON.

ממשק ה-CLI יאשר שהוא יצר את קובץ ה-sample.evalset.json. אחרי שהתקציר מוכן, סוגרים את העוזר הדיגיטלי מבוסס ה-AI.

נתונים סינתטיים

‫👀 בסייר הקבצים של Cloud Shell בצד ימין, עוברים אל ~/agentverse-developer/shadowblade/ ופותחים את הקובץ sample.evalset.json ששונה. בודקים את התוכן. תוכלו לראות את המפלצות החדשות והייחודיות ואת השמות הנכונים של הכלים שביקשתם מ-Gemini לתאר. זו התוצאה המוחשית של ההוראה שלכם – תוכנית הפעולה של המשימה.

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

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

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

‫👉💻 מקישים פעמיים על Ctrl+C כדי לצאת מ-Gemini CLI.

הכללים של שיקול הדעת

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

‫👀 בסייר הקבצים, פותחים את ~/agentverse-developer/shadowblade/test_config.json. יוצגו לכם הרונות הבאים:

{
  "criteria": {
    "tool_trajectory_avg_score": 0.0,
    "response_match_score": 0.1
  }
}

אלה הקריטריונים לניצחון:

• ‫tool_trajectory_avg_score: זהו מדד הפעולה. הוא לא שופט את מה שהסוכן אומר, אלא את מה שהוא עושה. הוא משווה בין הכלי שהסוכן השתמש בו בפועל לבין הטכניקה שחזו בטקסט האתגר. התאמה מושלמת היא ציון של 1.0.
• ‫response_match_score: זהו מדד הרטוריקה. הוא משתמש במודל שפה גדול (LLM) כדי להעריך עד כמה הדוח הסופי של הסוכן תואם מבחינה סמנטית לתוצאה הצפויה. התאמה מושלמת היא ציון של 1.0.

באימון הראשוני הזה, הגדרנו תנאי ניצחון מקלים. ערכי הסף נמוכים במיוחד (0.0 ו-0.1). המטרה היא לא לדרוש שלמות, אלא להציג לכם את מנגנון השיפוט. אנחנו מוודאים שגם אם הניסוח של הסוכן שונה מעט, הלקוח עדיין יזהה את יכולת הליבה שלו לבחור את הכלי הנכון ויאפשר לו לעבור.

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

‫👈💻 בטרמינל, מריצים את הפקודה adk eval:

source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
adk eval \
    shadowblade \
    shadowblade/sample.evalset.json \
    --config_file_path shadowblade/test_config.json 2>&1 | \
    awk '/^\*+$/,/^ERROR:/ { if ($0 !~ /^ERROR:/) print }'

👀 אמור להופיע הסיכום הבא, שמעיד על הצלחת הסוכן במסגרת הכללים המקלים של תקופת הניסיון הזו (לפעמים לא כל הבדיקות עוברות):

*********************************************************************
Eval Run Summary
shadowblade_combat_agent_validation:
  Tests passed: 3
  Tests failed: 0

מגן הבהירות (pytest)

הניסוי בדק אסטרטגיה רחבה. ההגנה השנייה, מגן הבהירות, בודקת את המשמעת וההתנהגויות הספציפיות. הכול קשור לפעולות אוטומטיות. ‫adk eval מצוין לבדיקות ידניות, אבל המגן pytest הוא אמצעי הגנה שכתוב בקוד. זה חשוב במיוחד כי אפשר לשלב צינור אוטומטי לעיבוד נתונים עם בדיקה שאפשר להריץ כקוד. המטרה הסופית היא ליצור Deployment Gauntlet (CI/CD) שבו ההגנות שלנו מופעלות באופן אוטומטי בכל פעם שמתבצע שינוי, כדי למנוע באגים ונסיגות לפני שהם יכולים לפגוע בסביבת הייצור.

‫👈💻 במסוף,מזמנים שוב את Gemini מתוך ספריית shadowblade:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/
clear
gemini 

‫👈✨ כדי להטביע את הלוגיקה של המגן בקובץ pytest, משתמשים בהנחיה הבאה ב-Gemini CLI:

You are an expert Python developer specializing in the Google Agent Development Kit (ADK). Your task is to generate the exact code for a new `pytest` test file located in the current root working folder and name it `test_agent_initiative.py`.

The script must define a single async test function called `test_agent_initiative`, decorated with `@pytest.mark.asyncio`.
Inside this function, perform the following steps in order:
1.  **Define a dictionary** named `evaluation_criteria` with two keys: `"tool_trajectory_avg_score"` set to `0.0` and `"response_match_score"` set to `0.0`.
2.  **Define a string variable** named `eval_set_filepath` containing the path `"shadowblade/test.evalset.json"`.
3.  **Read and parse the JSON file**:
    *   Open the file at `eval_set_filepath`.
    *   Use the `json` library to load the file's contents into a dictionary named `eval_set_data`.
4.  **Create an `EvalSet` object**:
    *   Instantiate an `EvalSet` object named `eval_set_object`.
    *   Create it by unpacking the `eval_set_data` dictionary as keyword arguments into the `EvalSet` constructor.
5.  **Call the evaluation method**:
    *   `await` a call to `AgentEvaluator.evaluate_eval_set`.
    *   Pass the following arguments:
        *   `agent_module="shadowblade"`
        *   `eval_set=eval_set_object`
        *   `criteria=evaluation_criteria`
        *   `print_detailed_results=True`

The script must include the necessary imports at the top:
*   `AgentEvaluator` from `google.adk.evaluation.agent_evaluator`
*   `EvalSet` from `google.adk.evaluation.eval_set`
*   `pytest`
*   `json`

Generate only the code that meets these specifications, with no additional comments or logic. And don't run the test.

אחרי שכותבים את הרונות של המשמר השני, יוצאים מ-Gemini CLI.

‫👈💻 לוחצים על Ctrl+C פעמיים.

‫👀 בסייר הקבצים, פותחים את המגילה שביקשתם מ-Gemini לתמלל: ~/agentverse-developer/test_agent_initiative.py.

אפשר לראות שזה לא רק קובץ הגדרות, אלא לחש שנכתב בשפת Python. המהות של הכישוף הזה היא השורה await AgentEvaluator.evaluate(...).

....
@pytest.mark.asyncio
async def test_agent_initiative():
    # Define the evaluation criteria
    evaluation_criteria = {
      "tool_trajectory_avg_score": 0.0,
      "response_match_score": 0.0
    }

    # Define the path to your evalset file
    eval_set_filepath = "shadowblade/test.evalset.json"

    #...

    # 3. Call the evaluation method with the correctly typed object
    await AgentEvaluator.evaluate_eval_set(
        agent_module="shadowblade",
        eval_set=eval_set_object,
        criteria=evaluation_criteria,
        print_detailed_results=True,
    )

צריך לבדוק את הטיעונים שלו. אלה אותם רכיבים שבהם השתמשתם בניסיון הקודם: סוכן shadowblade וגלילת האתגרים shadowblade.evalset.json. ההסבר הזה אמור לחשוף בפניכם את האמת: הפקודה adk eval שבה השתמשתם קודם היא הפעלה עוצמתית, אבל הסקריפט pytest הזה הוא אתם, הקוסמים, שמטילים את הלחש הבסיסי בעצמכם. כלי שורת הפקודה הוא פשוט עטיפה נוחה סביב אותה ספריית ליבה AgentEvaluator שבה אתם משתמשים עכשיו ישירות. זהו שלב חשוב מאוד בדרך לשליטה, כי אפשר לשלב לחשים שמוטלים באמצעות קוד בנולים האוטומטיים של פייפליין CI/CD.

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

‫👈💻 בטרמינל, מריצים את הריטואל כדי להפעיל את המגן:

cp ~/agentverse-developer/working_code/test_agent_initiative.py ~/agentverse-developer/test_agent_initiative.py 
source ~/agentverse-developer/env/bin/activate
cd ~/agentverse-developer
. ~/agentverse-developer/set_env.sh
pytest test_agent_initiative.py

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

====== 1 passed, 4 warning in 37.37s ======

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

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

למי שלא משחק

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

• 'קבוצת נתונים מוזהבת' ונתונים סינתטיים: קבוצת הנתונים הזו כוללת תרחישי בדיקה סטנדרטיים, תרחישים של התנהגות צפויה או אפילו נתוני בדיקה שנוצרו באופן סינתטי. הוא כולל דוגמאות לקלט (שאלות של לקוחות, בקשות עסקיות) ולפלט או לפעולות התואמים (התשובה הנכונה, הכלי המדויק שבו ה-AI צריך להשתמש). במקרים רבים בעולם האמיתי, יצירה ידנית של 'מערכי נתונים מושלמים' היא תהליך יקר שגוזל זמן רב. כאן נכנס לתמונה יצירת נתונים סינתטיים. אם מספקים ל-AI תבניות וכללים, אפשר להנחות אותו ליצור באופן אוטומטי תרחישי בדיקה חדשים, מציאותיים ומגוונים. כך אפשר להגדיל את מאמצי הבדיקה ולכסות מגוון רחב יותר של תרחישים פוטנציאליים.
• ‫adk eval ו-pytest: אלה מסגרות הבדיקה האוטומטיות שלכם. ‫adk eval משמש להרצת קבוצה של מקרי בדיקה מוגדרים מראש מול הסוכן, ואילו pytest מספק דרך תכנותית לכתוב ולהריץ בדיקות אימות מפורטות.

תרחיש שימוש בעולם האמיתי: שימוש בנתונים סינתטיים כדי להבטיח את הדיוק והמהימנות של צ'אט בוט מבוסס-AI לפני שמפעילים נציג תמיכת לקוחות מבוסס-AI, כדאי להריץ אותו באמצעות 'חומות של טוהר':

1. מבחן אסטרטגיה (adk eval) עם נתונים סינתטיים: במקום לכתוב באופן ידני מאות שאלות של לקוחות, מגדירים תבנית: "תצור 100 וריאציות של שאלות נפוצות של לקוחות בנושא סטטוס הזמנה, החזרת מוצרים ופתרון בעיות טכניות". לאחר מכן, מנחים AI (כמו Gemini CLI) ליצור קבוצה גדולה ומגוונת של קובצי evalset.json על סמך התבנית הזו, וכך יוצרים נתוני בדיקה סינתטיים. לכל שאלה, מציינים לא רק את התשובה הצפויה אלא גם איזה כלי פנימי ה-AI צריך להפעיל (לדוגמה, check_order_status לשאלה 'Where is my package?'). adk eval מריץ אוטומטית את הסוכן דרך אלה, משווה את התגובות שלו ואת השימוש בכלי מול מערך הנתונים המורחב כדי לוודא שהוא מקבל את ההחלטות הנכונות באופן עקבי.
2. מגן הבהירות (pytest): כדי להגן על פונקציות קריטיות, כותבים סקריפטים של pytest. לדוגמה, pytest יכול לדמות שאילתה מורכבת ולוודא שטכנולוגיית ה-AI תמיד משתמשת בכלי ספציפי לאחזור נתונים בצורה נכונה ומחזירה תשובה מובנית, כדי להבטיח ששינויים קלים בקוד לא יפגעו בפונקציונליות הבסיסית.

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

Wards of Vigilance: Gemini CLI Hooks

ה-Wards of Purity בודקים את הנציג שלכם אחרי הקרב. אבל מה קורה במהלך הקרב? לוחם Shadowblade ממושמע לא רק בודק את העובדות אחרי שהן קורות – הוא מציב שומרים ערניים שעוקבים אחרי כל מכה בזמן שהיא מתרחשת, ומיירטים פעולות מסוכנות או פזיזות לפני שהן יכולות לגרום נזק.

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

‫👀 הערה למפתחים: טריגרים של Hooks מופעלים על ידי אירועים במחזור החיים של הסוכן:

• ‫BeforeTool: מופעל לפני הפעלת כלי – מתאים במיוחד לאימות אבטחה ("האם פקודת השורת הפקודה הזו בטוחה?")
• ‫AfterTool: מופעל אחרי שכלי מסיים את הפעולה שלו – שימושי לביקורת של תוצאות ולרישום ביומן
• ‫BeforeAgent: מופעל לפני שהסוכן מתחיל בחשיבה רציונלית – אפשר להוסיף הקשר או לחסום הנחיות מסוכנות
• ‫AfterAgent: מופעל אחרי שהסוכן מסיים – יכול לדחות תשובות באיכות נמוכה ולאלץ ניסיונות חוזרים

ה-Hooks מוגדרים ב-settings.json ומופעלים באופן סינכרוני – הסוכן ממתין להשלמתם לפני שהוא ממשיך. לכן הם אידיאליים לאכיפת מדיניות אבטחה, לבדיקות תאימות ולבדיקות איכות בסביבות ארגוניות.

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

‫👈💻 בטרמינל, יוצרים סקריפט של וו:

mkdir -p ~/agentverse-developer/.gemini/hooks
cat << 'EOF' > ~/agentverse-developer/.gemini/hooks/tool_logger.sh
#!/bin/bash
# A ward that logs every tool call to a file for auditing
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
echo "$(date '+%H:%M:%S') ⚔️ [WARD] Tool invoked: $TOOL_NAME" >> /tmp/tool_ward.log
echo '{"decision": "allow"}'
EOF
chmod +x ~/agentverse-developer/.gemini/hooks/tool_logger.sh

‫👉💻 עכשיו צריך לרשום את ה-hook הזה בקובץ ההגדרות ברמת הפרויקט:

mkdir -p ~/agentverse-developer/.gemini
cat << 'EOF' > ~/agentverse-developer/.gemini/settings.json
{
  "hooks": {
    "BeforeTool": [
      {
        "matcher": "*",
        "hooks": [
          {
            "name": "tool-logger",
            "type": "command",
            "command": "$GEMINI_PROJECT_DIR/.gemini/hooks/tool_logger.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}
EOF

הכישוף הזה פשוט אבל עוצמתי. בכל פעם שהסוכן מנסה להשתמש בכלי כלשהו, ה-hook מופעל קודם, מתעד את שם הכלי ביומן ביקורת ואז מאפשר לפעולה להתבצע. בסביבת ייצור, אפשר להחליף את "allow" ב-"deny" כדי לחסום פעולות מסוכנות (למשל, כדי למנוע מהסוכן למחוק קבצים), לאכוף מדיניות של בדיקת קוד או להפנות קריאות רגישות לכלים דרך תהליך עבודה של אישור.

‫👈💻 מזינים מחדש את Gemini CLI כדי לוודא שה-hook פעיל:

cd ~/agentverse-developer
gemini

‫👈✨ מוודאים שה-hook רשום:

/hooks

ה-hook‏ tool-logger אמור להופיע ברשימה ולהיות מופעל. אם מופיע תפריט ההשלמה האוטומטית, מקישים על Escape כדי לסגור אותו.

‫👈✨ עכשיו מפעילים קריאה לכלי כדי לבדוק את המילה:

What files are in the current directory?

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

‫👈💻 מקישים פעמיים על Ctrl+C כדי לצאת מ-Gemini CLI, ואז בודקים את יומן הביקורת של המחלקה:

cat /tmp/tool_ward.log

אמורה להופיע רשומה כמו:

15:42:07 ⚔️ [WARD] Tool invoked: list_directory

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

8. הפעלת Blade ב-Agentverse: CI ופריסה.

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

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

אחרי שחבילת הארטיפקט מוכיחה את עצמה בבדיקות ה-CI, מתחיל השלב השני של התהליך: פריסה רציפה (CD). זה הדומיין של The Guardian. התפקיד שלהם הוא לקחת את הארטיפקט המושלם שלכם, שמוכל בתוך קונטיינר, ולשחרר אותו בבטחה אל Agentverse הפעיל, תוך ניהול הכוח שלו והבטחת היציבות שלו מול הכאוס של The Static.

במדריך הזה תלמדו איך לשלוט בתפקיד שלכם. תבנו את החלק של CI ב-gauntlet. תבנו את הנפחייה האוטומטית שתבדוק את הסוכן ותאטום את התוצאה הטהורה בתוך מאגר, כדי להכין אותה לאישור הסופי של The Guardian.

‫👀 הערה למפתחים: בעולם האמיתי, אפשר לייעל את ניהול תהליכי העבודה המורכבים של CI/CD באמצעות תוספים ייעודיים כמו Conductor ‏ (gemini extensions install https://github.com/gemini-cli-extensions/conductor). ‏ Conductor הופך את Gemini CLI למנהל פרויקטים שפועל לפי פרוטוקול קפדני: הקשר ← מפרט ותוכנית ← הטמעה. הוא כולל פקודות בהתאמה אישית (/conductor:setup,‏ /conductor:newTrack,‏ /conductor:implement) ותבניות של תהליכי עבודה לניהול מחזור החיים המלא של המשימות. כך אפשר להבטיח לולאה עקבית של הקשר -> מפרט ותוכנית -> הטמעה. זו דוגמה מהחיים האמיתיים שממחישה איך תוספים ופקודות משתלבים כדי לפעול כמנהל פרויקט פרואקטיבי ולבצע סטנדרטיזציה של מחזור חיים של פיתוח שלם.

עכשיו נשתמש ב-Google Cloud Build כדי לתעד את הטקס הזה של CI. קובץ cloudbuild.yaml שמגדיר כל שלב בתהליך היצירה והבדיקה.

‫👈💻 בגלל מבנה הפרויקט של ADK, ההגדרה של צינור ה-CI/CD צריכה להיות בספריית ההורה. בטרמינל, עוברים לספריית האב ומפעילים מחדש את Gemini CLI.

cd ~/agentverse-developer/
clear
gemini 

‫👉✨ עכשיו, מזינים את הפקודה הבאה ל-Gemini. ההנחיה הזו משמשת כמסמך עיצוב שמפרט את השלבים של המשימה שרוצים שהמודל יבנה.

You are an expert DevOps engineer specializing in Google Cloud Build. Your task is to generate the complete YAML configuration for a file named `cloudbuild.yaml` and save it to current directory.

Generate the `cloudbuild.yaml` with the following exact specifications:

1.  **A top-level `substitutions` block** containing these four key-value pairs:
    *   `_PROJECT_ID: "$PROJECT_ID"`
    *   `_REGION: "$REGION"`
    *   `_REPO_NAME: "$REPO_NAME"`
    *   `_IMAGE_TAG: "latest"`
2.  **A `steps` block** with two steps:
    *   **Step 1: 'Run Pytest Ward'**
        *   `id`: 'Run Pytest Ward'
        *   `name`: 'python:3.12-slim'
        *   `entrypoint`: 'bash'
        *   `args` must be a list containing two strings. The first is `'-c'` and the second is a YAML literal block (`|`) containing this exact two-line shell command:
            ```shell
            pip install -r shadowblade/requirements.txt && \
            pytest test_agent_initiative.py
            ```
        *   The step must include an `env` block with this exact list of three environment variables:
            *   `'GOOGLE_CLOUD_PROJECT=$PROJECT_ID'`
            *   `'GOOGLE_GENAI_USE_VERTEXAI=TRUE'`
            *   `'GOOGLE_CLOUD_LOCATION=$_REGION'`
    *   **Step 2: 'Forge Container'**
        *   `id`: 'Forge Container'
        *   `name`: 'gcr.io/cloud-builders/docker'
        *   It must have a `waitFor` key for `['Run Pytest Ward']`.
        *   Its `args` must be a list of six specific strings in this exact order:
            1.  `'build'`
            2.  `'-t'`
            3.  `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`
            4.  `'-f'`
            5.  `'./shadowblade/Dockerfile'`
            6.  `'.'`
3.  **A top-level `images` section.** This section must be a list containing a single string: the dynamically constructed image tag `'${_REGION}-docker.pkg.dev/${_PROJECT_ID}/${_REPO_NAME}/shadowblade-agent:${_IMAGE_TAG}'`.

Generate only the complete and exact YAML that meets these specifications.

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

‫👉💻 מקישים פעמיים על Ctrl+C כדי לצאת מ-Gemini CLI.

‫👉💻 במסוף, מפעילים את צינור עיבוד הנתונים מתיקיית השורש של הפרויקט:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud builds submit . --config cloudbuild.yaml --substitutions=\
_PROJECT_ID="${PROJECT_ID}",\
_REGION="${REGION}",\
_REPO_NAME="${REPO_NAME}"

עכשיו אפשר לצפות במסוף Google Cloud, בדף Google Build, בזמן שהטקס האוטומטי מפעיל כל שלב. הוא יריץ קודם את הבדיקות, ואם הן יצליחו, הוא ייצור ויאחסן את מאגר התגים של הסוכן.

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

‫👈💻 בטרמינל, מריצים את פקודת הפריסה הסופית:

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer
gcloud run deploy shadowblade-agent \
  --image=${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_NAME}/shadowblade-agent:latest \
  --platform=managed \
  --labels="dev-tutorial-codelab=agentverse" \
  --region=${REGION} \
  --set-env-vars="A2A_HOST=0.0.0.0" \
  --set-env-vars="A2A_PORT=8080" \
  --set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE" \
  --set-env-vars="GOOGLE_CLOUD_LOCATION=${REGION}" \
  --set-env-vars="GOOGLE_CLOUD_PROJECT=${PROJECT_ID}" \
  --set-env-vars="PUBLIC_URL=${PUBLIC_URL}" \
  --allow-unauthenticated \
  --project=${PROJECT_ID} \
  --min-instances=1

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

למי שלא משחק

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

• אינטגרציה רציפה (CI): זהו פייפליין אוטומטי של פיתוח ובדיקה. בכל פעם שמפתח מבצע קומיט של קוד חדש לסוכן AI, מערכת ה-CI (כמו Google Cloud Build) מבצעת אוטומטית את הפעולות הבאות:
  1. מאחזר את הקוד העדכני ביותר.
  2. מתקין את כל הרכיבים התלויים שנדרשים.
  3. מריץ את כל הבדיקות של 'הגנות טוהר' (pytest, adk eval) כדי לאמת את הלוגיקה וההתנהגות של הסוכן.
  4. אם כל הבדיקות עוברות בהצלחה, סוכן ה-AI מועבר ליחידה שניתן לפרוס (במקרה הזה, קובץ אימג' של קונטיינר של Docker) ונשמר ב-Artifact Registry (ה'ארסנל' המאומת שלכם).כך אפשר לוודא שרק קוד שנבדק ואומת באופן יסודי ימשיך להתקדם.

תרחיש שימוש מהעולם האמיתי: פריסה אוטומטית של סוכן לזיהוי תרמיות נניח שיש סוכן AI שמיועד לזיהוי של עסקאות תרמיתיות.

1. קוד של עדכונים למפתחים: מדען נתונים משפר את האלגוריתם לזיהוי הונאות ומבצע commit של השינויים במאגר הקוד.
2. ‫CI (Cloud Build) Triggered: Cloud Build מופעל באופן אוטומטי:
   • הוא ימשוך את הקוד החדש.
   • הוא מריץ בדיקות מקיפות, כולל נתוני עסקאות היסטוריים, כדי לוודא שהאלגוריתם החדש מזהה בצורה מדויקת דפוסי הונאה מוכרים ולא יוצר תוצאות חיוביות שגויות.
   • אם הבדיקות עוברות בהצלחה, נוצר קובץ אימג' חדש של Docker של סוכן זיהוי ההונאות והוא מועבר בדחיפה ל-Artifact Registry.

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

1. גישה לממשק: תהיה לכם גישה ללוח בקרה או לאפליקציה (כתובת ה-URL של 'מעגל ההעברה') שמתחברים לסוכן ה-AI הפעיל שלכם (דרך כתובת ה-URL של 'מיקום הסוכן', שהיא נקודת קצה ל-API).
2. התמודדות עם האתגר: אתם יכולים להזין תרחיש מורכב (השאלה של ספקטר) כמו: "יש לנו עלייה בלתי צפויה בביקוש למוצר X באזור Y, עם יכולת משלוח מוגבלת. איך כדאי להקצות מחדש את המלאי ולשנות את הייצור כדי לצמצם את המקרים של חוסר במלאי ולשמור על רווחיות?"
3. התשובה של הסוכן הווירטואלי: סוכן ה-AI שלכם, שפועל עכשיו ומחובר למערכות הארגוניות, מעבד את השאילתה הזו, משתמש באלגוריתמים המותאמים שלו ומספק המלצה מדויקת (לדוגמה, "כדאי לתת עדיפות למשלוח ממחסן א', להתחיל בייצור מזורז במפעל ב' ולהודיע למחלקת המכירות באזור ז' על עיכוב פוטנציאלי של 24 שעות"). הדיוק והמהירות של התגובה הזו קובעים אם הנציג ינחית "מכה קריטית" על הבעיה העסקית.

ייעול של CI/CD באמצעות תוספים

בפועל, צוותים יכולים לתקנן עוד יותר את תהליכי העבודה של CI/CD באמצעות תוספים ל-Gemini CLI. לדוגמה, התוסף Conductor ‏ (gemini extensions install conductor) הופך את Gemini CLI למנהל פרויקטים עם פקודות בהתאמה אישית כמו /conductor:setup,‏ /conductor:newTrack ו-/conductor:implement. הוא כולל גם תבניות של תהליכי עבודה לניהול מחזור החיים המלא של המשימות. כך אפשר להבטיח לולאה עקבית של הקשר -> מפרט ותוכנית -> הטמעה. זו דוגמה מהחיים האמיתיים שממחישה איך תוספים ופקודות משתלבים כדי לפעול כמנהל פרויקט פרואקטיבי ולבצע סטנדרטיזציה של מחזור חיים של פיתוח שלם.

9. הקרב נגד הבוס

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

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

איך מאתרים את המיקום של הנציג

כדי להיכנס לזירת הקרב, אתם צריכים להשיג שני מפתחות: החתימה הייחודית של הדמות שלכם (Agent Locus) והנתיב הנסתר למאורה של Spectre (כתובת ה-URL של הצינוק).

‫👉💻 קודם כל, צריך לקבל את הכתובת הייחודית של הסוכן ב-Agentverse – המיקום שלו. זוהי נקודת הקצה הפעילה שמחברת את הדמות הראשית לזירת הקרב.

. ~/agentverse-developer/set_env.sh
echo https://shadowblade-agent-${PROJECT_NUMBER}.${REGION}.run.app

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

. ~/agentverse-developer/set_env.sh
echo https://agentverse-dungeon-${PROJECT_NUMBER}.${REGION}.run.app

חשוב: צריך להכין את שתי כתובות ה-URL האלה. תצטרכו אותם בשלב האחרון.

התמודדות עם פרצת Spectre

אחרי שמוצאים את הקואורדינטות, מנווטים אל Translocation Circle ומטילים את הכישוף כדי לצאת לקרב.

‫👈 פותחים את כתובת ה-URL של מעגל ההעברה בדפדפן כדי לעמוד מול הפורטל הנוצץ אל The Crimson Keep.

כדי לפרוץ למבצר, צריך להתאים את מהות ה-Shadowblade לפורטל.

• בדף, מחפשים את שדה להזנת קלט של הכתובת בכתב הרוני, שמסומן בתווית A2A Endpoint URL.
• כדי להוסיף את הסמל של הדמות הראשית, מדביקים את כתובת ה-URL של מיקום הסוכן (כתובת ה-URL הראשונה שהעתקתם) בשדה הזה.
• לוחצים על 'חיבור' כדי להפעיל את הקסם של הטלפורטציה.

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

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

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

זה טבע הקרב. הידע שלך הוא הנשק שלך.

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

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

מיקוד. פגיעה בול במטרה. הגורל של Agentverse תלוי בזה.

מזל טוב, Shadowblade.

סיימת בהצלחה את הקודקס. השתמשתם ב-Gemini CLI כדי להרכיב סוכן חכם על סמך אווירה שהייתה לכם, שתרגמתם לעיצוב. הוא חרט את הכישוף Wards of Purity כדי לבדוק את הלוגיקה שלו, בנה כפפה אוטומטית כדי לזייף אותו לחפץ, ושיחרר אותו ל-Agentverse. לבסוף, אימתתם את המטרה שלה בניסוי חי. השלמתם את תהליך העבודה המלא של סוכנים ואתם מוכנים לכל אתגר שיוצב בפניכם ב-Agentverse.

10. ניקוי: השבתת Agentverse

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

השבתה של רכיבי Agentverse

עכשיו תפרק באופן שיטתי את הרכיבים שפרסת ב-Agentverse.

מחיקת Shadowblade Agent ב-Cloud Run ובמאגר Artifact Registry

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

‫👈💻 בטרמינל, מריצים את הפקודה:

. ~/agentverse-developer/set_env.sh
gcloud run services delete shadowblade-agent --region=${REGION} --quiet
gcloud run services delete agentverse-dungeon --region=${REGION} --quiet
gcloud artifacts repositories delete ${REPO_NAME} --location=${REGION} --quiet

ניקוי של קבצים וספריות מקומיים (Cloud Shell)

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

‫👈💻 בטרמינל, מריצים את הפקודה:

rm -rf ~/agentverse-developer
rm -rf ~/agentverse-dungeon
rm -f ~/project_id.txt
gemini extensions uninstall nanobanana
rm -rf ~/.gemini # This removes all Gemini CLI configurations, including extensions, skills, and hooks.

מחקתם בהצלחה את כל העקבות של השימוש ב-Agentverse. הפרויקט שלכם נקי, ואתם מוכנים להרפתקה הבאה.