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 --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
הנשק הראשי שלכם מודע עכשיו למטרה שלו.
👈💻 כדי לצאת מ-Gemini CLI, מקישים פעמיים על Ctrl+C
5. Analyzing the Battlefield: Practical Vibe Coding Interaction
תרגילי האימון הושלמו. למדתם את העמדות והמכות הבסיסיות של הנשק העיקרי שלכם, Gemini CLI. אבל אי אפשר לשלוט בלהב באמת עד שהוא נבדק בכבשן היצירה והותאם לארסנל המלחמה. לפני שמתמודדים עם האויב האמיתי, צריך קודם לבדוק את הסביבה הקרובה ולעצב אותה – שדה הקרב הדיגיטלי.
בפרק הזה נסביר איך עוברים מתיאוריה למעשים. קודם כול, תצרו נוכחות ב-Agentverse באמצעות הפקודה ליצירת חתימה דיגיטלית ב-Gemini, בצורה של אתר אישי שנבנה רק על סמך הכוונה שלכם. לאחר מכן, תוכלו להרחיב את היכולות שלכם על ידי הפעלת ארסנל מקומי של כלים מתקדמים – שרת MCP – והתאמת הלהב לתדר שלו, מה שיאפשר לכם לבצע תמרונים מורכבים כמו ניהול מאגרי קוד באמצעות פקודות פשוטות וחד-משמעיות.
יצירת חותם היוצר
לוחמי Shadowblade אמיתיים מזוהים לא רק לפי הנשק שלהם, אלא גם לפי הסגנון הייחודי שלהם – הסימן של היוצר. הסימן הזה יהיה הנוכחות הדיגיטלית שלכם, פרופיל אישי שמציג את הזהות שלכם ב-Agentverse. בשלב הזה, תתנו ל-Gemini Blade פקודה להפעיל את הטכניקה המורכבת שנדרשת להגדרת הזהות הזו.
👈💻 אם סגרתם את Gemini CLI, בקטע הקודם, הקפידו להפעיל אותו שוב. במסוף, מריצים את הפקודה
clear
cd ~/agentverse-developer/tabletop
gemini --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. Make sure you have a place holder spot for profile picture.
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.
הערה: יכול להיות שיידרשו כמה ניסיונות כדי שהחלק הזה יפעל בצורה תקינה. אם הבעיה נמשכת אחרי 3-4 ניסיונות, יוצאים מ-Gemini CLI על ידי הקלדת /quit או לחיצה על Ctrl+C פעמיים, ואז 👉💻 מריצים את הפקודה הבאה במסוף.
python3 -m http.server
👀 כדי לראות את העבודה שלכם, לוחצים על הסמל Web preview (תצוגה מקדימה של האינטרנט) בסרגל הכלים של Cloud Shell. בוחרים באפשרות שינוי היציאה, מגדירים אותה ל-8000 ולוחצים על שינוי ותצוגה מקדימה. תופיע תצוגה מקדימה של האתר. 
יכול להיות שהאתר שלכם ייראה שונה משלי. זהו הסימן הייחודי שלכם. 
👈✨ הטכניקה שלך לחתימה השתפרה, ולא צריך יותר את הסימולציה בזמן אמת. תגיד ל-Blade להפסיק.
Stop the Shadowblade Profile website
👈💻 הערה: אם מריצים את הפקודה הזו מחוץ ל-Gemini CLI, צריך להקיש על Ctrl+C כדי לצאת משרת ה-HTTP.
הצלחתם להנחות את Gemini CLI לבצע סדרה של פעולות בשמכם. אבל לוחם Shadowblade מנוסה יודע שכדי להשיג כוח אמיתי צריך משמעת וראייה לטווח ארוך. מתן הרשאה לסוכן AI להריץ פקודות ישירות בסביבה שלכם הוא חרב פיפיות. מה קורה אם הפקודה לא הייתה להפעלת שרת אינטרנט פשוט, אלא למחיקת קבצים קריטיים? פקודה לא זהירה עלולה להרוס את כל שדה האימונים.
לכן, האומנים החכמים ביותר מתרגלים את הטכניקות החזקות ביותר שלהם או טכניקות שהם לא ניסו קודם במגרש אימונים מוגן – מימד סגור שנקרא ארגז חול.
👈💻 כדי לצאת מ-Gemini CLI, מקישים פעמיים על Ctrl+C
ארגז החול של Gemini CLI (gemini --sandbox) יוצר מאגר זמני ומבודד עבור הסשן שלכם. כל פקודה שה-AI מבצע, כל קובץ שהוא כותב וכל תהליך שהוא מתחיל, קיימים רק בתחום הדמיוני הזה. הוא לא יכול לגעת בסביבת Cloud Shell האמיתית שלכם, לשנות אותה או לגרום לה נזק. זה המקום המושלם לבדוק כלים חדשים ועוצמתיים, לנתח קוד לא מוכר או לתת ל-AI הוראות מורכבות בלי לחשוש מהשלכות לא רצויות. היא מייצגת את הזהירות של Shadowblade.
👈💻 עכשיו, תבצעו טקס של הכלה כדי להבין את הכוח שלה.
clear
gemini --sandbox --yolo
- אם מוצגת השאלה
Do you want to connect Cloud Shell editor to Gemini CLI?, בוחרים באפשרות לא. - אם מוצגת בקשה להתחבר, פועלים לפי ההוראות כדי להתחבר באמצעות התחברות באמצעות Google
עכשיו אתם פועלים במאפיין המבודד. מבחינת Gemini CLI, הכול ייראה כרגיל. בואו נוכיח את זה.
👈💻 מריצים את הפקודה הבאה כדי שהלהב יבצע את אותה טכניקה כמו קודם:
Use the Python's built-in web server to start the Shadowblade Profile website, you just created.
Gemini ידווח על הצלחה, כי הוא יניח שהוא הצליח להפעיל את האתר שלכם שוב ביציאה 8000. אבל ההגנה נשארת חזקה.
👈 עוברים אל תצוגה מקדימה באינטרנט ומנסים להציג את האתר ביציאה 8000.
בפעם הזו, תופיע שגיאה. החיבור ייכשל. אין לך גישה לאתר.
זו לא תקלה בכלי, אלא הוכחה ליכולות של ארגז החול. שרת האינטרנט פועל, אבל הוא פועל בתוך המימד הכלול, ומבודד לחלוטין מהדפדפן ומהעולם החיצוני. החדר פועל בצורה מושלמת. השתמשתם בהצלחה בטכניקה עוצמתית שלא הייתה לה השפעה על הסביבה בפועל.
👉💻 כדי לצאת מ-Gemini CLI, לוחצים פעמיים על Ctrl+C.
הזהות הדיגיטלית שלכם נוצרה, וחשוב מכך, למדתם את החוכמה הקריטית של שימוש בכוח רב בזהירות רבה עוד יותר.
הפעלת כלי מקומיים: Gitea Armory
הפוטנציאל האמיתי של 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). בטרמינל, מריצים את הפקודה:
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 --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 הועבר לארכיון באופן בטוח.
👈✨ סמל ה-sigil מגדיר את ה-Shadowblade, אבל כמו שאתם זוכרים, תמונת הפרופיל חסרה באתר שלכם. אומן מומחה מודה בפגמים שלו כדי לשפר אותם. עליך לתעד את הפגם הזה ברשומות של מחסן הנשק.
File an issue for me in the shadowblade-profile repo. The issue is that the profile image is missing.
הצגת הבעיה ב-Gitea 
כדי ליצור את הסמל החסר, צריך להפעיל כוח מסוג אחר – רוח יצירה מ-Vertex AI שיכולה ליצור תמונות ממחשבה טהורה. לשם כך נדרש פורטל MCP נוסף.
👈💻 כדי לצאת מ-Gemini CLI, מקישים פעמיים על Ctrl+C
👈💻 קודם כול, מתקינים את השרת של הפורטל. בטרמינל, מריצים את הפקודה:
echo 'export PATH="$PATH:$HOME/go/bin"' >> ~/.bashrc
source ~/.bashrc
cd ~/vertex-ai-creative-studio/experiments/mcp-genmedia/mcp-genmedia-go
./install.sh
👉 כשמוצגת בקשה, בוחרים באפשרות mcp-imagen-go (בדרך כלל 4, אבל לפעמים המספרים משתנים), כי אנחנו צריכים ליצור רק תמונה לפרופיל.
👈💻 כדי ליצור, צריך כלי קדוש – קטגוריה של 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 --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.
👈✨ הרוח תיצור את התמונה ותמקם אותה בכלי הקדוש שלכם. עכשיו, נותנים לפלדה פקודה להשתמש בחותם החדש שנוצר. (GEMINI MIGHT ALREADY DID THIS FOR YOU! כדאי לבדוק את התשובה הקודמת, יכול להיות שהיא מספיק חכמה כדי לעשות את זה לפני שתבקשו ממנה!!!! )
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
👀 כדי לראות את העבודה שלכם, לוחצים על הסמל Web preview (תצוגה מקדימה של האינטרנט) בסרגל הכלים של 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"
👀 כדי לראות את העבודה שלכם, לוחצים על הסמל Web preview (תצוגה מקדימה של האינטרנט) בסרגל הכלים של Cloud Shell. בוחרים באפשרות שינוי היציאה, מגדירים אותה ל-3005 ולוחצים על שינוי ותצוגה מקדימה. תופיע תצוגה מקדימה של האתר. 
👉✨ מוודאים ב-Gitea שהתמונה עודכנה והבעיה נסגרה. העבודה שלך הושלמה. תשבית את השרת.
stop website server
👈💻 מקישים פעמיים על Ctrl+C כדי לצאת.
למי שלא משחק
6. הרכבת סוכן Shadowblade: קוד Vibe עם הגבלות
הגיע הזמן לתרגל. ההד של הפלדה על האבן דועך. השתלטתם על הנשק הראשי והכנתם את הארסנל למלחמה. עכשיו, תעברו את המבחן האמיתי של Shadowblade: הרכבת הלוחם עצמו. זוהי אומנות של הפיכת לוגיקה לחיים, באמצעות תוכנית קדושה מתוך הקודקס, כדי לבנות את ליבת האינטליגנציה של סוכן – ליצור משתמש בעל תבונה בלהבים שבארסנל שלכם, שיכול לחשוב, להסיק מסקנות ולפעול בעצמו.
המשימה הראשונה היא להיכנס לסדנה קיימת – בסיס קוד מוכן מראש – וליצור ממנה את הדמות שלכם.
The Assembly Ritual
לפני הניצוץ הראשון בכבשן, טכנאי מומחה בוחן את בית המלאכה שלו, ומבין כל כלי וכל תרשים. כשנכנסים לשדה קרב לא מוכר כמו בסיס קוד גדול וקיים, העדיפות הראשונה היא לבצע סיור מקדים. חשוב להבין את המצב הקיים – הארכיטקטורה הקיימת, המטרות הסופיות והפרוטוקולים של ההתקשרות. רק אם תכירו את התוכניות של המבצר ואת הסטנדרטים שלו, תוכלו לתרום את הכישורים שלכם בצורה יעילה.
Gemini CLI, הסייר שתמיד זמין, יכול לעזור לכם בסיור הזה:
- לספק סיכומים ברמה גבוהה: הוא יכול לקרוא את כל הקודקס (או בסיס הקוד) ולתת לכם הבנה מהירה של המטרה והרכיבים העיקריים שלו.
- עזרה בהגדרת הסביבה: הוא יכול להדריך אתכם בתהליכי ההתקנה של כלים ובהגדרת המחשב.
- ניווט בבסיסי קוד: הוא יכול לשמש כמדריך שיעזור לכם לחקור לוגיקה מורכבת ולמצוא קטעים נסתרים בקוד.
- יצירת מסמכי הדרכה: הוא יכול ליצור מסמכים מותאמים אישית שמסבירים את המטרות, התפקידים והמשאבים של בעלי ברית חדשים שמצטרפים למאבק שלכם.
- אוטומציה של למידה ושאלות ותשובות: הוא הופך להיות חוקר אישי, ועונה על שאלות לגבי תכונות או התנהגות של קוד, כך שאתם יכולים להילחם באופן עצמאי יותר.
👈💻 במסוף הראשון, עוברים לספרייה shadowblade ומזמנים את שותף ה-AI:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/shadowblade
clear
gemini --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 --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 ליצור שבעה כלי נשק חדשים לארסנל. מזינים את ההנחיה הבאה ב-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 המיומן.
אחרי שהסוכן נוצר ועבר שיפורים, הגיע הזמן להפעיל אותו.
👈💻 כדי לצאת מ-Gemini CLI, מקישים פעמיים על Ctrl+C
הערת מפתח לגבי הפלט של 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 לבצע משימות מורכבות שדורשות חשיבה. ההתנהגות שלהם היא תוצאה של אינטראקציה בין רכיבים שונים. המשמעות היא שצריך להעריך לא רק את איכות הפלט הסופי, אלא גם את היעילות והדיוק של המסלול הפנימי שלו. הנתיב שבו השתמשתם כדי להגיע לשם. האם הוא השתמש בכלים הנכונים? האם נוצרו יותר מדי טוקנים? האם שינוי בגרסת המודל גרם לרגרסיה קלה של זמן האחזור? חשוב מאוד לזהות את השחיתות הזו – רגרסיות בחביון, בעלות או באיכות הפלט – כשמבצעים כל שינוי, החל משינוי פשוט בהנחיה ועד לשיפוץ ארכיטקטוני משמעותי, לפני שהיא עלולה לפגוע בסביבת הייצור.
הגישה הכללית להערכה הזו כוללת טקס קדוש:
- קודם כל, מגדירים "מערך נתונים מושלם". קבוצה של מגילות שמכילות דוגמאות לקלט ולפלט או להתנהגויות הצפויות שלהן. התשובות יכולות לכלול תשובות סופיות, שימוש נכון בכלי או אפילו מסלולים שלמים של שלבים.
- בשלב הבא מגדירים את הלוגיקה של האפליקציה של הסוכן, שהיא הליבה של הישות שלו.
- לבסוף, מגדירים בודקים, שהם כמו רונות של שיפוט. הם יכולים להיות מודלים גדולים של שפה אחרים שפועלים כשופטים של איכות, קוד היוריסטי מדויק שמאמת שלב אחד או פונקציות מותאמות אישית שמנתחות את כל תהליך החשיבה של הסוכן.
ערכת פיתוח הסוכנים (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 --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.
👉💻 כדי לצאת מ-Gemini CLI, לוחצים פעמיים על Ctrl+C.
הכללים של שיפוט
אי אפשר להשתתף בתחרות ללא כללים לניצחון. לפני שמריצים את תקופת הניסיון, צריך לבדוק את מגילת הדין – הקובץ 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 נבדקה אסטרטגיה רחבה. ההגנה השנייה, Shield of Clarity (מגן הבהירות), בודקת משמעת והתנהגויות ספציפיות. המאמר הזה עוסק באוטומציה. adk eval הוא כלי מצוין לבדיקות ידניות, אבל המגן pytest הוא אמצעי הגנה שכתוב בקוד. זה חשוב מאוד כי אפשר לשלב צינור אוטומטי לעיבוד נתונים עם בדיקה שאפשר להריץ כקוד. המטרה הסופית היא ליצור Deployment Gauntlet (CI/CD) שבו ההגנות שלנו מופעלות באופן אוטומטי בכל פעם שמבוצע שינוי, כדי למנוע באגים ונסיגות לפני שהם יכולים לפגוע בסביבת הייצור.
👉💻 במסוף,מזמנים שוב את Gemini מתוך ספריית shadowblade:
. ~/agentverse-developer/set_env.sh
cd ~/agentverse-developer/
clear
gemini --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.
אחרי שגם ה-Gauntlet הרחב וגם ה-Shield המדויק נכתבו ואומתו, הנציג שלכם לא רק מתפקד – הוא טהור, נבדק ומוכן לפריסה.
למי שלא משחק
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 --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="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. הטקסים של הקודקס הושלמו. הגיע הזמן להוכיח את יכולותיה. ממתין לכם אתגר בדמות רוח רפאים, שנולדה מהכאוס שאתם למדתם לאלף. התכוננו למבחן הסופי.
למי שלא משחק
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
אחרי שרושמים את הקואורדינטות, מנווטים אל 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
מחיקת הקטגוריה של 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. הפרויקט שלכם נקי, ואתם מוכנים להרפתקה הבאה.