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

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

כדי לכתוב אפליקציה ב-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: מזהה הפרויקט ב- Cloud de Confiance by S3NS .
   • ‫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.