מידע על Codelab זה
1. סקירה כללית
סוכן הוא תוכנית אוטונומית שמדברת עם מודל AI כדי לבצע פעולה מבוססת-יעד באמצעות הכלים וההקשר שיש לה, והיא מסוגלת לקבל החלטות אוטונומיות שמבוססות על אמת.
כשיש באפליקציה כמה סוכנים שפועלים יחד באופן אוטונומי ועם זאת יחד כנדרש כדי לעמוד במטרה הרחבה יותר שלה, כאשר כל אחד מהסוכנים יודע ומומחה בתחום ספציפי, האפליקציה הופכת למערכת עם סוכנים מרובים.
ערכת הפיתוח של סוכן (ADK)
ערכת פיתוח סוכנים (ADK) היא מסגרת גמישה ומודולרית לפיתוח ופריסה של סוכני AI. ADK תומך ביצירת אפליקציות מתוחכמות על ידי שילוב של כמה מכונות סוכנים נפרדות למערכת של סוכנים מרובים (MAS).
ב-ADK, מערכת עם סוכנים מרובים היא אפליקציה שבה סוכנים שונים, שפעמים רבות יוצרים היררכיה, משתפים פעולה או מתואמים כדי להשיג מטרה גדולה יותר. למבנה כזה של האפליקציה יש יתרונות משמעותיים, כולל מודולריות משופרת, התמחות, שימוש חוזר, יכולת תחזוקה ויכולת להגדיר תהליכי בקרה מובְנים באמצעות סוכני תהליכי עבודה ייעודיים.
דברים שכדאי לזכור לגבי מערכת עם כמה סוכנים
קודם, חשוב להבין את ההתמחות של כל סוכן ולדעת למה היא מתאימה לו. — "האם ברור לך למה דרושה לך סוכנות משנה ספציפית למשהו", קודם צריך להבין את זה.
השלב השני: איך משלבים אותם עם סוכן ברמה הבסיסית כדי לנתב ולנתח כל אחת מהתשובות.
שלישי, יש כמה סוגים של ניתוב סוכנים שמפורטים במסמכי התיעוד האלה. חשוב לבדוק איזו מהן מתאימה לתהליך של האפליקציה. בנוסף, מהם ההקשרים והמצבים השונים שנדרשים לבקרת התהליך במערכת עם כמה סוכנים.
מה תפַתחו
נלמד איך ליצור מערכת עם כמה סוכנים לטיפול בשיפוצים של מטבחים. זה מה שנעשה. נבנה מערכת עם 3 סוכני תמיכה.
- סוכן של הצעת שיפוץ
- סוכן לבדיקת רישיונות ותאימות
- סוכנות לבדיקת סטטוס ההזמנה
סוכן של הצעת שיפוץ, כדי ליצור את מסמך הצעת השיפוץ של המטבח.
סוכן רישיונות ותאימות, לטיפול ברישיונות ובמשימות שקשורות לתאימות.
Order Status Check Agent, כדי לבדוק את סטטוס ההזמנה של חומרי הגלם באמצעות מסד הנתונים לניהול ההזמנות שהגדרתנו ב-AlloyDB.
יהיה לנו סוכן ברמה הבסיסית (root) שינהל את הסוכנים האלה על סמך הדרישה.
דרישות
2. לפני שמתחילים
יצירת פרויקט
- בדף לבחירת הפרויקט במסוף Google Cloud, בוחרים פרויקט ב-Google Cloud או יוצרים פרויקט חדש.
- הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט
אם אתם קוראים את המאמר הזה ואתם רוצים לקבל זיכויים שיעזרו לכם להתחיל להשתמש ב-Google Cloud וב-ADK, תוכלו לממש את הזיכויים דרך הקישור הזה. כדי לממש את השובר, אפשר לפעול לפי ההוראות כאן. לתשומת ליבך, הקישור הזה תקף רק עד סוף מאי.
- לוחצים על הקישור הזה כדי להפעיל את Cloud Shell. כדי לעבור בין Cloud Shell Terminal (להרצת פקודות ב-Cloud) לבין Cloud Shell 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
- מריצים את הפקודות הבאות כדי להפעיל את ממשקי ה-API הבאים:
gcloud services enable artifactregistry.googleapis.com \cloudbuild.googleapis.com \run.googleapis.com \aiplatform.googleapis.com
- במסמכי העזרה מפורטות הפקודות של gcloud והשימוש בהן.
3. אב טיפוס
אם בחרתם להשתמש במודל 'Gemini 2.5 Pro' לפרויקט, אתם יכולים לדלג על השלב הזה.
עוברים אל 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 אפילו מפנה למקורות!
חוזרים על התהליך עם מודלים שונים עד שמגיעים לתוצאה הרצויה. אבל למה לעבור את כל התהליך הזה כשיש לך את Gemini 2.5? :)
בכל מקרה, עכשיו ננסה להפוך את הרעיון למציאות באמצעות הנחיה אחרת:
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:
python -m venv .venv
מפעילים את הסביבה הווירטואלית:
source .venv/bin/activate
- התקנת ADK
pip install google-adk
5. מבנה הפרויקט
- ב-Terminal של Cloud Shell, יוצרים ספרייה במיקום הרצוי של הפרויקט.
mkdir agentic-apps
cd agentic-apps
mkdir renovation-agent
- עוברים לעורך של Cloud Shell ויוצרים את קבצי מבנה הפרויקט הבא (תחילה הם יהיו ריקים):
renovation-agent/
__init__.py
agent.py
.env
requirements.txt
6. קוד המקור
- עוברים לקובץ init.py ומעדכנים אותו בתוכן הבא:
from . import agent
- עוברים לקובץ agent.py ומעדכנים אותו בתוכן הבא מהנתיב הבא:
https://github.com/AbiramiSukumaran/adk-renovation-agent/blob/main/agent.py
בקובץ agent.py אנחנו מייבאים את יחסי התלות הנדרשים, מאחזרים את פרמטרים ההגדרה מקובץ .env ומגדירים את root_agent שמארגן את 3 סוכני המשנה שרצינו ליצור באפליקציה הזו. יש כמה כלים שיעזרו לכם לבצע את הפונקציות המרכזיות והתומכות של סוכני המשנה האלה.
- מוודאים שיש לכם קטגוריה ב-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). נבחן את הרכיבים העיקריים:
הגדרות של סוכנויות
RenovationProposalAgent
הסוכן הזה אחראי ליצירת המסמך של הצעת השיפוץ למטבח. אפשר להזין פרמטרים של קלט כמו גודל המטבח, הסגנון הרצוי, התקציב וההעדפות של הלקוח. על סמך המידע הזה, המערכת משתמשת במודל שפה גדול (LLM) מסוג Gemini 2.5 כדי ליצור הצעה מפורטת. לאחר מכן, ההצעה שנוצרה מאוחסנת בקטגוריה של Google Cloud Storage.
PermitsAndComplianceCheckAgent
התפקיד של הגורם הזה הוא לוודא שפרויקט השיפוץ עומד בתקנות ובקודים המקומיים לבנייה. המערכת מקבלת מידע על השיפוץ המוצע (למשל, שינויים מבניים, עבודות חשמל, שינויים בצנרת) ומשתמשת ב-LLM כדי לבדוק את דרישות ההיתר וכללי התאימות. הסוכן משתמש במידע ממאגר ידע (שאפשר להתאים אישית כדי לגשת לממשקי API חיצוניים ולקבל מידע על תקנות רלוונטיות).
OrderingAgent
הסוכן הזה (אפשר להסיר את ההערה שלו אם לא רוצים להטמיע אותו עכשיו) מטפל בבדיקת סטטוס ההזמנה של החומרים והציוד הנדרשים לשיפוץ. כדי להפעיל אותה, צריך ליצור פונקציית Cloud Run כפי שמתואר בשלבים להגדרה. לאחר מכן, הסוכן יפעיל את פונקציית Cloud Run הזו, שמקיימת אינטראקציה עם מסד נתונים של AlloyDB שמכיל את פרטי ההזמנה. הדגמה של שילוב עם מערכת מסד נתונים למעקב אחרי נתונים בזמן אמת.
סוכן Root (כלי תזמור)
root_agent משמש בתור התזמור המרכזי של המערכת עם סוכנים מרובים. הוא מקבל את בקשת השיפוץ הראשונית ומחליט אילו סוכני משנה להפעיל על סמך הצרכים של הבקשה. לדוגמה, אם הבקשה מחייבת בדיקת דרישות לקבלת רישיון, תתבצע קריאה ל-PermitsAndComplianceCheckAgent. אם המשתמש רוצה לבדוק את סטטוס ההזמנה, הוא יפעיל את OrderingAgent (אם הוא מופעל).
לאחר מכן, root_agent אוסף את התגובות מהסוכנים המשניים ומשלב אותן כדי לספק תשובה מקיפה למשתמש. יכול להיות שזה יכלול סיכום של ההצעה, פירוט ההיתרים הנדרשים ועדכונים לגבי סטטוס ההזמנה.
תהליך העברת הנתונים ומושגים מרכזיים
המשתמש יוצר בקשה דרך ממשק ADK (המסוף או ממשק המשתמש באינטרנט).
- הבקשה מתקבלת על ידי root_agent.
- ה-root_agent מנתח את הבקשה ומנתב אותה לסוכני המשנה המתאימים.
- סוכני המשנה משתמשים ב-LLM, בבסיסות ידע, בממשקי API ובמסדי נתונים כדי לעבד את הבקשה וליצור תשובות.
- סוכני המשנה מחזירים את התשובות שלהם ל-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
7. הגדרת מסד נתונים
באחד הכלים שבהם ה-ordering_agent משתמש, שנקרא check_status, אנחנו ניגשים למסד הנתונים של ההזמנות ב-AlloyDB כדי לקבל את סטטוס ההזמנות. בקטע הזה נגדיר את האשכולות והמכונות של מסדי הנתונים של AlloyDB.
יצירת אשכול ומכונה
- נכנסים לדף AlloyDB במסוף Cloud. דרך קלה למצוא את רוב הדפים במסוף Cloud היא לחפש אותם באמצעות סרגל החיפוש במסוף.
- בוחרים באפשרות CREATE CLUSTER (יצירת אשכול) בדף הזה:
- יוצג מסך כמו זה שבהמשך. יוצרים אשכול ומכונה עם הערכים הבאים (חשוב לוודא שהערכים תואמים במקרה שמשכפלים את קוד האפליקציה מהמאגר):
- cluster id: "
vector-cluster" - password: "
alloydb" - PostgreSQL 15 / הגרסה האחרונה המומלצת
- אזור: "
us-central1" - Networking: "
default"
- כשבוחרים את רשת ברירת המחדל, מופיע מסך כמו זה שבהמשך.
בוחרים באפשרות הגדרת חיבור.
- לאחר מכן, בוחרים באפשרות Use an automatically allocated IP range (שימוש בטווח כתובות IP שהוקצה באופן אוטומטי) וממשיכים. אחרי שבודקים את המידע, בוחרים באפשרות 'יצירת חיבור'.
- אחרי שמגדירים את הרשת, אפשר להמשיך ליצור את האשכולות. לוחצים על CREATE CLUSTER (יצירת אשכול) כדי להשלים את הגדרת האשכול, כפי שמתואר בהמשך:
חשוב לשנות את מזהה המכונה (שאפשר למצוא בזמן ההגדרה של האשכולות או המכונות) ל
vector-instance. אם אין לכם אפשרות לשנות אותו, חשוב לזכור להשתמש במזהה המכונה בכל ההפניות הבאות.
לתשומת ליבכם: יצירת האשכולות תימשך כ-10 דקות. לאחר השלמת הפעולה, אמור להופיע מסך עם סקירה כללית של האשכולות שיצרתם.
הטמעת נתונים
עכשיו הגיע הזמן להוסיף טבלה עם הנתונים על החנות. עוברים אל AlloyDB, בוחרים את האשכול הראשי ואז את AlloyDB Studio:
יכול להיות שתצטרכו להמתין עד לסיום יצירת המכונה. לאחר מכן, נכנסים ל-AlloyDB באמצעות פרטי הכניסה שיצרתם כשיצרתם את האשכולות. משתמשים בנתונים הבאים כדי לבצע אימות ב-PostgreSQL:
- שם משתמש : "
postgres" - מסד נתונים : '
postgres' - סיסמה : "
alloydb"
אחרי שתבצעו אימות ב-AlloyDB Studio, תוכלו להזין פקודות SQL בעורך. אפשר להוסיף כמה חלונות של הכלי באמצעות סמל הפלוס שמשמאל לחלון האחרון.
מזינים פקודות ל-AlloyDB בחלונות העריכה, באמצעות האפשרויות Run (הפעלה), Format (פורמט) ו-Clear (מחיקה) לפי הצורך.
צור טבלה
אפשר ליצור טבלה באמצעות משפט ה-DDL הבא ב-AlloyDB Studio:
-- Table DDL for Procurement Material Order Status
CREATE TABLE material_order_status (
order_id VARCHAR(50) PRIMARY KEY,
material_name VARCHAR(100) NOT NULL,
supplier_name VARCHAR(100) NOT NULL,
order_date DATE NOT NULL,
estimated_delivery_date DATE,
actual_delivery_date DATE,
quantity_ordered INT NOT NULL,
quantity_received INT,
unit_price DECIMAL(10, 2) NOT NULL,
total_amount DECIMAL(12, 2),
order_status VARCHAR(50) NOT NULL, -- e.g., "Ordered", "Shipped", "Delivered", "Cancelled"
delivery_address VARCHAR(255),
contact_person VARCHAR(100),
contact_phone VARCHAR(20),
tracking_number VARCHAR(100),
notes TEXT,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
quality_check_passed BOOLEAN, -- Indicates if the material passed quality control
quality_check_notes TEXT, -- Notes from the quality control check
priority VARCHAR(20), -- e.g., "High", "Medium", "Low"
project_id VARCHAR(50), -- Link to a specific project
receiver_name VARCHAR(100), -- Name of the person who received the delivery
return_reason TEXT, -- Reason for returning material if applicable
po_number VARCHAR(50) -- Purchase order number
);
הוספת רשומות
מעתיקים את ביטוי השאילתה insert מהסקריפט database_script.sql שצוין למעלה לעורך.
לוחצים על Run.
עכשיו, כשמערך הנתונים מוכן, נוצר אפליקציה של Cloud Run Functions ב-Java כדי לחלץ את הסטטוס.
יצירת פונקציית Cloud Run ב-Java כדי לחלץ מידע על סטטוס ההזמנה
- יצירת פונקציית Cloud Run כאן: https://console.cloud.google.com/run/create?deploymentType=function
- מגדירים את שם הפונקציה כ-check-status ובוחרים ב-Java 17 כסביבת זמן ריצה.
- אפשר להגדיר את האימות לאפשרות Allow unauthenticated invocations (הרשאה להפעלות לא מאומתות) כי מדובר באפליקציית הדגמה.
- בוחרים ב-Java 17 כסביבת זמן ריצה וב-Inline Editor לקוד המקור.
- בשלב הזה, קוד placeholder ייטען בעורך.
החלפת קוד הפלייסהולדר
- משנים את שם קובץ ה-Java ל-ProposalOrdersTool.java ואת שם הכיתה ל-ProposalOrdersTool.
- מחליפים את קוד ה-placeholder בקובצי ProposalOrdersTool.java ו-pom.xml בקוד מהקבצים המתאימים בתיקייה 'פונקציית Cloud Run' ב-repo הזה.
- בקובץ ProposalOrdersTool.java, מחפשים את שורת הקוד הבאה ומחליפים את הערכים הזמניים לשמירת מקום (placeholder) בערכים מההגדרות שלכם:
String ALLOYDB_INSTANCE_NAME = "projects/<<YOUR_PROJECT_ID>>/locations/us-central1/clusters/<<YOUR_CLUSTER>>/instances/<<YOUR_INSTANCE>>";
- לוחצים על 'יצירה'.
- פונקציית Cloud Run תיווצר ותופרס.
שלב חשוב:
לאחר הפריסה, כדי לאפשר ל-Cloud Function לגשת למכונה של מסד הנתונים AlloyDB, נוצר את מחבר ה-VPC.
אחרי שתסיימו את ההכנות לפריסה, הפונקציות אמורות להופיע במסוף Google Cloud Run Functions. מחפשים את הפונקציה שנוצרה (check-status), לוחצים עליה ואז על EDIT AND DEPLOY NEW REVISIONS (הסמל של EDIT (עיפרון) בחלק העליון של מסוף Cloud Run Functions) ומשנים את הפרטים הבאים:
- עוברים לכרטיסייה Networking (רשתות):
- בוחרים באפשרות Connect to a VPC for outbound traffic (התחברות ל-VPC לתנועה יוצאת) ואז באפשרות Use Serverless VPC Access connectors (שימוש במחברים של חיבור לרשת (VPC) מאפליקציית serverless).
- בתפריט הנפתח Network, לוחצים על התפריט הנפתח Network ובוחרים באפשרות Add New VPC Connector (אם עדיין לא הגדרתם את האפשרות default) ופועלים לפי ההוראות שמופיעות בתיבת הדו-שיח הקופצת:
- נותנים שם למחבר VPC ומוודאים שהאזור זהה לאזור של המכונה. משאירים את הערך של Network כברירת מחדל ומגדירים את Subnet כ-Custom IP Range עם טווח כתובות ה-IP 10.8.0.0 או משהו דומה שזמין.
- מרחיבים את האפשרות SHOW SCALING SETTINGS (הצגת הגדרות התאמה לעומס) ומוודאים שההגדרות מוגדרות בדיוק כך:
- לוחצים על CREATE (יצירה) והמחבר הזה אמור להופיע עכשיו בהגדרות תעבורת הנתונים היוצאת.
- בוחרים את המחבר החדש שנוצר.
- בוחרים שכל התנועה תנותב דרך המחבר הזה של VPC.
- לוחצים על NEXT ואז על DEPLOY.
- אחרי הפריסה של פונקציית Cloud Functions המעודכנת, נקודת הקצה שנוצרה אמורה להופיע.
- כדי לבדוק את הפונקציה, לוחצים על הלחצן TEST בחלק העליון של מסוף Cloud Run Functions ומריצים את הפקודה שנוצרת במסוף Cloud Shell.
- נקודת הקצה שנפרסה היא כתובת ה-URL שצריך לעדכן במשתנה
CHECK_ORDER_STATUS_ENDPOINT .env.
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>>
CHECK_ORDER_STATUS_ENDPOINT=<<YOUR_ENDPOINT_TO_CLOUD FUNCTION_TO_READ_ORDER_DATA_FROM_ALLOYDB>>
מחליפים את ה-placeholders בערכים שלכם.
10. הפעלת הסוכן
- עוברים לספריית ההורה של פרויקט הנציג באמצעות הטרמינל:
cd renovation-agent
- התקנה של כל יחסי התלות
pip install -r requirements.txt
- כדי להפעיל את הסוכן, אפשר להריץ את הפקודה הבאה במסוף של Cloud Shell:
adk run .
- כדי להריץ אותו בממשק משתמש אינטרנטי שהוקצה על ידי ADK, אפשר להריץ את הפקודה הבאה:
adk web
- אפשר לבדוק את ההנחיות הבאות:
user>>
Hello. Generate Proposal Document for the kitchen remodel requirement. I have no other specification.
12. פריסה ב-Agent Engine
עכשיו, אחרי שבדקתם שהמערכת עם כמה סוכני ה-API פועלת כמו שצריך, נהפוך אותה ללא שרתים ונשאיר אותה זמינה בענן כדי שכל אחד או כל אפליקציה יוכלו להשתמש בה. מסירים את ההערה מקטע הקוד הבא בקובץ agent.py מהמאגר, ומוכנים לפרוס את המערכת עם כמה סוכנים:
# Agent Engine Deployment:
# Create a remote app for our multiagent with agent Engine.
# This may take 1-2 minutes to finish.
# Uncomment the below segment when you're ready to deploy.
app = AdkApp(
agent=root_agent,
enable_tracing=True,
)
vertexai.init(
project=PROJECT_ID,
location=GOOGLE_CLOUD_LOCATION,
staging_bucket=STAGING_BUCKET,
)
remote_app = agent_engines.create(
app,
requirements=[
"google-cloud-aiplatform[agent_engines,adk]>=1.88",
"google-adk",
"pysqlite3-binary",
"toolbox-langchain==0.1.0",
"pdfplumber",
"google-cloud-aiplatform",
"cloudpickle==3.1.1",
"pydantic==2.10.6",
"pytest",
"overrides",
"scikit-learn",
"reportlab",
"google-auth",
"google-cloud-storage",
],
)
# Deployment to Agent Engine related code ends
מריצים שוב את agent.py בתיקיית הפרויקט באמצעות הפקודה הבאה:
>> cd adk-renovation-agent
>> python agent.py
השלמת הקוד תימשך כמה דקות. בסיום התהליך, תקבלו נקודת קצה שנראית כך:
'projects/123456789/locations/us-central1/reasoningEngines/123456'
אפשר לבדוק את הסוכן שנפרס באמצעות הקוד הבא, על ידי הוספת קובץ חדש בשם test.py.
import vertexai
from vertexai.preview import reasoning_engines
from vertexai import agent_engines
import os
import warnings
from dotenv import load_dotenv
load_dotenv()
GOOGLE_CLOUD_PROJECT = os.environ["GOOGLE_CLOUD_PROJECT"]
GOOGLE_CLOUD_LOCATION = os.environ["GOOGLE_CLOUD_LOCATION"]
GOOGLE_API_KEY = os.environ["GOOGLE_API_KEY"]
GOOGLE_GENAI_USE_VERTEXAI=os.environ["GOOGLE_GENAI_USE_VERTEXAI"]
AGENT_NAME = "adk_renovation_agent"
MODEL_NAME = "gemini-2.5-pro-preview-03-25"
warnings.filterwarnings("ignore")
PROJECT_ID = GOOGLE_CLOUD_PROJECT
reasoning_engine_id = "<<YOUR_DEPLOYED_ENGINE_ID>>"
vertexai.init(project=PROJECT_ID, location="us-central1")
agent = agent_engines.get(reasoning_engine_id)
print("**********************")
print(agent)
print("**********************")
for event in agent.stream_query(
user_id="test_user",
message="I want you to check order status.",
):
print(event)
בקוד שלמעלה, מחליפים את הערך של placeholder '<<YOUR_DEPLOYED_ENGINE_ID>>' ומריצים את הפקודה 'python test.py'. עכשיו אפשר להריץ את הפקודה הזו כדי לקיים אינטראקציה עם מערכת של סוכנים מרובים שמופעלת על ידי Agent Engine, ולהתחיל לשפץ את המטבח!!!
13. אפשרויות פריסה בשורה אחת
עכשיו, אחרי שבדקתם את המערכת עם כמה סוכנים שפרסמתם, נלמד שיטות פשוטות יותר שמפשטות את שלב הפריסה שביצענו בשלב הקודם: אפשרויות פריסה בשורה אחת:
- ב-Cloud Run:
תחביר:
adk deploy cloud_run \
--project=<<YOUR_PROJECT_ID>> \
--region=us-central1 \
--service_name=<<YOUR_SERVICE_NAME>> \
--app_name=<<YOUR_APP_NAME>> \
--with_ui \
./<<YOUR_AGENT_PROJECT_NAME>>
במקרה זה:
adk deploy cloud_run \
--project=<<YOUR_PROJECT_ID>> \
--region=us-central1 \
--service_name=renovation-agent \
--app_name=renovation-app \
--with_ui \
./renovation-agent
אפשר להשתמש בנקודת הקצה שנפרסה בשילובים במורד הזרם.
- ל-Agent Engine:
תחביר:
adk deploy agent_engine \
--project <your-project-id> \
--region us-central1 \
--staging_bucket gs://<your-google-cloud-storage-bucket> \
--trace_to_cloud \
path/to/agent/folder
במקרה זה:
adk deploy agent_engine --project <<YOUR_PROJECT_ID>> --region us-central1 --staging_bucket gs://<<YOUR_BUCKET_NAME>> --trace_to_cloud renovation-agent
סוכן חדש אמור להופיע בממשק המשתמש של Agent Engine במסוף Google Cloud. פרטים נוספים זמינים בפוסט הזה בבלוג.
14. הסרת המשאבים
כדי להימנע מחיובים בחשבון Google Cloud בגלל השימוש במשאבים שנעשה במסגרת הפוסט הזה, יש לפעול לפי השלבים הבאים:
- נכנסים לדף Manage resources במסוף Google Cloud.
- ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
- כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.
15. מזל טוב
מעולה! יצרתם את הנציג הראשון באמצעות ADK והייתם איתו באינטראקציה.