פיתוח ופריסה של סוכן AI ב-Cloud Run באמצעות ערכת פיתוח סוכנים (ADK)

המסגרת Agent Development Kit (ADK) מפשטת את היצירה, ההערכה והפריסה של סוכני AI. ערכת ה-ADK מספקת גישה מודולרית שמתמקדת בקוד ליצירת סוכנים שיכולים להסיק מסקנות, לתכנן ולהשתמש בכלים.

במדריך הזה נסביר איך ליצור ולפרוס סוכן AI ב-Cloud Run באמצעות ADK for Python. הסוכן הזה מאחזר את דוח מזג האוויר של העיר שציינתם.

מידע נוסף על אירוח סוכן ADK באמצעות Google Cloud CLI זמין במאמר פריסה ב-Cloud Run במסמכי ADK.

מטרות

• כותבים את האפליקציה לדוגמה כדי להגדיר את סוכן מזג האוויר.
• פריסת הסוכן ב-Cloud Run מקוד המקור
• מריצים את הסוכן כדי לשאול שאילתה לגבי מידע על מזג האוויר.

עלויות

במסמך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

• Artifact Registry
• Cloud Build
• Cloud Run
• Vertex AI

כדי ליצור הערכת עלויות בהתאם לשימוש החזוי, אתם יכולים להשתמש במחשבון התמחור.

משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

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

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. מפעילים את Cloud Run Admin API,‏ Vertex AI API ו-Cloud Build APIs, אם הם עדיין לא מופעלים.

   תפקידים שנדרשים להפעלת ממשקי API

   כדי להפעיל ממשקי API, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

   הפעלת ממשקי ה-API

2. הגדרת סביבת הפיתוח של Cloud Run בפרויקט Google Cloud .
3. כדי להתקין את ADK, פועלים לפי ההוראות בתיעוד של הערכה לפיתוח סוכנים.

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

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לפריסת סוכן AI ב-Cloud Run, אתם צריכים לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

• Cloud Run Source Developer (roles/run.sourceDeveloper) on the project
• משתמש Vertex AI (roles/aiplatform.user) בפרויקט
• משתמש בחשבון שירות (roles/iam.serviceAccountUser) בזהות השירות
• ‫Logs Viewer (roles/logging.viewer) on the project

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

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

כתיבת האפליקציה לדוגמה

כדי לכתוב אפליקציה ב-Python:

1. יוצרים ספריית הורה חדשה בשם parent_folder ועוברים אליה:

   mkdir parent_folder
   cd parent_folder
   

2. בספרייה parent_folder, יוצרים ספריית משנה חדשה בשם multi_tool_agent ועוברים אליה:

   mkdir multi_tool_agent
   cd multi_tool_agent
   

3. יוצרים קובץ __init__.py לייבוא הסוכן:

   from . import agent
   

4. יוצרים קובץ agent.py כדי להגדיר את הסוכן שיענה על שאלות לגבי השעה ומזג האוויר בעיר מסוימת:

   import datetime
   from zoneinfo import ZoneInfo
   from google.adk.agents import Agent
   
   def get_weather(city: str) -> dict:
       """Retrieves the current weather report for a specified city.
   
       Args:
           city (str): The name of the city for which to retrieve the weather report.
   
       Returns:
           dict: status and result or error msg.
       """
       if city.lower() == "new york":
           return {
               "status": "success",
               "report": (
                   "The weather in New York is sunny with a temperature of 25 degrees"
                   " Celsius (77 degrees Fahrenheit)."
               ),
           }
       else:
           return {
               "status": "error",
               "error_message": f"Weather information for '{city}' is not available.",
           }
   
   def get_current_time(city: str) -> dict:
       """Returns the current time in a specified city.
   
       Args:
           city (str): The name of the city for which to retrieve the current time.
   
       Returns:
           dict: status and result or error msg.
       """
   
       if city.lower() == "new york":
           tz_identifier = "America/New_York"
       else:
           return {
               "status": "error",
               "error_message": (
                   f"Sorry, I don't have timezone information for {city}."
               ),
           }
   
       tz = ZoneInfo(tz_identifier)
       now = datetime.datetime.now(tz)
       report = (
           f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
       )
       return {"status": "success", "report": report}
   
   root_agent = Agent(
       name="weather_time_agent",
       model="gemini-2.5-flash",
       description=(
           "Agent to answer questions about the time and weather in a city."
       ),
       instruction=(
           "You are a helpful agent who can answer user questions about the time and weather in a city."
       ),
       tools=[get_weather, get_current_time],
   )
   

5. יוצרים קובץ .env ומוסיפים את המשתנים הבאים:

   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   GOOGLE_CLOUD_PROJECT=PROJECT_ID
   GOOGLE_CLOUD_LOCATION=REGION
   

   מחליפים את מה שכתוב בשדות הבאים:

   • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
   • ‫REGION: האזור שבו אתם מתכננים לפרוס את השירות.

6. עוברים לספריית התיקייה הראשית parent_folder ויוצרים קובץ requirements.txt כדי להוסיף את התלות google-adk:

   google-adk
   

   פרויקט המקור כולל את המבנה הבא:

   parent_folder/
   ├── requirements.txt
   └── multi_tool_agent/
       ├── __init__.py
       ├── agent.py
       └── .env
   

האפליקציה מוכנה לפריסה.

פריסה מקוד המקור ל-Cloud Run

האפשרות 'פריסה ממקור' יוצרת באופן אוטומטי קובץ אימג' של קונטיינר מקוד המקור ופורסת אותו.

1. בספריית קוד המקור (parent_folder), פורסים ל-Cloud Run באמצעות הפקודה הבאה:

   gcloud run deploy --source .

   1. כשמופיעה בקשה להזין את שם השירות, לוחצים על Enter כדי לאשר את שם ברירת המחדל, לדוגמה weather-agent.

   2. אם תתבקשו להפעיל ממשקי API נוספים בפרויקט, למשל Artifact Registry API, תצטרכו להגיב בהקשה על y.

   3. כשמוצגת בקשה לבחור אזור: בוחרים את האזור הרצוי, לדוגמה europe-west1.

   4. אם מוצגת בקשה ליצור מאגר באזור שצוין, משיבים על ידי הקשה על y.

   5. אם מופיעה בקשה allow public access: משיבים y. יכול להיות שההנחיה הזו לא תוצג אם יש מדיניות ארגונית להגבלת דומיין שמונעת את הצגתה. פרטים נוספים זמינים בקטע לפני שמתחילים.

   אחר כך מחכים כמה רגעים עד שהפריסה תסתיים. אם הפריסה הצליחה, כתובת ה-URL של הסוכן שנפרס תוצג בשורת הפקודה בפורמט הבא: https://weather-agent-123456789101.us-central1.run.app/list-apps.

הרצת הסוכן

כדי להשתמש בסוכן ADK, אפשר להריץ את פקודות ה-curl הבאות:

1. כדי לקבל את רשימת האפליקציות, מריצים את הפקודה הבאה:

   curl -X GET SERVICE_URL/list-apps
   

   מחליפים את SERVICE_URL בכתובת ה-URL של השירות שפרסתם.

2. כדי להתחיל סשן, מריצים את הפקודה הבאה:

   curl -X POST SERVICE_URL/apps/multi_tool_agent/users/u_123/sessions/s_123 -H "Content-Type: application/json" -d '{"key1": "value1", "key2": "value2"}'
   

3. כדי לשלוח שאילתה לסוכן, מריצים את הפקודה הבאה:

   curl -X POST SERVICE_URL/run \
   -H "Content-Type: application/json" \
   -d "{\"appName\": \"multi_tool_agent\",\"userId\": \"u_123\",\"sessionId\": \"s_123\",\"newMessage\": { \"role\": \"user\", \"parts\": [{ \"text\": \"What's the weather in New York today?\" }]}}"
   

הסוכן מחזיר את נתוני מזג האוויר בתוצאות השאילתה.

מידע נוסף ודוגמאות לגבי פקודות curl נתמכות זמינים במאמר שימוש בשרת ה-API במסמכי התיעוד של ADK.

הצלחה: פרסתם סוכן AI באמצעות הערכה לפיתוח סוכנים ב-Cloud Run.

הסרת המשאבים

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

מחיקת הפרויקט

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

הדרך הקלה ביותר לבטל את החיוב היא למחוק את הפרויקט שיצרתם בשביל המדריך.

כדי למחוק את הפרויקט:

זהירות: כשמוחקים פרויקט:

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

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

1. במסוף Google Cloud , נכנסים לדף Manage resources.

   כניסה לדף Manage resources

2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

מחיקת משאבים של מדריך

1. מוחקים את שירות Cloud Run שפרסתם במדריך הזה. שירותי Cloud Run לא צוברים עלויות עד שהם מקבלים בקשות.

   כדי למחוק את שירות Cloud Run, מריצים את הפקודה הבאה:

   gcloud run services delete SERVICE-NAME

   מחליפים את SERVICE-NAME בשם השירות.

   אפשר גם למחוק שירותים של Cloud Run מGoogle Cloud המסוף.

2. מסירים את הגדרת ברירת המחדל של האזור gcloud שהוספתם במהלך ההגדרה של המדריך:

    gcloud config unset run/region
   

3. מסירים את הגדרת הפרויקט:

    gcloud config unset project