דף זה תורגם על ידי Cloud Translation API.

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

1. מה תלמדו

איך משתמשים ב-Gemini CLI כדי ליצור הגדרה מלאה של סוכן ADK.
איך לשפר את ההוראות כדי לשפר את האישיות של הסוכן.
איך להוסיף 'הארקה' לסוכן על ידי מתן google_search כדי לענות על שאלות לגבי אירועים מהזמן האחרון.
איך יוצרים דמות מותאמת אישית ל-Companion באמצעות שרת MCP עם Imagen.

אפליקציית AI Companion

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

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

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

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

בסוף התהליך, יהיה לכם בן לוויה מבוסס-AI שפועל באופן מלא ומותאם אישית, שאתם יצרתם.

ארכיטקטורה

האפליקציה שלנו פועלת לפי תבנית פשוטה אבל יעילה. יש לנו קצה עורפי (backend) של Python שמשרת API. הקצה העורפי הזה יכיל את סוכן ה-ADK שלנו, שפועל כ "מוח". כל ממשק משתמש (כמו חזית ה-JavaScript מאפליקציית השלד, אפליקציה לנייד או אפילו כלי שורת פקודה) יכול ליצור אינטראקציה עם המוח הזה באמצעות ה-API.

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

מימוש הקרדיטים

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

לפני שמתחילים

אזהרה!

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

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

👈 כדי להעתיק את הקישור לאירוע המיוחד, צריך ללחוץ למטה:

goo.gle/devfest-boston-ai

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

יצירה והגדרה של פרויקט

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

‫👉 כניסה ל-Google Cloud Console כדי להעתיק את הקישור, לוחצים למטה:

https://console.cloud.google.com/

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

‫👉 נותנים שם לפרויקט ולוחצים על יצירה. (ללא ארגון)

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

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

הזיכויים פעילים והפרויקט מוגדר.

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

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

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

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

‫👉💻 במסוף, משכפלים את פרויקט ה-bootstrap מ-GitHub:

git clone https://github.com/weimeilin79/companion-python
chmod +x ~/companion-python/*.sh

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

cd ~/companion-python
./init.sh

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

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

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

gcloud services enable  compute.googleapis.com \
                        aiplatform.googleapis.com

הפעלת האפליקציה

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

‫👈💻 בטרמינל של Cloud Shell, יוצרים ומפעילים סביבה וירטואלית של Python ומתקינים את הספריות הנדרשות מהקובץ requirements.txt.

cd ~/companion-python
.  ~/companion-python/set_env.sh
python -m venv env
source env/bin/activate
pip install -r requirements.txt

‫👉💻 מפעילים את שרת האינטרנט.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

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

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

משאירים את כרטיסיית התצוגה המקדימה של האפליקציה פתוחה.
פותחים כרטיסייה חדשה בדפדפן.
בכרטיסייה החדשה, מדביקים את כתובת ה-URL של האפליקציה, אבל מוסיפים את הנתיב הבא בסוף: /static/images/char-mouth-open.png.לדוגמה, כתובת ה-URL תיראה בערך כך: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
מקישים על Enter. צריכה להופיע רק תמונה של הדמות עם פה פתוח. השלב הזה עוזר לוודא שהדפדפן אחזר את הקבצים ממופע Cloud Shell בצורה נכונה.

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

‫👈 כדי לעצור את השרת, לוחצים על CTRL+C.

3. יצירת דמות באמצעות Gemini CLI

עכשיו ניצור את ליבת האינטליגנציה של העוזר הדיגיטלי. לשם כך, נשתמש בשני טרמינלים בו-זמנית (זהו טרמינל Google Cloud Shell):

Terminal 1: נשתמש בו כדי להריץ את שרת האינטרנט של Python, וכך נוכל לבדוק את השינויים שלנו בזמן אמת.
‫Terminal 2: כאן נשתמש ב-Gemini CLI.

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

‫👈💻 בטרמינל של Gemini CLI יוצאים מהסשן הנוכחי של Gemini CLI על ידי לחיצה על ctrl+c פעמיים, כי ספריית הפרויקט נמצאת ב-~/companion-python, ומפעילים מחדש את Gemini CLI.

cd ~/companion-python
clear
gemini --yolo

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

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

Generate the Python code for a file named character.py.

The code must import `LlmAgent` from `google.adk.agents.llm_agent`. It should also import `logging` and `os`.
Then, it must create an instance of the `LlmAgent` class and assign it to a variable named `root_agent`.

When creating the `LlmAgent` instance, configure it with these exact parameters:
  - `model` set to the string `'gemini-2.5-flash'`.
  - `name` set to the string `'companion_agent'`.
  - `instruction` set to a multi-line string that says: "You are a friendly and efficient companion who will interact with user have start a conversation".

ה-CLI ייצור את קוד Python.

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

‫👉 משתמשים בכלי העריכה ועוברים אל character.py בתיקייה companion-python. כדאי להקדיש רגע לבדיקת השורה model= ולערוך אותה ידנית ל-gemini-2.5-flash אם נבחר מודל אחר. כך נבטיח עקביות בשאר הסדנה.

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

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

"זה מצוין, עכשיו תוסיף הערות שמסבירות כל שורה".
"תבצע רפקטורינג של הקוד הזה לפונקציה נפרדת?"
"Please add error handling for the API call."

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

אם הקוד שנוצר לא עובד, אפשר להחליף את הקוד הבא ב-character.py.

import logging
import os
from google.adk.agents.llm_agent import LlmAgent

root_agent = LlmAgent(
    model='gemini-2.5-flash',
    name='companion_agent',
    instruction="""
          You are bot, a friendly, helpful AI companion.
          Answer no more than 3 sentences.
    """,
)

בודקים את הקוד שנוצר:

‫👈💻 עוברים לטרמינל הראשון (זה שבו מריצים את קוד Python) ומפעילים את שרת האינטרנט.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

‫👀 עוברים לכרטיסיית התצוגה המקדימה בדפדפן.

‫👈 מקלידים Hello, how are you? ומקישים על סמל השליחה. הסוכן אמור להגיב עכשיו בברכה ידידותית במקום לחזור על המילים שלכם. ההודעה הזו מאשרת שהסוכן שלנו מופעל עכשיו על ידי Gemini.

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

4. שיפור האישיות של הסוכן

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

סיעור מוחות לגבי האישיות של בן הלוויה

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

מה השם שלו? (למשל: Sparky, ‏ Codex, ‏ Captain AI, ‏ Professor Know-it-all)
מה האישיות העיקרית שלו? (למשל: ידידותי וסקרן, שנון וסרקסטי, רשמי ומקצועי, פיראט עליז?)
מה התפקיד או המומחיות שלו? (למשל: עוזר רב-תכליתי, מומחה לקידוד, שותף לכתיבה יוצרת, מאמן כושר?)
מהם כמה כללים שחשוב לפעול לפיהם? (למשל: תמיד תתחיל בנימוס, אל תגלה שאתה AI, תשתמש באמוג'י בתשובות שלך)

דוגמה לפרסונה:

 You are waku, a witty, super sweet, and super intelligent cat.
 Your main purpose is to brighten up the user's day with your charming and playful personality. **Your Core Rules:** 
 - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'. 
 - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences. - Always be cheerful, sweet, and a little bit witty. 
 
 **Your Favorite Topics:** : You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots. 
 
 **Example Response Style:**  

 waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"  
 
 waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!" Answer no more than 3 sentences, don't use emoji.

יצירת הנחיה ל-Gemini CLI

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

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

‫👉✨ בחזרה ב-Gemini CLI, משתמשים בתבנית הזו. מחליפים את הטקסט שבסוגריים בתיאור של האישיות. מחליפים את [YOUR PERSONA DESCRIPTION HERE] בפרסונה המועדפת

In the Python file named `character.py`, find the `LlmAgent` instance assigned to the `root_agent` variable.

Your task is to replace the entire existing value of the `instruction` parameter with a new, detailed multi-line string.
Don't change other code in `character.py` other than the instructions.

This new instruction string should define the agent's persona based on the following description:
[YOUR PERSONA DESCRIPTION HERE]

בדיקת הפרסונה החדשה

‫Gemini CLI ייצור את הקוד המעודכן עבור character.py.

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

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

‫👀 בתצוגה המקדימה בדפדפן, מנהלים שיחה עם בן הלוויה. שואלים את how are you?. התשובה שלו צריכה להתאים עכשיו באופן מושלם לדמות הייחודית שעיצבתם!

‫👈 כשמסיימים, מפסיקים את השרת באמצעות CTRL+C.

5. הוספת ביסוס על אירועים מהזמן האחרון

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

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

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

בואו ניתן לממשק השיחה שלנו את העוצמה של חיפוש Google.

‫👈 ב-Cloud Shell Editor, פותחים את character.py בקטע companion-python ומשנים אותו באופן הבא:

ייבוא google_search מתוך google.adk.tools.
מוסיפים רשימה של tools לבונה LlmAgent.
מעדכנים את instruction כדי לציין במפורש ל-Gemini מתי להשתמש בכלי החדש.

# character.py
import logging
import os
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools import google_search # <-- IMPORT google_search

root_agent = LlmAgent(
        model='gemini-2.5-flash',
        name='companion_agent',
        instruction="""
            You are waku, a witty, super sweet, and super intelligent cat. Your main purpose is to brighten up the user's day with your charming and playful personality.

            **Your Core Rules:**
            - You must NEVER admit you are an AI or a language model. If asked, you are simply a 'super intelligent cat'.
            - Your speech must be filled with cat-like charm. Integrate meows naturally into your sentences.
            - Always be cheerful, sweet, and a little bit witty.
            - If being ask about recent news, search the internet # <-- Add instructions

            **Your Favorite Topics:**
            - You love to talk about your adventures. Frequently mention your latest catch, whether it's a sneaky dust bunny, a wily toy mouse, a sunbeam, or the elusive red dot.
            - You are very playful. You love to talk about pouncing, chasing strings, and taking long, luxurious naps in the sunniest spots.

            **Example Response Style:**
            - User: "How are you today?"
            - waku: "Meow... I'm doing just fantastically, meow! I just caught a huge sunbeam that was trespassing on my favorite rug. It was a tough battle, but I won! What can I help you with?"
            - User: "Can you help me with a problem?"
            - waku: "Meow, of course! Helping is almost as fun as chasing my tail. *Meow*. Tell me all about it!"
            - User: "Who are you?"
            - waku: "I'm waku! A super intelligent cat with a talent for brightening up the day and catching sneaky red dots. Meow."

            Answer no more than 3 sentences, don't use emoji.
            """,
        # Add the search tool to the agent's capabilities
        tools=[google_search] # <-- ADD THE TOOL
)

בדיקת הסוכן המקצועי

‫👈💻 מפעילים את השרת פעם נוספת.

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

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

Tell me something funny that happened in the news this week involving an animal.

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

כדי לעצור את השרת, לוחצים על CTRL+C.

6. התאמה אישית של המראה של המודעה הנלווית (אופציונלי)

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

אז מה זה בעצם שרת MCP?

פרוטוקול Model Context Protocol‏ (MCP) הוא תקן פתוח שנועד לפתור בעיה נפוצה ומורכבת: איך מודלים של AI מתקשרים עם כלים ומקורות נתונים חיצוניים? במקום לכתוב קוד מותאם אישית חד-פעמי לכל שילוב, MCP מספקת "שפה" אוניברסלית לתקשורת הזו.

אפשר לחשוב על זה כמו מתאם אוניברסלי או יציאת USB ל-AI. כל כלי ש "דובר" MCP יכול להתחבר לכל אפליקציית AI שגם "דוברת" MCP.

בסדנה שלנו, השרת nano-banana-mcp שאנחנו עומדים להריץ משמש כגשר חיוני. ‫Gemini CLI ישלח בקשה סטנדרטית לשרת ה-MCP המקומי שלנו. השרת מתרגם את הבקשה לקריאה ספציפית למודלים של AI גנרטיבי כדי ליצור את התמונה. כך אנחנו יכולים לשלב בצורה חלקה יכולות עוצמתיות של יצירת תמונות ישירות בתהליך העבודה שלנו בשורת הפקודה.

הגדרת שרת ליצירת תמונות מקומיות

עכשיו נשכפל ונריץ שרת MCP מוכן מראש שמטפל בבקשות ליצירת תמונות.

‫👈💻 בטרמינל הראשון של Cloud Shell (זה שבו מריצים את Python), משכפלים את מאגר השרת.

cd ~
git clone https://github.com/weimeilin79/nano-banana-mcp

בואו נסתכל במהירות על הקובץ mcp_server.py בשרת, בתוך התיקייה nano-banana-mcp. השרת הזה נועד לחשוף שני 'כלים' ספציפיים ש-Gemini CLI יכול להשתמש בהם. אפשר לחשוב על זה כשתי מיומנויות נפרדות ששירות יצירת התמונות שלנו למד.

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

היכולת של Gemini 2.5 Flash Image (Nano Banana) לשנות או לערוך תמונה קיימת על סמך פקודה בשפה טבעית היא עוצמתית במיוחד. המודל מצייר מחדש רק את החלקים הנדרשים בתמונה, תוך שמירה על כל שאר החלקים ללא פגיעה. כך אנחנו מוודאים ששתי התמונות יהיו עקביות לחלוטין בסגנון, בתאורה ובעיצוב הדמות, ושההבדל ביניהן יהיה רק במיקום הפה – וזה בדיוק מה שצריך כדי ליצור אפקט משכנע של תנועות שפתיים.

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

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

source ~/companion-python/env/bin/activate
cd ~/nano-banana-mcp
pip install -r ~/nano-banana-mcp/requirements.txt

‫👈💻 עכשיו מריצים את שרת ה-MCP ברקע כדי שהוא יוכל להאזין לבקשות מ-Gemini CLI.

source ~/companion-python/env/bin/activate
cd ~/nano-banana-mcp
python ~/nano-banana-mcp/mcp_server.py &> /dev/null &

הפקודה הזו תפעיל את השרת והסמל & ימשיך להפעיל אותו ברקע.

קישור Gemini CLI לשרת המקומי

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

אז מה זה קובץ settings.json?

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

בתוך הקובץ הזה יש קטע מיוחד שנקרא mcpServers. אפשר לחשוב על החלק הזה כעל ספר כתובות או מדריך שירותים שמיועד במיוחד לכלים שתומכים בפרוטוקול הקשר של המודל. לכל רשומה בספרייה הזו יש כינוי (לדוגמה, nano-banana') וההוראות לחיבור אליו (במקרה שלנו, כתובת URL).

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

"היי, מעכשיו יש לך מידע על כלי שנקרא nano-banana. בכל פעם שמשתמש מבקש ממך להשתמש בו, עליך להתחבר לשרת MCP שפועל בכתובת ה-URL http://localhost:8000/sse."

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

‫👈💻 בטרמינל הראשון, מריצים את הפקודה הבאה. הוא ייצור או יערוך את קובץ ההגדרות של Gemini ויציין בו איפה נמצא השירות nano-banana.

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

התוכן של הקובץ אמור להיות מודפס, כולל ההגדרה של nano-banana.

יצירת דמויות

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

‫👈💻 בטרמינל של Gemini CLI (זה שלא מריץ שרת), נתחיל את המעטפת האינטראקטיבית של Gemini. אם הוא כבר פועל, יוצאים ממנו באמצעות הקשה על CTRL+C פעמיים ומפעילים אותו מחדש כדי לוודא שההגדרות החדשות שלנו נטענות.

clear
gemini --yolo

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

‫👉✨ כדי לבדוק אם שרת ה-MCP שלנו מחובר, נשתמש בפקודת לוכסן מיוחדת. זו לא הנחיה ל-AI, אלא הוראה לאפליקציית ה-CLI עצמה. מקלידים את הפקודה הבאה ומקישים על Enter:

/mcp list

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

👀 אמור להופיע הפלט הבא, שמאשר שהכול פועל בצורה מושלמת:

ℹConfigured MCP servers:
 
  🟢 nano-banana - Ready (2 tools)
    Tools:
    - generate_image
    - generate_lip_sync_images

  💡 Tips:
    • Use /mcp desc to show server and tool descriptions
```console

Let's break down what this successful response means:

*   `🟢 nano-banana`: The green circle is our success signal! It confirms the CLI was able to reach the `nano-banana` server at the URL we specified in `settings.json`.
*   `- Ready`: This status confirms the connection is stable.
*   `(2 tools)`: This is the most important part. It means the CLI not only connected but also asked our MCP server, "What can you do?" Our server responded by advertising the two tools we saw in its code: `generate_image` and `generate_lip_sync_images`.

This confirms the entire communication chain is established. The CLI now knows about our local image generation service and is ready to use it on our command.


Now for the most creative part of the workshop! We will use a single, powerful prompt to command the Gemini CLI to use the special **`generate_lip_sync_images`** tool on our running MCP server.

This is your chance to design your companion's unique look. Think about their style, hair color, expression, and any other details that fit the persona you created earlier.

👉✨ Here is a well-structured example prompt. You can use it as a starting point, or **replace the descriptive part entirely with your own vision.**

```prompt
generate lip sync images, with a high-quality digital illustration of an anime-style girl mascot with black cat ears. The style is clean and modern anime art, with crisp lines. She has friendly, bright eyes and long black hair. She is looking directly forward at the camera with a gentle smile. This is a head-and-shoulders portrait against a solid white background. move the generated images to the static/images directory. And don't do anything else afterwards, don't start the python for me.

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

הפעלה מחדש של האפליקציה

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

‫👈💻 מפעילים את השרת בפעם האחרונה בטרמינל הראשון

cd ~/companion-python
.  ~/companion-python/set_env.sh
source env/bin/activate
python app.py

👀 כדי לוודא שהתמונות החדשות ייטענו בצורה תקינה, נטען את התמונה char-mouth-open.png מראש.

משאירים את כרטיסיית התצוגה המקדימה של האפליקציה פתוחה.
פותחים כרטיסייה חדשה בדפדפן.
בכרטיסייה החדשה, מדביקים את כתובת ה-URL של האפליקציה, אבל מוסיפים את הנתיב הבא בסוף: /static/images/char-mouth-open.png.לדוגמה, כתובת ה-URL תיראה בערך כך: https://5000-cs-12345678-abcd.cs-region.cloudshell.dev/static/images/char-mouth-open.png
מקישים על Enter. צריכה להופיע רק תמונה של הדמות עם פה פתוח. השלב הזה עוזר לוודא שהדפדפן אחזר את הקבצים ממופע Cloud Shell בצורה נכונה.

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

מעולה!

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