פריסת סוכן

כשפורסים סוכן ב-Agent Runtime, הוא זמין מרחוק לטיפול בבקשות. במסמך הזה מוסבר איך לפרוס סוכן בהתאם לתהליך העבודה של הפיתוח: מאובייקט הפעלה, מקובצי מקור מקומיים, מקובץ Dockerfile, מקובץ אימג' בקונטיינר שמתארח ב-Artifact Registry או ישירות דרך מאגר Git מקושר.

כדי לפרוס סוכן ב-Agent Runtime, אפשר לבחור באחת מהשיטות הבאות:

  • פריסה מאובייקט של סוכן: מתאים לפיתוח אינטראקטיבי בסביבות כמו Colab, ומאפשר פריסה של אובייקטים של local_agent בזיכרון. השיטה הזו מתאימה לסוכנים עם מבנים שלא מכילים רכיבים מורכבים שלא ניתן לסדר אותם בסדרות.
  • פריסה מקובצי מקור: השיטה הזו מתאימה במיוחד לתהליכי עבודה אוטומטיים כמו צינורות עיבוד נתונים של CI/CD וכלים של תשתית כקוד כמו Terraform, ומאפשרת פריסות מוצהרות ואוטומטיות לחלוטין. הוא פורס את הסוכן ישירות מקוד המקור המקומי ולא דורש קטגוריה של Cloud Storage.
  • פריסה מקובץ Dockerfile: השיטה הזו דומה לשיטה של פריסה מקובצי מקור. אתם פורסים את הסוכן ישירות מקוד מקור מקומי. לא צריך קטגוריה של Cloud Storage. השיטה הזו מתאימה אם אתם צריכים להגדיר ולשלוט בשרת ה-API שנפרס. המאגר שנפרס חייב לפעול בהתאם לחוזה זמן הריצה.
  • פריסה מקובץ אימג' של קונטיינר: השיטה הזו דומה לשיטה של פריסה מקובץ Dockerfile. אתם פורסים קובץ אימג' של קונטיינר שמתארח ב-Artifact Registry. כדאי להשתמש בשיטה הזו אם רוצים לשלוט בתהליך build של קובץ אימג' של קונטיינר ולקצר את זמן האחזור של הפריסה. קובץ אימג' של קונטיינר חייב לעמוד בדרישות של חוזה זמן הריצה.
  • פריסה מ-Developer Connect: מומלץ לפרויקטים שמנוהלים במאגר Git שמקושרים דרך Developer Connect. השיטה הזו מייעלת את הפריסה של הסוכן ישירות מקוד המקור, ותומכת באופן מובנה בניהול גרסאות, בעריכה משותפת ובצינורות CI/CD. לפני שמשתמשים בשיטה הזו, צריך להגדיר את הקישור למאגר Git באמצעות ההוראות שבקטע הגדרת קישור למאגר Git של Developer Connect.

כדי להתחיל, מבצעים את השלבים הבאים:

  1. השלמת הדרישות המוקדמות
  2. אופציונלי: הגדרת הסוכן לפריסה
  3. יצירת מופע של Agent Platform
  4. אופציונלי: קבלת מזהה המשאב של הסוכן
  5. אופציונלי: רשימת הפעולות הנתמכות
  6. אופציונלי: מתן הרשאות לסוכן הפרוס

אפשר גם להשתמש ב-Agents CLI לפריסה.

דרישות מוקדמות

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

  1. הגדרת הסביבה
  2. יצירת סוכן

אופציונלי: הגדרת הסוכן לפריסה

אפשר לבצע את ההגדרות האופציונליות הבאות לסוכן:

יצירת מופע של Agent Platform

בקטע הזה מוסבר איך ליצור מופע של Agent Platform כדי לפרוס סוכן.

כדי לפרוס סוכן ב-Agent Platform, אפשר לבחור בין השיטות הבאות:

  • פריסה מאובייקט של סוכן לפיתוח אינטראקטיבי.
  • פריסה מ-Developer Connect לתהליכי עבודה מבוססי-Git.
  • פריסה מקובצי מקור או מקובץ Docker לתהליכי עבודה שמבוססים על קבצים.

  • פריסה מקובץ אימג' של קונטיינר לתהליכי עבודה מבוססי-אימג'.

אובייקט Python

כדי לפרוס את הסוכן ב-Agent Platform, משתמשים ב-client.agent_engines.create כדי להעביר את האובייקט local_agent יחד עם הגדרות אופציונליות:

remote_agent = client.agent_engines.create(
    agent=local_agent,                                  # Optional.
    config={
        "requirements": requirements,                   # Optional.
        "extra_packages": extra_packages,               # Optional.
        "gcs_dir_name": gcs_dir_name,                   # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # Optional.
        "service_account": service_account,             # Optional.
        "min_instances": min_instances,                 # Optional.
        "max_instances": max_instances,                 # Optional.
        "resource_limits": resource_limits,             # Optional.
        "container_concurrency": container_concurrency, # Optional
        "encryption_spec": encryption_spec,             # Optional.
        "agent_framework": agent_framework,             # Optional.
    },
)

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

  1. חבילה של הארטיפקטים הבאים נוצרת באופן מקומי:

  2. החבילה מועלית ל-Cloud Storage (בתיקייה המתאימה) כדי להכין את הארטיפקטים.

  3. מזהי ה-URI של Cloud Storage עבור פריטי המידע שנוצרו בתהליך פיתוח (Artifacts) הרלוונטיים מצוינים ב-PackageSpec.

  4. שירות Agent Runtime מקבל את הבקשה, בונה מאגרי תגים ומתחיל שרתי HTTP בקצה העורפי.

Developer Connect

כדי לבצע פריסה מ-Developer Connect ב-Agent Platform, צריך להשתמש ב-client.agent_engines.create ולספק את הערכים developer_connect_source, entrypoint_module ו-entrypoint_object במילון ההגדרות, יחד עם הגדרות אופציונליות אחרות. בשיטה הזו אפשר לפרוס קוד ישירות ממאגר Git מקושר.

remote_agent = client.agent_engines.create(
    config={
        "developer_connect_source": {                   # Required.
            "git_repository_link": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID",
            "revision": "main",
            "dir": "path/to/dir",
        },
        "entrypoint_module": "agent",                   # Required.
        "entrypoint_object": "root_agent",              # Required.
        "requirements_file": "requirements.txt",        # Optional.
        # Other optional configs:
        # "env_vars": {...},
        # "service_account": "...",
    },
)

הפרמטרים לפריסה של Developer Connect הם:

  • ‫developer_connect_source (חובה, dict): ההגדרה לאחזור קוד המקור. פרטים נוספים זמינים במאמר בנושא הגדרת קישור למאגר Git של Developer Connect.
    • ‫git_repository_link (חובה, str): שם המשאב של הקישור למאגר Git של Developer Connect.
    • ‫revision (חובה, str): הגרסה לאחזור (ענף, תג או SHA של קומיט).
    • ‫dir (חובה, str): ספריית הבסיס של קוד הסוכן במאגר.
  • ‫entrypoint_module (חובה, str): שם מודול Python שמכיל את נקודת הכניסה של הסוכן, ביחס לספרייה שצוינה ב-developer_connect_source.dir.
  • ‫entrypoint_object (חובה, str): השם של האובייקט שאפשר להתקשר אליו בתוך entrypoint_module שמייצג את אפליקציית הסוכן (לדוגמה, root_agent).
  • ‫requirements_file (אופציונלי, str): הנתיב לקובץ דרישות של pip ביחס לשורש המקור. ברירת המחדל היא requirements.txt.

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

  1. שירות Agent Runtime מאחזר את קוד המקור מהגרסה שצוינה במאגר Git.
  2. השירות מתקין יחסי תלות מ-requirements_file (אם הם מסופקים).
  3. השירות מפעיל את אפליקציית הנציג באמצעות הערכים שצוינו בפרמטרים entrypoint_module ו-entrypoint_object.

קובצי מקור

כדי לבצע פריסה מקובצי מקור ב-Agent Platform, משתמשים ב-client.agent_engines.create ומספקים את source_packages,‏ entrypoint_module,‏ entrypoint_object ו-class_methods במילון ההגדרות, יחד עם הגדרות אופציונליות אחרות. בשיטה הזו, לא צריך להעביר אובייקט של סוכן או קטגוריה של Cloud Storage.

remote_agent = client.agent_engines.create(
    config={
        "source_packages": source_packages,             # Required.
        "entrypoint_module": entrypoint_module,         # Required.
        "entrypoint_object": entrypoint_object,         # Required.
        "class_methods": class_methods,                 # Required.
        "requirements_file": requirements_file,         # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # Optional.
        "service_account": service_account,             # Optional.
        "min_instances": min_instances,                 # Optional.
        "max_instances": max_instances,                 # Optional.
        "resource_limits": resource_limits,             # Optional.
        "container_concurrency": container_concurrency, # Optional
        "encryption_spec": encryption_spec,             # Optional.
        "agent_framework": agent_framework,             # Optional.
    },
)

הפרמטרים לפריסת מקור מוטבע הם:

  • ‫source_packages (חובה, list[str]): רשימה של נתיבים של קבצים או ספריות מקומיים שייכללו בפריסה. הגודל הכולל של הקבצים והספריות ב-source_packages לא יכול להיות גדול מ-8MB.
  • ‫entrypoint_module (חובה, str): השם מוגדר במלואו של מודול Python שמכיל את נקודת הכניסה של הסוכן (לדוגמה, agent_dir.agent).
  • ‫entrypoint_object (חובה, str): השם של האובייקט שאפשר להתקשר אליו בתוך entrypoint_module שמייצג את אפליקציית הסוכן (לדוגמה, root_agent).

  • ‫class_methods (חובה, list[dict]): רשימה של מילונים שמגדירים את השיטות הגלויות של הסוכן. כל מילון כולל את השדות name (חובה), api_mode (חובה) ו-parameters. מידע נוסף על השיטות של סוכן מותאם אישית זמין במאמר בנושא רשימת פעולות נתמכות.

    לדוגמה:

      "class_methods": [
      {
          "name": "method_name",
          "api_mode": "", # Possible options are: "", "async", "async_stream", "stream", "bidi_stream"
          "parameters": {
              "type": "object",
              "properties": {
                  "param1": {"type": "string", "description": "Description of param1"},
                  "param2": {"type": "integer"}
              },
              "required": ["param1"]
          }
      }
  ]
  ```

  • ‫requirements_file (אופציונלי, str): הנתיב לקובץ דרישות של pip בנתיבים שצוינו ב-source_packages. ברירת המחדל היא requirements.txt בספריית השורש של המקור הארוז.

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

  1. ‫Agent Platform SDK יוצר ארכיון tar.gz של הנתיבים שצוינו ב-source_packages.
  2. הארכיון הזה מוצפן ונשלח ישירות אל Agent Platform API.
  3. שירות Agent Runtime מקבל את הארכיון, מחלץ אותו, מתקין תלויות מ-requirements_file (אם צוין) ומפעיל את אפליקציית הסוכן באמצעות entrypoint_module ו-entrypoint_object שצוינו.

הדוגמה הבאה מראה איך פורסים סוכן מקובצי מקור:

from google.cloud.aiplatform import vertexai

# Example file structure:
# /agent_directory
#     ├── agent.py
#     ├── requirements.txt

# Example agent_directory/agent.py:
# class MyAgent:
#     def ask(self, question: str) -> str:
#         return f"Answer to {question}"
# root_agent = MyAgent()

remote_agent = client.agent_engines.create(
  config={
      "display_name": "My Agent",
      "description": "An agent deployed from a local source.",
      "source_packages": ["agent_directory"],
      "entrypoint_module": "agent_directory.agent",
      "entrypoint_object": "root_agent",
      "requirements_file": "requirements.txt",
      "class_methods": [
          {"name": "ask", "api_mode": "", "parameters": {
              "type": "object",
              "properties": {
                  "question": {"type": "string"}
              },
              "required": ["question"]
          }},
      ],
      # Other optional configs:
      # "env_vars": {...},
      # "service_account": "...",
  }
)

קובץ Docker

כדי לבצע פריסה מ-קובץ Docker ב-Agent Platform, משתמשים בגישה דומה לפריסה מקובצי מקור. השינוי היחיד שצריך לעשות כשמפעילים את הכלי הוא להחליף את entrypoint_module, ‏entrypoint_object ו-(אופציונלית) requirements_file בהגדרות ב-image_spec. הקונטיינר שנבנה מקובץ ה-Dockerfile חייב לעמוד בתנאי החוזה של זמן הריצה.

הדוגמה הבאה מראה איך פורסים סוכן באמצעות קובץ Dockerfile:

from google.cloud.aiplatform import vertexai

# Example file structure:
# /current_directory
#     ├── agent.py
#     ├── main.py
#     ├── requirements.txt
#     ├── Dockerfile

remote_agent = client.agent_engines.create(
    config={
        "source_packages": [
            "agent.py",
            "main.py",
            "requirements.txt",
            "Dockerfile",
        ],
        "image_spec": {},  # tells Agent Runtime to use the Dockerfile
        # Other optional configs
        "display_name": "Dockerfile agent",
    }
)

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

כדי לבצע פריסה מקובץ אימג' של קונטיינר, קודם צריך לפעול לפי הוראות ההגדרה של שימוש בקונטיינר משלכם, ולוודא שמותקנת גרסה של google-cloud-aiplatform שעומדת בדרישות של >=1.144. קובץ אימג' של קונטיינר חייב לעמוד בדרישות של חוזה זמן הריצה. לאחר מכן, מריצים את הקוד הבא:

remote_agent = client.agent_engines.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Other optional configs
        "display_name": "Container image agent",
    },
)

כאשר CONTAINER_IMAGE_URI תואם ל-URI של קובץ אימג' של קונטיינר ב-Artifact Registry (למשל us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag).

זמן האחזור של הפריסה תלוי בזמן הכולל שנדרש להתקנת החבילות. אחרי הפריסה, remote_agent מתאים למופע של local_agent שפועל ב-Agent Platform, ואפשר להריץ עליו שאילתות או למחוק אותו.

האובייקט remote_agent תואם למחלקה AgentEngine שמכילה את הרכיבים הבאים:

  • ‫remote_agent.api_resource עם מידע על הנציג שהופעל. אפשר גם לקרוא לפונקציה remote_agent.operation_schemas() כדי להחזיר את רשימת הפעולות ש-remote_agent תומך בהן. פרטים נוספים זמינים במאמר בנושא פעולות נתמכות.
  • ‫remote_agent.api_client שמאפשרת אינטראקציות סינכרוניות עם שירותים
  • remote_agent.async_api_client שמאפשרת אינטראקציות אסינכרוניות בין שירותים

אופציונלי: קבלת מזהה המשאב של הסוכן

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

remote_agent.api_resource.name

התגובה אמורה להיראות כמו המחרוזת הבאה:

"projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"

איפה

אופציונלי: הצגת הפעולות הנתמכות

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

remote_agent.operation_schemas()

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

אופציונלי: מתן הרשאות לסוכן שנפרס

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

אופציונלי: פריסת סוכנים באמצעות תשתית ארגונית

כדי לפרוס את הסוכן עם סביבה מלאה שכוללת שכבות אבטחה וניהול, מעתיקים את התבניות הבאות של Application Design Center ומבצעים בהן התאמה אישית:

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

מדריך

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

מדריך

שימוש בסוכן עם Agent Platform Runtime.