הגדרת הסביבה

לפני שמתחילים לעבוד עם Agent Runtime, צריך לוודא שהסביבה מוגדרת. צריך פרויקט ב- Google Cloud עם חיוב מופעל, ההרשאות הנדרשות, קטגוריה של Cloud Storage ו-Agent Platform SDK ל-Python. כדי להתחיל לעבוד עם Agent Runtime, כדאי לקרוא את הנושאים הבאים.

כדי לייעל את ההגדרה והפריסה של סביבת Agent Runtime, אתם יכולים להשתמש בדוגמה של Terraform ב-agent-starter-pack.

הגדרה בעזרת Google Cloud

כדי להגדיר את Google Cloud ל-Agent Runtime, צריך ליצור פרויקט ב- Google Cloud .

פרויקט Google Cloud

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

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

  2. 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.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Gemini Enterprise Agent Platform, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  5. 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.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Gemini Enterprise Agent Platform, Cloud Storage, Cloud Logging, Cloud Monitoring, Telemetry, Cloud Trace, and Resource Manager APIs, if any are not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

    8.

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

כדי לקבל את ההרשאות שנדרשות לשימוש ב-Agent Runtime, בקשו מהאדמין להקצות לכם את התפקיד משתמש בפלטפורמת הסוכנים (roles/aiplatform.user) ב-IAM בפרויקט. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

הגדרת הזהות וההרשאות של הסוכן

כשמגדירים זהות והרשאות, יש כמה אפשרויות:

  • זהות הנציג (מומלץ) משתמשים בזהות הנציג של ניהול הזהויות והרשאות הגישה (IAM) כדי לספק תכונות של אבטחה וניהול גישה כשמשתמשים בנציגים ב-Agent Runtime. הזהות של הסוכן קשורה לכל סוכן בנפרד. כברירת מחדל, לסוכנים יש את התפקיד גישת ברירת המחדל של סוכן בפלטפורמת הסוכנים (roles/aiplatform.agentDefaultAccess), שכולל רק הרשאות בסיסיות לרישום ביומן ברמת הפרויקט ולקריאה למודלים, ואת התפקיד עריכת הקשר של סוכן בפלטפורמת הסוכנים (roles/aiplatform.agentContextEditor), שמגביל את הסוכן לגישה רק לסשנים, לזיכרונות ולארגזי החול שלו.

    הערה: יכול להיות שחלק מהתכונות שנגישות לתפקיד הזה נמצאות בגרסת טרום-השקה (Preview)

  • חשבונות שירות: חשבונות שירות משותפים בין נציגים שאתם פורסים ב-Agent Runtime. יש שתי אפשרויות לחשבון השירות:

    • סוכן שירות שמוגדר כברירת מחדל: כברירת מחדל, הסוכנים משתמשים בסוכן השירות של מנוע החשיבה הרציונלית של פלטפורמת AI. לחשבון השירות הזה שמנוהל על ידי Google יש את התפקיד סוכן שירות של מנוע החשיבה הרציונלית ב-Gemini Enterprise Agent Platform (roles/aiplatform.reasoningEngineServiceAgent), שכולל את הרשאות ברירת המחדל שנדרשות לסוכנים שנפרסו.
    • חשבון שירות בהתאמה אישית: אתם יכולים לציין חשבון שירות משלכם שבו הסוכנים ישתמשו. כך אתם יכולים לשלוט בצורה מדויקת יותר בהרשאות שניתנות לנציגים.

זהות הסוכן

כדי להגדיר את מדיניות ה-IAM לפני פריסת הנציג, אתם יכולים ליצור זהות לנציג בלי לפרוס את הקוד שלו. כדי לעשות את זה, יוצרים מופע של Agent Platform עם השדה identity_type בלבד:

remote_app = client.agent_engines.create(
      config={
          "identity_type": types.IdentityType.AGENT_IDENTITY,
      },
)

אחרי שיוצרים את המכונה של Agent Platform עם זהות הסוכן, אפשר לבצע את הפעולות הבאות:

  1. מקצים לזהות הסוכן תפקידים נוספים לפי הצורך.

  2. מוסיפים את קוד הסוכן באמצעות agent_engine.update(...).

סוכן שירות שמוגדר כברירת מחדל

כברירת מחדל, נעשה שימוש בסוכן השירות של מנוע החשיבה הרציונלית של פלטפורמת ה-AI. הרשימה המלאה של הרשאות ברירת המחדל מופיעה במסמכי התיעוד של IAM.

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

  1. נכנסים לדף IAM ומסמנים את התיבה Include Google-provided role grants.

    כניסה לדף IAM

  2. מוצאים את חשבון המשתמש שמתאים ל-service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

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

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

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

כך יוצרים באופן ידני סוכן שירות של מנוע חשיבה רציונלית:

  1. יוצרים את סוכן השירות של מנוע החשיבה הרציונלית באמצעות Google Cloud CLI.

    gcloud beta services identity create --service=aiplatform.googleapis.com --project=PROJECT-ID-OR-PROJECT-NUMBER

  2. נכנסים לדף IAM ולוחצים על Grant Access.

    כניסה לדף IAM

  3. בקטע Add principals, בשדה New principals מזינים את הערך service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com.

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

  5. לוחצים על הלחצן שמירה.

חשבון שירות בהתאמה אישית

כדי להשתמש בחשבון שירות משלכם, אתם צריכים לתת לו את ההרשאות הנדרשות להפעלת הנציג. כנראה שחשבון השירות בהתאמה אישית צריך את התפקיד משתמש בפלטפורמת הסוכנים (roles/aiplatform.user).

  1. אם אין לכם חשבון שירות, אתם צריכים ליצור אחד. איך יוצרים חשבונות שירות

  2. מקצים לחשבון השירות את התפקיד משתמש בפלטפורמת הסוכן (roles/aiplatform.user).

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

  4. כדי לפרוס את הנציג באמצעות חשבון השירות הזה, צריך להקצות לעצמכם את התפקיד משתמש בחשבון שירות (roles/iam.serviceAccountUser) בחשבון השירות בהתאמה אישית.

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

חשבון שירות בהתאמה אישית בפרויקטים שונים

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

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

  2. נותנים הרשאות לסוכן השירות של פלטפורמת הסוכנים: בפרויקט שבו נמצא חשבון השירות, נותנים את התפקיד יצירת אסימונים בחשבון שירות (roles/iam.serviceAccountTokenCreator) לסוכן השירות של פלטפורמת הסוכנים (service-RESOURCE_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) של הפרויקט שבו רוצים לפרוס את הסוכן.

  3. הקצאת הרשאות לחשבון השירות בהתאמה אישית: בפרויקט שבו אתם מתכננים לפרוס את הנציג, מקצים את התפקידים הנדרשים לחשבון השירות בהתאמה אישית. בדרך כלל זה כולל את התפקיד משתמש בפלטפורמת הסוכן (roles/aiplatform.user) וכל תפקיד אחר שנדרש לפי קוד הסוכן.

(אופציונלי) יצירת קטגוריה של Cloud Storage

הצורך בקטגוריה של Cloud Storage תלוי בשאלה אם Agent Platform SDK for Python צריך מקום להכנת קוד הנציג לפני הפריסה:

  • פריסה מקובצי מקור: הנציג קיים כקבצים. ערכת ה-SDK של Agent Platform ל-Python יכולה לארוז ולהעלות את הקבצים האלה ישירות לשירות הפריסה, כך שלא צריך קטגוריית Staging ב-Cloud Storage.

  • פריסה מאובייקט של נציג: הנציג קיים בזיכרון. ה-SDK של Agent Platform ל-Python אורז את האובייקט הזה ומעלה אותו לקטגוריה של Cloud Storage, שמשמשת כסביבת Staging לשירות הפריסה.

פריסה מקובצי מקור

אם פורסים נציג מקובצי מקור, לא צריך קטגוריה של Cloud Storage.

פריסה מאובייקט

כשפורסים מאובייקט של סוכן, Agent Runtime מעביר את פריטי המידע שנוצרו של הסוכנים שנפרסו לקטגוריה של Cloud Storage כחלק מתהליך הפריסה. חשוב לוודא שלחשבון המשתמש שמאומת לשימוש ב-Gemini Enterprise Agent Platform (אתם או חשבון שירות) יש גישה מסוג Storage Admin לקטגוריה הזו. הפעולה הזו נדרשת כי Agent Platform SDK for Python כותב את הקוד שלכם בקטגוריה הזו.

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

מבקשים מהאדמין להקצות לכם את התפקיד Storage Admin ‏(roles/storage.admin) ב-IAM בפרויקט.

מסוףGoogle Cloud

  1. במסוף Google Cloud , נכנסים לדף Buckets של Cloud Storage.

    כניסה לדף Buckets

  2. לוחצים על Create.
  3. ממלאים את פרטי הקטגוריה בדף Create a bucket. כדי לעבור לשלב הבא לוחצים על Continue.
    1. בקטע Get started, מבצעים את הפעולות הבאות:
    2. בקטע Choose where to store your data, מבצעים את הפעולות הבאות:
      1. בוחרים Location type.
      2. בתפריט הנפתח Location type, בוחרים את המיקום שבו נתוני הקטגוריה יישמרו באופן קבוע.
      3. כדי להגדיר רפליקציה בין קטגוריות, בוחרים באפשרות Add cross-bucket replication via Storage Transfer Service ופועלים לפי השלבים הבאים:

        הגדרת רפליקציה בין קטגוריות

        1. בתפריט Bucket בוחרים קטגוריה.

        2. בקטע Replication settings, לוחצים על Configure כדי לקבוע את ההגדרות של משימת הרפליקציה.

          מופיע החלונית Configure cross-bucket replication.

          • כדי לסנן אובייקטים שרוצים לשכפל לפי קידומת של שם האובייקט, מזינים את הקידומת שרוצים לכלול או להחריג, ואז לוחצים על Add a prefix.
          • כדי להגדיר סוג אחסון לאובייקטים המשוכפלים, בוחרים סוג אחסון מהתפריט Storage class. אם מדלגים על השלב הזה, האובייקטים המשוכפלים ישתמשו כברירת מחדל בסוג האחסון של קטגוריית היעד.
          • לוחצים על סיום.
    3. בקטע Choose how to store your data, מבצעים את הפעולות הבאות:
      1. בוחרים סוג אחסון (storage class) שמוגדר כברירת מחדל לקטגוריה, או בוחרים ב-Autoclass לניהול אוטומטי של סוג האחסון של נתוני הקטגוריה.
      2. כדי להפעיל מרחב שמות היררכי, בקטע Optimize storage for data-intensive workloads בוחרים באפשרות Enable hierarchical namespace on this bucket.
    4. בקטע Choose how to control access to objects, בוחרים אם הקטגוריה אוכפת public access prevention או לא, ואז בוחרים שיטת בקרת גישה לאובייקטים של הקטגוריה.
    5. בקטע Choose how to protect object data, מבצעים את הפעולות הבאות:
      • בוחרים את האפשרויות שרוצים להגדיר לקטגוריה בקטע הגנה על נתונים.
        • כדי להפעיל מחיקה רכה, לוחצים על תיבת הסימון Soft delete policy (For data recovery) ומציינים את מספר הימים שבהם רוצים לשמור את האובייקטים אחרי המחיקה.
        • כדי להגדיר ניהול גרסאות של אובייקטים, לוחצים על תיבת הסימון ניהול גרסאות של אובייקטים (לניהול גרסאות) ומציינים את המספר המקסימלי של גרסאות לכל אובייקט ואת מספר הימים שאחריהם פג התוקף של הגרסאות הלא עדכניות.
        • כדי להפעיל את מדיניות שמירת הנתונים על אובייקטים וקטגוריות, לוחצים על תיבת הסימון Retention (For compliance)‎ ואז מבצעים את הפעולות הבאות:
          • כדי להפעיל את נעילת שמירת האובייקטים, לוחצים על תיבת הסימון Enable object retention.
          • כדי להפעיל את Bucket Lock, לוחצים על תיבת הסימון Set bucket retention policy ובוחרים יחידת זמן ואת משך הזמן של תקופת השמירה.
      • כדי לבחור איך להצפין את נתוני האובייקטים, מרחיבים את הקטע Data encryption () ובוחרים שיטה ל-Data encryption.
  4. לוחצים על יצירה.

שורת הפקודה

    יוצרים קטגוריה ב-Cloud Storage ומגדירים אותה כך:
    • מחליפים את STORAGE_CLASS בסוג האחסון המועדף.
    • מחליפים את LOCATION במיקום המועדף (ASIA, ‏EU או US)
    • מחליפים את BUCKET_NAME בשם קטגוריה של שעומד בקריטריונים לשמות של קטגוריות. 
    gcloud storage buckets create gs://BUCKET_NAME --default-storage-class STORAGE_CLASS --location LOCATION

התקנה והפעלה של Agent Platform SDK ל-Python

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

(אופציונלי) הגדרת סביבה וירטואלית

מומלץ גם להגדיר סביבה וירטואלית כדי לבודד את יחסי התלות.

התקנה

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

  • ‫agent_engines: קבוצת החבילות שנדרשות לפריסה ב-Agent Runtime.
  • ‫adk: קבוצת החבילות התואמות של הערכה לפיתוח סוכנים (ADK).
  • ‫langchain: קבוצת החבילות התואמות של LangChain ו-LangGraph.
  • ‫ag2: קבוצת החבילות התואמות של AG2.
  • ‫llama_index: קבוצת החבילות התואמות של LlamaIndex.

כשמתקינים את Agent Platform SDK ל-Python, אפשר לציין את יחסי התלות הנדרשים (מופרדים בפסיקים). כדי להתקין את כל האפליקציות:

pip install google-cloud-aiplatform[agent_engines,adk,langchain,ag2,llama_index]>=1.112.0

כדי להשתמש ב-Agent2Agent (A2A) ב-Agent Platform , צריך להתקין גם את חבילת a2a-sdk:

pip install google-adk[a2a]

אימות

Colab

מריצים את הקוד הבא:

from google.colab import auth

auth.authenticate_user(project_id="PROJECT_ID")

Cloud Shell

לא נדרשת כל פעולה.

מעטפת מקומית

מריצים את הפקודה הבאה:

gcloud auth application-default login

ייבוא והפעלה של ה-SDK

מריצים את הקוד הבא כדי לייבא ולאתחל את ה-SDK של Agent Runtime:

פרויקט Google Cloud 

import vertexai
from vertexai import agent_engines # For the prebuilt templates

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

כאשר

(אופציונלי) שימוש בקונטיינר משלכם (BYOC)

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

כדי לפרוס את הנציג באמצעות קונטיינר בהתאמה אישית, צריך לבצע את המשימות הבאות:

  1. יוצרים את קובץ האימג' של הקונטיינר ומעבירים אותו ל-Artifact Registry.
  2. הגדרת הזהות וההרשאות של הנציג.
  3. מקצים את התפקיד "קריאה ב-Artifact Registry" לסוכן השירות שמוגדר כברירת מחדל של Agent Runtime.

יצירה והעברה של קובץ האימג' של הקונטיינר

כדי ליצור קובץ אימג' של קונטיינר ולהעביר אותו בדחיפה, פועלים לפי ההוראות במאמר יצירה והעברה בדחיפה של קובץ אימג' של Docker באמצעות Cloud Build.

הגדרת הזהות וההרשאות של Agent Runtime

כדי לייבא קונטיינרים מהמאגר של Artifact Registry, צריך להשתמש בסוכן השירות שמוגדר כברירת מחדל ב-Agent Runtime.

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

הקצאת התפקיד "קריאה ב-Artifact Registry"

מקצים את התפקיד "קריאה מ-Artifact Registry" (roles/artifactregistry.reader) לסוכן השירות שמוגדר כברירת מחדל (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com).

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

gcloud projects add-iam-policy-binding PROJECT_NUMBER \
  --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com" \
  --role="roles/artifactregistry.reader"

(אופציונלי) מתן הרשאה בפרויקטים שונים

אם קובצי האימג' של הקונטיינרים מאוחסנים במאגר של Artifact Registry בפרויקט ב- Google Cloud שונה מהפרויקט שבו הנציגים פרוסים, צריך הרשאה לפרויקטים שונים.

במקרה כזה, צריך להקצות את התפקיד "קריאה מ-Artifact Registry" לסוכן השירות של Agent Platform‏ (service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) בפרויקט של מאגר Artifact Registry.

gcloud projects add-iam-policy-binding AR_REPO_PROJECT_NUMBER \
  --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/artifactregistry.reader"

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

סקירה כללית

איך יוצרים נציג באמצעות Agent Platform Runtime.

פתרון בעיות

איך פותרים שגיאות נפוצות כשיוצרים סוכנים בהתאמה אישית.

משאב

מקורות מידע ותמיכה ל-Google Agent Platform.