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

1. של גורל

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

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

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

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

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

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

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

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

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

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

בחירת כיתה

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

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

המשימה שלך

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

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

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

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

2. The Shadowblade's Codex

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

מה תלמדו

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

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

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

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

‫👈כך מוצאים את מזהה הפרויקט ב-Google Cloud:

• פותחים את מסוף Google Cloud: https://console.cloud.google.com
• בוחרים את הפרויקט שבו רוצים להשתמש בסדנה הזו מהתפריט הנפתח של הפרויקט בחלק העליון של הדף.
• מזהה הפרויקט מוצג בכרטיס Project info בלוח הבקרה

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

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

gcloud auth list

‫👈💻 משכפלים את פרויקט ה-bootstrap מ-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

git clone https://github.com/weimeilin79/vertex-ai-creative-studio.git
chmod +x ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go/install.sh

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

cd ~/agentverse-developer
./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. זהו הלהב הכי מגוון שלכם, שיכול לעצב את העולם הדיגיטלי באמצעות הפקודות שלכם. התרגילים האלה יעזרו לכם להכיר את הטיפול הבסיסי ב-Gmail ואת היכולות שלו.

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

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

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

cd ~/agentverse-developer
mkdir tabletop
cd tabletop

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

clear
gemini --model=gemini-2.5-flash --yolo

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

הכרת כלי נשק

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

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

/help

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

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

!ls -l

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

/tools

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

‫👈✨ נשק יעיל רק אם מתמקדים בו כמו שצריך. ה-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 --model=gemini-2.5-flash --yolo

‫👈✨ בעזרת פקודה אחת עוצמתית, אפשר להנחות את 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.

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

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

‫👈✨ ב-Gemini CLI, מריצים את פקודת הסימולציה:

Use Python's built-in web server to start the Shadowblade Profile website you just created.

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

מאשרים את ההצעות לפעולות. ‫Gemini יאשר שהסימולציה פעילה.

‫👀 Gemini CLI יפעל לפי ההוראה ויאשר שהסימולציה פעילה והסימן הדיגיטלי שלכם פעיל:

The website is now being served on port 8000. You can access it at http://localhost:8000.

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

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

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

Stop the Shadowblade Profile website

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

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

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

ארגז החול של Gemini CLI‏ (gemini --sandbox) יוצר מאגר זמני ומבודד עבור הסשן שלכם. כל פקודה שה-AI מבצע, כל קובץ שהוא כותב וכל תהליך שהוא מתחיל, קיימים רק בתחום הדמיוני הזה. היא לא יכולה לגעת בסביבת Cloud Shell האמיתית שלכם, לשנות אותה או לגרום לה נזק. זה המקום המושלם לבדוק כלים חדשים ועוצמתיים, לנתח קוד לא מוכר או לתת ל-AI הוראות מורכבות בלי לחשוש מהשלכות לא רצויות. היא מייצגת את הזהירות של Shadowblade.

‫👈💻 עכשיו, תבצעו טקס של הכלה כדי להבין את הכוח שלה.

clear
gemini --sandbox --yolo

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

Use the Python's built-in web server to start the Shadowblade Profile website, you just created.

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

‫👈 עוברים אל תצוגה מקדימה באינטרנט ומנסים להציג את האתר ביציאה 8000.

בפעם הזו, תופיע שגיאה. החיבור ייכשל. אין לך גישה לאתר.

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

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

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

הפעלת כלי מקומיים: ארסנל Gitea

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

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

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

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

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

cd ~/agentverse-developer
./gitea.sh

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

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

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

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

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

jq '. * {"mcpServers":{"gitea":{"url":"http://localhost:8085/sse"}}}' ~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
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 --model=gemini-2.5-flash --yolo

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

/mcp

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

פרופיל 'סימן היצרן' הוא טכניקה מתוחכמת, אבל צריך למצוא לו מקום מתאים בארסנל – נדן שישמור עליו בצורה מאובטחת. מנחים את 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

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

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

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

echo 'export PATH="$PATH:$HOME/go/bin"' >> ~/.bashrc
source ~/.bashrc
cd ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go
./install.sh

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

‫👈💻 כדי ליצור, צריך כלי קדוש – קטגוריה של Google Cloud Storage – שבו אפשר לאחסן את היצירות. בואו ניצור אחד עכשיו. בטרמינל, מריצים את הפקודה:

. ~/agentverse-developer/set_env.sh
gcloud storage buckets create gs://$BUCKET_NAME --project=$PROJECT_ID

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

. ~/agentverse-developer/set_env.sh
source ~/.bashrc
jq \
--arg bucket "$BUCKET_NAME" \
--arg project "$PROJECT_ID" \
--arg region "$REGION" \
'.mcpServers.imagen = { "command": "mcp-imagen-go", "env": { "MCP_SERVER_REQUEST_TIMEOUT": "55000", "GENMEDIA_BUCKET": $bucket, "PROJECT_ID": $project, "LOCATION": $region } }' \
~/.gemini/settings.json > tmp.json && mv tmp.json ~/.gemini/settings.json
cat ~/.gemini/settings.json

התהליך הזה הוא סקריפט של מעטפת שמגדיר את Gemini CLI לשימוש בכלי חדש ומתקדם: Imagen, מודל ליצירת תמונות של Google. חשוב לציין שההגדרה הזו מתבצעת על ידי הקמת שרת MCP (Model Context Protocol) ל-Imagen. שרת ה-MCP הזה משמש כגשר, ומאפשר ל-Gemini CLI לתקשר עם Imagen ולהשתמש ביכולות שלו. הוא עושה את זה על ידי שינוי ישיר של קובץ התצורה המרכזי של ה-CLI, ‏ ~/.gemini/settings.json, כדי ללמד אותו איך להריץ את הפקודה mcp-imagen-go עם פרטי הכניסה הנכונים לענן.

‫👀 אחרי הטקס, בקובץ settings.json יש בלוק חדש שמלמד את Gemini CLI מיומנות חדשה:

"imagen": {
    "command": "mcp-imagen-go",
    "env": {
        "MCP_SERVER_REQUEST_TIMEOUT": "55000",
        "GENMEDIA_BUCKET": "your-bucket-name",
        "PROJECT_ID": "your-project-id",
        "LOCATION": "your-region"
    }
}

ההנחיה הזו אומרת ל-Gemini CLI: "כשמשימה דורשת שימוש בכלי Imagen, עליך להריץ את התוכנית שנקראת mcp-imagen-go (שהיא שרת Imagen MCP). כשמריצים אותו, צריך לספק לו את הסביבה הספציפית הזו (env): באקט ב-Google Cloud Storage לשמירת התמונות, ומזהה הפרויקט והמיקום לשימוש בממשקי ה-API בענן". הגדרת שרת MCP הזה מאפשרת ל-Gemini CLI גישה ליכולות יצירת התמונות של Imagen."

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

clear
cd ~/agentverse-developer/tabletop/
gemini --model=gemini-2.5-flash --yolo

‫👈✨ בעזרת פקודה אחת חזקה, אפשר להנחות את Gemini CLI לבנות את הבסיס לזהות הדיגיטלית שלכם. ב-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.

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

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

‫👈✨ מפעילים את האתר בפעם האחרונה כדי לראות את העבודה המושלמת.

start the website with a simple HTTP server via Python

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

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

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"

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

‫👉✨ מוודאים ב-Gitea שהתמונה עודכנה והבעיה נסגרה. העבודה שלך הושלמה. תשבית את השרת.

stop website server

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

6. הרכבת סוכן Shadowblade: קוד אווירה עם הגבלות

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

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

The Assembly Ritual

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

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

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

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

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini --model=gemini-2.5-flash --yolo

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

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

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

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

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

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

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

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

download https://raw.githubusercontent.com/weimeilin79/agentverse/main/developer/shadowblade/agent_design.md  and store it to my local folder
and show me the newly downloaded design doc. Do not attempt to create 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 --model=gemini-2.5-flash --yolo

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

/memory show 

זה הרגע המכריע. תספק את הסכימה (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 ליצור שבעה כלי נשק חדשים לארסנל. מזינים את ההנחיה הבאה ב-CLI של Gemini:

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 פעמיים. ההרכבה הושלמה.

7. Wards of Purity: Evaluating the agents

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

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

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

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

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

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

ה-ADK תומך בשתי גישות עיקריות: 'קובצי בדיקה' פשוטים לאינטראקציות נפרדות בין סוכן למודל (דו-קרב יחיד), ו'ערכות הערכה' מקיפות (evalsets) למספר סשנים ארוכים פוטנציאלית עם כמה תורות (קרב רב). הם יכולים למדוד מדדים מורכבים כמו 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 --model=gemini-2.5-flash --yolo

‫👈✨ מריצים פקודה ב-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)

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

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

. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/
clear
gemini --model=gemini-2.5-flash --yolo

‫👉✨ כדי להטביע את הלוגיקה של Shield בקובץ 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 at 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.

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

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

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

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

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

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

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

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

cd ~/agentverse-developer/
clear
gemini --model=gemini-2.5-flash --yolo

‫👉✨ עכשיו, מזינים את הפקודה הבאה ל-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.

לצאת מ-Gemini כדי לבדוק את התוצאה

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

. ~/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 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. הטקסים של הקודקס הושלמו. הגיע הזמן להוכיח את יכולותיה. מפלצת ספקטר, שנולדה מהכאוס שאתם למדתם לאלף, מחכה לאתגר שלכם. התכוננו למשפט האחרון.

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

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

תעברו עכשיו לסימולציה של קרב אש חיה, שבה תתמודדו עם Shadowblade החדש שהצבתם מול 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

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

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

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

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

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

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

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

זה אופי המאבק. הידע שלך הוא הנשק שלך.

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

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

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

מזל טוב, Shadowblade.

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

10. ניקוי: שחזור של Agentverse

כל הכבוד על השלמת המדריך של Shadowblade! כדי לוודא שסביבת 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

מחיקת הקטגוריה של Google Cloud Storage

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

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

. ~/agentverse-developer/set_env.sh
gcloud storage rm -r gs://${BUCKET_NAME} --quiet

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

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

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

rm -rf ~/agentverse-developer
rm -rf ~/agentverse-dungeon
rm -rf ~/vertex-ai-creative-studio
rm -f ~/project_id.txt
rm -rf ~/.gemini # This removes all Gemini CLI configurations, including the MCP server settings.

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

11. למי שלא גיימרים: הסבר על Agentverse בהקשר עסקי

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

Vibecoding עם Gemini CLI: פיתוח 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: פקודה מהירה ותיאורית הפיקה דף אינטרנט פונקציונלי ומעוצב שמבוסס על עיצוב ברמה גבוהה.

שרתי Arsenal ו-MCP מקומיים: חיבור AI לכלים עסקיים

‫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) ל-"File an issue for me in the ‘AI-Fraud-Detection-Module' repo: The data ingestion pipeline is occasionally dropping records."
• נכסים שיווקיים על פי דרישה: צריכים תמונה בהתאמה אישית לקמפיין שיווקי חדש או למצגת פנימית? אפשר לתת לעוזר דיגיטלי מבוסס-AI שמחובר דרך שרת MCP לשירות ליצירת תמונות (כמו Imagen של Google) את ההוראה הבאה: "צור תמונת באנר ל'פלטפורמת תובנות הנתונים' החדשה שלנו, עם נושא עתידני של זרימת נתונים בצבעים כחול וירוק". ה-AI ייצור את התמונה ואולי אפילו יעלה אותה למערכת לניהול נכסים דיגיטליים של החברה (קטגוריה ב-Google Cloud Storage במקרה של ה-codelab).

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

הרכבת הסוכן: יצירת מודולים עסקיים אוטונומיים

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

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

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

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

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

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

Wards of Purity: Automated Testing and Quality Assurance for AI

נציג 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 לשאלה 'איפה החבילה שלי?'). ‫adk eval מריץ אוטומטית את הסוכן דרך השלבים האלה, משווה את התגובות שלו ואת השימוש בכלי מול מערך הנתונים המורחב כדי לוודא שהוא מקבל את ההחלטות הנכונות באופן עקבי.
2. מגן הבהירות (pytest): כדי להגן על פונקציות קריטיות, כותבים סקריפטים של pytest. לדוגמה, pytest יכול לדמות שאילתה מורכבת ולוודא שטכנולוגיית ה-AI תמיד משתמשת בכלי ספציפי לאחזור נתונים בצורה נכונה ומחזירה תשובה מובנית, כדי להבטיח ששינויים קלים בקוד לא יפגעו בפונקציונליות הבסיסית.

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

הלהב החדש: CI/CD לפריסת סוכני AI

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

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

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

אפשר להשתמש בסוכן AI שנועד לזהות עסקאות הונאה.

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

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

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

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

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