הגדרת הסביבה

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

כדי לראות דוגמה של Terraform שתעזור לכם להגדיר ולפרוס את סביבת Agent Runtime, כדאי לעיין בחבילת ההתחלה של הסוכן.

הגדרה באמצעות Google Cloud

כדי להגדיר את Agent Runtime, צריך ליצור פרויקט Google Cloud . 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.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

    8.

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

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

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

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

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

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

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

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

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

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

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

    כניסה לדף IAM

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

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

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

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

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

  1. יוצרים את סוכן השירות של Reasoning Engine באמצעות 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. לוחצים על הלחצן שמירה.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

מסוףGoogle Cloud

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

    כניסה לדף Buckets

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

        הגדרה של רפליקציה בין מאגרי מידע

        1. בתפריט Bucket, בוחרים באפשרות הרצויה.

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

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

          • כדי לסנן אובייקטים לשכפול לפי קידומת של שם האובייקט, מזינים קידומת שרוצים לכלול או להחריג אובייקטים ממנה, ואז לוחצים על הוספת קידומת.
          • כדי להגדיר סוג אחסון לאובייקטים המשוכפלים, בוחרים סוג אחסון מהתפריט סוג אחסון. אם מדלגים על השלב הזה, האובייקטים המשוכפלים ישתמשו בסוג האחסון של קטגוריית היעד כברירת מחדל.
          • לוחצים על סיום.
    3. בקטע Choose how to store your data, מבצעים את הפעולות הבאות:
      1. בוחרים default storage class לקטגוריה או Autoclass לניהול אוטומטי של סוג האחסון (storage class) של נתוני הקטגוריה.
      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, מבצעים את הפעולות הבאות:
      • בוחרים באחת מהאפשרויות בקטע הגנה על נתונים שרוצים להגדיר עבור הדלי.
        • כדי להפעיל מחיקה עם יכולת שחזור, מסמנים את התיבה מדיניות מחיקה עם יכולת שחזור (לשחזור נתונים) ומציינים את מספר הימים שבהם רוצים לשמור אובייקטים אחרי המחיקה.
        • כדי להגדיר ניהול גרסאות של אובייקטים, מסמנים את התיבה ניהול גרסאות של אובייקטים (לשליטה בגרסאות) ומציינים את מספר הגרסאות המקסימלי לכל אובייקט ואת מספר הימים שאחריהם הגרסאות הלא עדכניות יפוגו.
        • כדי להפעיל את מדיניות שמירת הנתונים על אובייקטים וקטגוריות, לוחצים על תיבת הסימון שמירת נתונים (לצורך תאימות), ואז מבצעים את הפעולות הבאות:
          • כדי להפעיל את הנעילה של שמירת אובייקטים, מסמנים את התיבה הפעלת שמירת אובייקטים.
          • כדי להפעיל את נעילת הקטגוריה, מסמנים את תיבת הסימון הגדרת מדיניות שמירת נתונים בקטגוריה ובוחרים יחידת זמן ואת משך הזמן של תקופת השמירה.
      • כדי לבחור איך להצפין את נתוני האובייקט, מרחיבים את הקטע Data encryption () ובוחרים Data encryption method.
  4. לוחצים על יצירה.

שורת הפקודה

    יוצרים קטגוריה ב-Cloud Storage ומגדירים אותה כך: 
    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 Reader (קריאה ב-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

פתרון בעיות

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

Resource

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