מידע על Codelab זה
1. סקירה כללית
איפה מתחילים לבנות עם AI היום? אצל רובנו, התהליך מתחיל בדרך כלל בשאלה פשוטה: "האם המודל יכול לעזור לפתור את הבעיה הזו שחשבתי עליה?". כאן נכנס לתמונה Google AI Studio. זהו מקום שבו אפשר ליצור אבות טיפוס של כל דבר במהירות. אני רוצה לשפץ את המטבח שלי, ואני בטוח ש-Gemini יכול לעזור – אבל אני מהנדס, לא קבלן כללי. אני לא בטוחה מה כדאי לבקש – יש כל כך הרבה דברים שצריך לקחת בחשבון: תקנות, אביזרי חשמל וכו'. אז נחלק את זה לחלקים ונבקש מ-Gemini ליצור עבורנו הנחיה מפורטת במיוחד, ואז ליצור תוכנית שיפוץ מלאה וגם להציג את השיפוץ באופן חזותי! אבל רגע. איך אוכל לעזור לעסקים להתרחב? מזינים AGENTS!!!
סוכן הוא תוכנית אוטונומית שמדברת עם מודל AI כדי לבצע פעולה מבוססת-יעד באמצעות הכלים וההקשר שיש לה, והיא מסוגלת לקבל החלטות אוטונומיות שמבוססות על אמת.
ערכת הפיתוח של סוכן (ADK)
ערכת פיתוח סוכנים (ADK) היא מסגרת גמישה ומודולרית לפיתוח ופריסה של סוכני AI. ADK תומך ביצירת אפליקציות מתוחכמות על ידי שילוב של כמה מכונות סוכנים נפרדות למערכת של סוכנים מרובים (MAS).
ב-ADK, מערכת עם סוכנים מרובים היא אפליקציה שבה סוכנים שונים, שפעמים רבות יוצרים היררכיה, משתפים פעולה או מתואמים כדי להשיג מטרה גדולה יותר. למבנה כזה של האפליקציה יש יתרונות משמעותיים, כולל מודולריות משופרת, התמחות, שימוש חוזר, יכולת תחזוקה ויכולת להגדיר תהליכי בקרה מובְנים באמצעות סוכני תהליכי עבודה ייעודיים.
מה תפַתחו
רוצה לעבור מהאב טיפוס של PROMPT ליצירת סוכן? ניצור סוכן שיעזור ליצור את מסמך ההצעה לפרויקט שיפוץ המטבח. במסגרת שיעור ה-Lab הזה תלמדו:
- פיתוח סוכן פשוט ליצירת מסמך של הצעת שיפוץ באמצעות ADK
- אחסון המסמך שנוצר של הצעת השיפוץ בקטגוריה של Cloud Storage
- בדיקת הסוכן ב-Cloud Shell ובפלט האינטרנט של הסוכן
דרישות
2. לפני שמתחילים
יצירת פרויקט
- בדף לבחירת הפרויקט במסוף Google Cloud, בוחרים פרויקט קיים או יוצרים פרויקט חדש ב-Google Cloud.
- הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט
- אם אתם קוראים את המאמר הזה ואתם רוצים לקבל זיכויים שיעזרו לכם להתחיל להשתמש ב-Google Cloud וב-ADK, תוכלו להשתמש בקישור הזה כדי לממש את הזיכויים.
- כדי לממש את השובר, אפשר לפעול לפי ההוראות כאן. לתשומת ליבך, הקישור הזה תקף למימוש רק עד 15 ביולי 2025.
- לוחצים על הקישור הזה כדי להפעיל את Cloud Shell. אפשר לעבור בין Cloud Shell Terminal (להרצת פקודות ב-Cloud) לבין Editor (ליצירת פרויקטים) בלחיצה על הלחצן המתאים ב-Cloud Shell.
- אחרי שמתחברים ל-Cloud Shell, בודקים שכבר בוצע אימות ושהמזהה של הפרויקט מוגדר כפרויקט באמצעות הפקודה הבאה:
gcloud auth list
- מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שהפקודה gcloud מכירה את הפרויקט.
gcloud config list project
- אם הפרויקט לא מוגדר, משתמשים בפקודה הבאה כדי להגדיר אותו:
gcloud config set project <YOUR_PROJECT_ID>
- מוודאים שמותקנת גרסה 3.9 ואילך של Python
במסמכי העזרה מפורטות פקודות נוספות של gcloud ודרכים נוספות לשימוש בהן.
3. אב טיפוס
עוברים אל Google AI Studio. מתחילים להקליד את ההנחיה. זה ההנחיה שלי:
I want to renovate my kitchen, basically just remodel it. I don't know where to start. So I want to use Gemini to generate a plan. For that I need a good prompt. Give me a short yet detailed prompt that I can use.
משנים ומגדירים את הפרמטרים בצד שמאל כדי לקבל תגובה אופטימלית.
על סמך התיאור הפשוט הזה, Gemini יצר לי הנחיה מפורטת מאוד לתחילת השיפוץ! למעשה, אנחנו משתמשים ב-Gemini כדי לקבל תשובות טובות יותר מ-AI Studio ומהמודלים שלנו. אפשר גם לבחור מודלים שונים לשימוש, בהתאם לתרחיש לדוגמה.
בחרנו ב-Gemini 2.5 Pro. זהו מודל חשיבה, כלומר אנחנו מקבלים עוד יותר טוקני פלט, במקרה הזה עד 65,000 טוקנים, לניתוח ארוך ומסמכים מפורטים. תיבת החשיבה של Gemini מופיעה כשמפעילים את Gemini 2.5 Pro, שיש לו יכולות הסקת מסקנות מובנות והוא יכול לטפל בבקשות עם הקשר ארוך.
קטע הקוד של התשובה מופיע בהמשך:
AI Studio ניתח את הנתונים שלי וייצר את כל הדברים האלה, כמו ארונות, משטחי עבודה, חיפוי קיר, ריצוף, כיור, הרמוניה, לוח צבעים ובחירת חומרים. Gemini אפילו מפנה למקורות!
עכשיו ננסה להפוך את הרעיון למציאות באמצעות הנחיה אחרת.
- מעתיקים את ההנחיה הזו ומדביקים אותה בעורך ההנחיות:
Add flat and circular light accessories above the island area for my current kitchen in the attached image.
- מצרפים תמונה של המטבח הנוכחי (אפשר גם להשתמש בתמונה לדוגמה של מטבח).
- כדי שתהיה לכם גישה ליצירת תמונות, צריך לשנות את המודל ל-'יצירת תמונות של תצוגה מקדימה ב-Gemini 2.0 Flash'.
הפלט הזה הופיע:
זהו כוחם של Gemini!
יש דברים שאפשר ליצור רק באמצעות Gemini, החל מהבנה של סרטונים ועד ליצירת תמונות מקוריות ולשימוש במידע אמיתי בחיפוש Google.
מ-AI Studio אפשר לקחת את אב הטיפוס הזה, לקבל את מפתח ה-API ולהרחיב אותו לאפליקציה מלאה של סוכן באמצעות Vertex AI ADK.
4. הגדרת ADK
עכשיו נעבור לטרמינל של Cloud Shell שהפעלנו בקטע 'לפני שמתחילים':
- יצירה והפעלה של סביבה וירטואלית (מומלץ)
יוצרים סביבה וירטואלית בטרמינל של Cloud Shell:
python -m venv .venv
מפעילים את הסביבה הווירטואלית:
source .venv/bin/activate
- התקנת ADK
pip install google-adk
5. מבנה הפרויקט
- ב-Cloud Shell Terminal, יוצרים ספריית root לאפליקציות של הסוכנות במיקום הרצוי של הפרויקט:
mkdir agentic-apps
- בספרייה הראשית, יוצרים תיקייה אחת ספציפית לפרויקט הנוכחי:
mkdir renovation-agent
- עוברים לעורך של Cloud Shell ויוצרים את קבצי מבנה הפרויקט הבא (תחילה הם יהיו ריקים):
renovation-agent/
__init__.py
agent.py
requirements.txt
.env
6. קוד המקור
- עוברים לקובץ init.py ומעדכנים אותו עם התוכן הבא:
from . import agent
- עוברים לקובץ agent.py ומעדכנים אותו בתוכן הבא מהנתיב הבא:
https://github.com/AbiramiSukumaran/adk-renovation-single-agent/blob/main/agent.py
בקובץ agent.py אנחנו מייבאים את יחסי התלות הנדרשים, מאחזרים את פרמטרים ההגדרה מקובץ ה-env .ומגדירים את root_agent שיוצר מסמך הצעה ושומר אותו בקטגוריה של Cloud Storage. כדי לבצע את השלב של Cloud Storage, אנחנו משתמשים בכלי שנקרא store_pdf.
- מוודאים שיש לכם קטגוריה ב-Cloud Storage
זהו המיקום שבו יישמר מסמך ההצעה שהסוכן יוצר. יוצרים אותו ומקצים לו גישה כדי שהמערכת הסוכנית שנוצרת באמצעות Vertex AI תהיה מסוגלת לגשת אליו. כך עושים את זה:
https://cloud.google.com/storage/docs/creating-buckets#console
נותנים לקטגוריה את השם next-demo-store. אם נותנים לה שם אחר, חשוב לזכור לעדכן את הערך של STORAGE_BUCKET בקובץ .env (בשלב הגדרת משתני ENV).
- כדי להגדיר גישה לקטגוריה, נכנסים למסוף של Cloud Storage ולקטגוריית האחסון (במקרה שלנו שם הקטגוריה הוא next-demo-storage: https://console.cloud.google.com/storage/browser/next-demo-storage.
עוברים אל Permissions (הרשאות) -> View Principals (הצגת חשבונות משתמשים) -> Grant Access (מתן גישה). בוחרים באפשרות Principals כ-'allUsers' ובאפשרות Role כ-'Storage Object User'.
Make sure to not enable "prevent public access". Since this is a demo/study application we are going with a public bucket. Remember to configure permission settings appropriately when you are building your application.
- יצירת רשימת יחסי תלות
מציינים את כל יחסי התלות בקובץ requirements.txt. אפשר להעתיק את הקובץ הזה מ-repo.
הסבר על קוד המקור של מערכת סוכן יחיד
קובץ agent.py מגדיר את המבנה וההתנהגות של מערכת הסוכנויות שלנו לשיפוץ מטבחים באמצעות ערכת הפיתוח של סוכנים (ADK). נבחן את הרכיבים העיקריים:
הגדרת נציג
סוכן ברמה הבסיסית (כלי התזמור): proposal_agent
root_agent פועל בתור התזמור של המערכת הזו עם סוכן יחיד. הוא מקבל את בקשת השיפוץ הראשונית ומחליט אילו כלים להפעיל על סמך הצרכים של הבקשה.
לאחר מכן, root_agent אוסף את התשובות מהכלים ומחבר אותן כדי לספק תשובה מקיפה למשתמש. במקרה הזה יש לנו רק כלי אחד, 'store_pdf'.
7. תהליך העברת הנתונים ומושגים מרכזיים
המשתמש יוצר בקשה דרך ממשק ADK (המסוף או ממשק המשתמש באינטרנט).
- הבקשה מתקבלת על ידי root_agent.
- ה-root_agent מנתח את הבקשה ומנתב אותה לכלי לפי הצורך.
- הכלי store_pdf נועד לכתוב את תוכן הטקסט המשופץ בקובץ PDF, ולאחר מכן להעלות אותו ל-Google Cloud Storage.
- לאחר מכן, התגובה מוחזרת ל-root_agent.
- ה-root_agent משללב את התשובות ומספק פלט סופי למשתמש.
מודלים גדולים של שפה (LLMs)
הנציגים מסתמכים במידה רבה על מודלים גדולים של שפה (LLMs) כדי ליצור טקסט, לענות על שאלות ולבצע משימות של חשיבה. מודלים מסוג LLM הם 'המוח' שמאפשר לסוכנים להבין את בקשות המשתמשים ולהשיב להן. אנחנו משתמשים ב-Gemini 2.5 באפליקציה הזו.
Google Cloud Storage
משמש לאחסון המסמכים של הצעת השיפוץ שנוצרה. צריך ליצור קטגוריה ולהקצות את ההרשאות הנדרשות כדי שהסוכנים יוכלו לגשת אליה.
Cloud Run (אופציונלי)
ה-OrderingAgent משתמש בפונקציית Cloud Run כדי ליצור ממשק עם AlloyDB. Cloud Run מספק סביבה ללא שרת (serverless) להרצת קוד בתגובה לבקשות HTTP.
AlloyDB
אם אתם משתמשים ב-OrderingAgent, תצטרכו להגדיר מסד נתונים של AlloyDB כדי לאחסן את פרטי ההזמנות.
קובץ .env
קובץ ה-env .מאחסן מידע אישי רגיש כמו מפתחות API, פרטי כניסה למסד נתונים ושמות של קטגוריות. חשוב מאוד לשמור על אבטחת הקובץ הזה ולא להתחייב לו במאגר. הוא גם מאחסן את הגדרות התצורה של הסוכנים ושל הפרויקט ב-Google Cloud. בדרך כלל, root_agent או פונקציות תומכות יקראו ערכים מהקובץ הזה. מוודאים שכל המשתנים הנדרשים מוגדרים כראוי בקובץ .env. כולל את שם הקטגוריה ב-Cloud Storage
8. הגדרת מודל
היכולת של הנציג להבין בקשות של משתמשים וליצור תשובות מבוססת על מודל שפה גדול (LLM). הסוכן צריך לבצע שיחות מאובטחות לשירות ה-LLM החיצוני הזה, שדורש פרטי כניסה לאימות. ללא אימות תקין, שירות ה-LLM ידחה את הבקשות של הסוכן והסוכן לא יוכל לפעול.
- מקבלים מפתח API מ-Google AI Studio.
- בשלב הבא, שבו מגדירים את הקובץ .env, מחליפים את הערך
<<your API KEY>>בערך בפועל של מפתח ה-API.
9. הגדרת משתני ENV
- מגדירים את הערכים של הפרמטרים בקובץ .env של התבנית במאגר הזה. במקרה שלי, הקובץ .env מכיל את המשתנים הבאים:
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<<your API KEY>>
GOOGLE_CLOUD_LOCATION = us-central1 <<or your region>>
GOOGLE_CLOUD_PROJECT = <<your project id>>
PROJECT_ID = <<your project id>>
GOOGLE_CLOUD_REGION=us-central1 <<or your region>>
STORAGE_BUCKET = next-demo-store <<or your storage bucket name>>
מחליפים את ה-placeholders בערכים שלכם.
10. הפעלת הסוכן
- עוברים לספריית ההורה של פרויקט הנציג באמצעות הטרמינל:
cd agentic-apps/renovation-agent
- התקנה של כל יחסי התלות
pip install -r requirements.txt
- כדי להפעיל את הסוכן, אפשר להריץ את הפקודה הבאה במסוף של Cloud Shell:
adk run .
- כדי להריץ אותו בממשק משתמש אינטרנטי שהוקצה על ידי ADK, אפשר להריץ את הפקודה הבאה:
adk web
- אפשר לבדוק את ההנחיות הבאות:
user>>
Hello. Generate Proposal Document for the kitchen remodel requirement in a proper format that applies to a renovation contract. Remember this text will eventually be stored as a pdf file so make sure to have the formatting appropriate. I have no other specification.
11. תוצאה
בפקודה adk run . התוצאה היא:"
...
אפשר לוודא שהמסמך Renovation Proposal נוצר בקטגוריה של Cloud Storage.
12. הסרת המשאבים
כדי להימנע מחיובים בחשבון Google Cloud בגלל השימוש במשאבים שנעשה במסגרת הפוסט הזה, יש לפעול לפי השלבים הבאים:
- נכנסים לדף Manage resources במסוף Google Cloud.
- ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
- כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.
13. מזל טוב
מעולה! סיימתם ליצור את האפליקציה עם כמה סוכנים ולנהל איתה אינטראקציה באמצעות ADK. המערכת עם סוכנים מרובים נועדה לייעל את תהליך שיפוץ המטבח על ידי אוטומציה של משימות כמו יצירת הצעות, בדיקת היתרים ומעקב אחר סטטוס ההזמנה. לכל סוכן יש תפקיד ספציפי, ו-root_agent כוונן את הפעילויות שלהם כדי לספק פתרון מקיף. כדי לספק את הפונקציונליות שלה, המערכת משתמשת ב-LLM, בשירותי Google Cloud ובממשקי API חיצוניים. כאן יש קישור למסמכי העזרה של המוצר.