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

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

כשאתם פורסים מקוד מקור, Cloud Run יוצר באופן אוטומטי קובץ אימג' של קונטיינר בשביל השירות. במאמר פיתוח אפליקציה ב-Python מוסבר איך ה-buildpack של Python קובע את נקודת הכניסה שמוגדרת כברירת מחדל לפריסות של קוד מקור ב-Cloud Run.

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

  1. התקינו את ה-CLI של Google Cloud.

  2. הגדירו שה-CLI של gcloud ישתמש בזהות המאוחדת שלכם.

    איך נכנסים ל-CLI של gcloud באמצעות הזהות המאוחדת?

  3. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה: 

    gcloud init

  4. יוצרים או בוחרים פרויקט ב- Google Cloud .

    התפקידים שנדרשים כדי לבחור או ליצור פרויקט

    • בחירת פרויקט: כדי לבחור פרויקט לא נדרש תפקיד IAM ספציפי – אתם יכולים לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד "יצירת פרויקטים" (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים?

    • יוצרים פרויקט ב- Google Cloud :

      gcloud projects create PROJECT_ID

      מחליפים את PROJECT_ID בשם של הפרויקט ב- Google Cloud שאתם יוצרים.

    • בוחרים את הפרויקט שיצרתם ב- Google Cloud :

      gcloud config set project PROJECT_ID

      מחליפים את PROJECT_ID בשם הפרויקט ב- Google Cloud .

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

  6. מוודאים שהחיוב מופעל בפרויקט ב- Google Cloud .

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

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

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

    gcloud services enable run.googleapis.com aiplatform.googleapis.com cloudbuild.googleapis.com
  8. מתקינים את ה-ADK לפי ההוראות במסמכי התיעוד של ערכת הפיתוח לסוכנים.

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

  10. למחירון של Cloud Run או למחשבון עלויות.

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

כדי לקבל את ההרשאות שדרושות להשלמת המדריך למתחילים, אתם צריכים לבקש מהאדמין לתת לכם את התפקידים הבאים ב-IAM:

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

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

מתן גישה לפרויקט לחשבון השירות של Cloud Build

כברירת מחדל, Cloud Build משתמש בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine בתור חשבון השירות שמוגדר כברירת מחדל ב-Cloud Build כדי ליצור את קוד המקור ואת המשאב של Cloud Run, אלא אם משנים את ההתנהגות הזו.

כדי ש-Cloud Build יוכל ליצור את המקורות, צריך להקצות לחשבון השירות של Cloud Build את התפקיד Cloud Run Builder‏ (roles/run.builder) בפרויקט:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder

מחליפים את PROJECT_ID במזהה הפרויקט ב- Google Cloudואת SERVICE_ACCOUNT_EMAIL_ADDRESS בכתובת האימייל של חשבון השירות של Cloud Build. אם אתם משתמשים בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine בתור חשבון השירות של Cloud Build, השתמשו בפורמט הבא לכתובת האימייל של חשבון השירות:

PROJECT_NUMBER-compute@

מחליפים את PROJECT_NUMBER במספר הפרויקט ב- Google Cloud.

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

הקצאת התפקיד "מפתח ב-Cloud Run" מתעדכנת תוך כמה דקות.

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

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

הסרת המשאבים

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

מחיקת המאגר

ב-Cloud Run לא תחויבו כשהשירות שפרסתם לא בשימוש. עם זאת, יכול להיות שעדיין תחויבו על אחסון קובץ האימג' של הקונטיינר ב-Artifact Registry. כדי למחוק מאגרים של Artifact Registry, פועלים לפי השלבים שמפורטים במאמר מחיקת מאגרים במסמכי התיעוד של Artifact Registry.

מחיקת השירות

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

המסוף

כדי למחוק שירות:

  1. נכנסים לדף Services של Cloud Run במסוף Google Cloud :

    כניסה ל-Cloud Run

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

  3. לוחצים על Delete. כל הגרסאות של השירות יימחקו.

gcloud

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

gcloud run services delete SERVICE --region REGION

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

  • ‫SERVICE: שם השירות.
  • ‫REGION: Google Cloud האזור של השירות.

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

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

    כדי למחוק פרויקט ב- Google Cloud :

    gcloud projects delete PROJECT_ID

המאמרים הבאים

למידע נוסף על בניית קונטיינר מקוד מקור ודחיפה למאגר, ראו: