אפליקציה עם סוכנים מרובים באמצעות ADK, ‏ Agent Engine ו-AlloyDB

1. סקירה כללית

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

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

ערכת פיתוח סוכנים (ADK)

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

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

דברים שכדאי לזכור לגבי מערכת מרובת סוכנים

קודם, חשוב להבין את ההתמחות של כל סוכן ולנמק אותה. – "do you know why you need a specific sub-agent for something", work that out first.

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

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

מה תפַתחו

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

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

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

סוכן ההיתרים והתאימות, לטיפול במשימות שקשורות להיתרים ולתאימות.

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

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

דרישות

דפדפן, כמו Chrome או Firefox
פרויקט ב-Google Cloud שהחיוב בו מופעל.

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

יצירת פרויקט

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

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

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

gcloud auth list

מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שפקודת gcloud מכירה את הפרויקט.

gcloud config list project

אם הפרויקט לא מוגדר, משתמשים בפקודה הבאה כדי להגדיר אותו:

gcloud config set project <YOUR_PROJECT_ID>

מוודאים שמותקנת גרסה Python 3.9 ומעלה
מפעילים את ממשקי ה-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 Preview Image Generation.

קיבלתי את הפלט הזה:

זו העוצמה של Gemini!

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

מ-AI Studio, אפשר לקחת את אב הטיפוס הזה, להשיג את מפתח ה-API ולהרחיב אותו לאפליקציה מלאה שמבוססת על סוכנים באמצעות היכולות של Vertex AI ADK.

4. הגדרת ADK

יצירה והפעלה של סביבה וירטואלית (מומלץ)

בטרמינל של Cloud Shell, יוצרים סביבה וירטואלית:

python -m venv .venv

מפעילים את הסביבה הווירטואלית:

source .venv/bin/activate

התקנת ADK

pip install google-adk

5. מבנה הפרויקט

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

מוודאים שיש לכם קטגוריה של Cloud Storage

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

https://cloud.google.com/storage/docs/creating-buckets#console

נותנים שם למאגר next-demo-store. אם נותנים לו שם אחר, צריך לעדכן את הערך של STORAGE_BUCKET בקובץ ‎ .env (בשלב הגדרת משתני הסביבה).

כדי להגדיר גישה לקטגוריה, עוברים אל מסוף Cloud Storage ואל קטגוריית האחסון (במקרה שלנו, שם הקטגוריה הוא next-demo-storage): https://console.cloud.google.com/storage/browser/next-demo-storage.

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

הסבר על קוד המקור של מערכת מרובת סוכנים

קובץ agent.py מגדיר את המבנה וההתנהגות של מערכת מרובת סוכנים לשיפוץ מטבח באמצעות Agent Development Kit‏ (ADK). נפרט את הרכיבים העיקריים:

הגדרות הסוכן

RenovationProposalAgent

הסוכן הזה אחראי ליצירת מסמך הצעת המחיר לשיפוץ המטבח. אפשר גם להזין פרמטרים כמו גודל המטבח, הסגנון הרצוי, התקציב והעדפות הלקוח. על סמך המידע הזה, הוא משתמש במודל שפה גדול (LLM) Gemini 2.5 כדי ליצור הצעה מפורטת. ההצעה שנוצרה מאוחסנת בקטגוריה של Google Cloud Storage.

PermitsAndComplianceCheckAgent

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

OrderingAgent

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

סוכן הבסיס (כלי התזמור)

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

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

זרימת נתונים ומושגי מפתח

המשתמש יוזם בקשה דרך הממשק של ADK (טרמינל או ממשק משתמש באינטרנט).

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

מודלים גדולים של שפה (LLM)

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

Google Cloud Storage

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

Cloud Run (אופציונלי)

הסוכן OrderingAgent משתמש בפונקציית Cloud Run כדי ליצור אינטראקציה עם AlloyDB. ‫Cloud Run מספק סביבה ללא שרתים להרצת קוד בתגובה לבקשות HTTP.

AlloyDB

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

קובץ ‎.env

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

7. הגדרת מסד נתונים

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

יצירת אשכול ומופע

עוברים לדף AlloyDB במסוף Cloud. דרך קלה למצוא את רוב הדפים ב-Cloud Console היא לחפש אותם באמצעות סרגל החיפוש של המסוף.
בדף הזה, לוחצים על יצירת אשכול:

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

cluster id: "vector-cluster"
password: "alloydb"
‫PostgreSQL 15 / הגרסה המומלצת האחרונה
אזור: "us-central1"
רשת: "default"

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

לוחצים על הגדרת חיבור.

משם, בוחרים באפשרות שימוש בטווח כתובות IP שהוקצה באופן אוטומטי ולוחצים על 'המשך'. אחרי שבודקים את המידע, לוחצים על CREATE CONNECTION (יצירת חיבור).
אחרי שמגדירים את הרשת, אפשר להמשיך ליצור את האשכול. לוחצים על CREATE CLUSTER (יצירת אשכול) כדי להשלים את הגדרת האשכול, כמו שמוצג בהמשך:

חשוב לשנות את מזהה המופע (שאפשר למצוא בזמן ההגדרה של האשכול או המופע) ל

‫vector-instance. אם אי אפשר לשנות אותו, חשוב להשתמש במזהה המכונה בכל ההפניות הבאות.

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

הטמעת נתונים

עכשיו צריך להוסיף טבלה עם הנתונים על החנות. עוברים אל AlloyDB, בוחרים את האשכול הראשי ואז את AlloyDB Studio:

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

שם משתמש : "postgres"
מסד נתונים : "postgres"
סיסמה : "alloydb"

אחרי שתעברו בהצלחה את תהליך האימות ב-AlloyDB Studio, תוכלו להזין פקודות SQL בכלי העריכה. אפשר להוסיף כמה חלונות של Editor באמצעות סימן הפלוס שמימין לחלון האחרון.

מזינים פקודות ל-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.

עכשיו שמערך הנתונים מוכן, ניצור אפליקציית Java Cloud Run Functions כדי לחלץ את הסטטוס.

יצירת פונקציית Cloud Run ב-Java כדי לחלץ מידע על סטטוס ההזמנה

כדי ליצור פונקציית Cloud Run, אפשר להיכנס לכתובת https://console.cloud.google.com/run/create?deploymentType=function
מגדירים את שם הפונקציה ל-check-status ובוחרים באפשרות Java 17 כזמן ריצה.
אפשר להגדיר את האימות להפעלת קריאות ללא אימות כי מדובר באפליקציית הדגמה.
בוחרים באפשרות Java 17 כסביבת זמן ריצה ובאפשרות Inline Editor (עורך מוטבע) לקוד המקור.
בשלב הזה, קוד ה-placeholder ייטען בעורך.

החלפת קוד הפלייסהולדר

משנים את השם של קובץ ה-Java ל-ProposalOrdersTool.java ואת שם המחלקה ל-ProposalOrdersTool.
מחליפים את קוד ה-placeholder בקבצים ProposalOrdersTool.java ו-pom.xml בקוד מהקבצים המתאימים בתיקייה פונקציית Cloud Run במאגר הזה.
ב-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. מחפשים את פונקציית Cloud Run החדשה שנוצרה (check-status), לוחצים עליה ואז לוחצים על עריכה ופריסה של גרסאות חדשות (מזוהה על ידי סמל העריכה (עיפרון) בחלק העליון של מסוף Cloud Run Functions) ומשנים את הפרטים הבאים:

עוברים לכרטיסייה 'רשת':

בוחרים באפשרות Connect to a VPC for outbound traffic (חיבור לרשת (VPC) לתנועה יוצאת) ואז באפשרות Use Serverless VPC Access connectors (שימוש במחברי חיבור לרשת (VPC) מאפליקציית serverless)
בתפריט הנפתח 'רשת', לוחצים על האפשרות הוספת מחבר VPC חדש (אם עדיין לא הגדרתם את ברירת המחדל) ופועלים לפי ההוראות שמופיעות בתיבת הדו-שיח שקופצת:

נותנים שם למחבר ה-VPC ומוודאים שהאזור זהה לאזור של המכונה. משאירים את ערך הרשת כברירת מחדל ומגדירים את רשת המשנה כטווח IP מותאם אישית עם טווח ה-IP‏ 10.8.0.0 או ערך דומה אחר שזמין.
מרחיבים את האפשרות SHOW SCALING SETTINGS (הצגת הגדרות שינוי הגודל) ומוודאים שההגדרה מוגדרת בדיוק כמו שמופיע כאן:

לוחצים על יצירה. המחבר הזה אמור להופיע עכשיו בהגדרות היציאה.
בוחרים את המחבר החדש שנוצר.
בוחרים שכל התנועה תנותב דרך מחבר ה-VPC הזה.
לוחצים על הבא ואז על פריסה.
אחרי שפורסים את הפונקציה המעודכנת ב-Cloud Functions, אמורה להופיע נקודת הקצה שנוצרה.
כדי לבדוק את הפונקציה, לוחצים על הלחצן TEST (בדיקה) בחלק העליון של מסוף פונקציות Cloud Run ומריצים את הפקודה שמתקבלת במסוף Cloud Shell.
נקודת הקצה שנפרסה היא כתובת ה-URL שצריך לעדכן במשתנה CHECK_ORDER_STATUS_ENDPOINT בקובץ ‎ .env.

8. הגדרת המודל

היכולת של הסוכן להבין בקשות של משתמשים וליצור תשובות מבוססת על מודל שפה גדול (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.

11. תוצאה

‫@ Multi-agent system for Kitchen Renovation tasks

12. פריסה ל-Agent Engine

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

במסוף Google Cloud, עוברים לדף Manage resources.
ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

15. מזל טוב

מעולה! יצרתם אינטראקציה עם הנציג הראשון שלכם באמצעות ADK!