‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

פריסת סוכן

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

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

Developer Connect

מומלץ לפרויקטים שמנוהלים במאגר Git שמקושר דרך Developer Connect. השיטה הזו מייעלת את פריסת הנציגים ישירות מקוד המקור, ותומכת באופן מובנה בניהול גרסאות, בשיתוף פעולה בצוות ובצינורות עיבוד נתונים של CI/CD. לפני שמשתמשים בשיטה הזו, צריך להגדיר את הקישור למאגר Git לפי ההוראות במאמר הגדרת קישור למאגר Git ב-Developer Connect.

אפשר להשתמש בשיטת הפריסה הזו רק עם Python.

קובצי מקור

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

אפשר להשתמש בשיטת הפריסה הזו רק עם Python.

קובץ Docker

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

אפשר להשתמש בשיטת הפריסה הזו בכל שפה. הדוגמאות בדף הזה הן ב-Python.

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

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

אפשר להשתמש בשיטת הפריסה הזו בכל שפה. הדוגמאות בדף הזה הן ב-Python.

Agent Platform SDK

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

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

השלמת הדרישות המוקדמות
אופציונלי: הגדרת הנציג לפריסה
יצירת מכונה של Gemini Enterprise Agent Platform
אופציונלי: קבלת מזהה המשאב של הנציג
אופציונלי: רשימת הפעולות הנתמכות
אופציונלי: מתן הרשאות לסוכן שנפרס

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

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

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

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

הגדרת דרישות החבילה

הערה: בפריסות מקובצי מקור, אין צורך להשתמש בפרמטר requirements. במקום זאת, צריך לכלול קובץ requirements.txt ישירות בחבילת קוד המקור. אפשר לציין את הנתיב לקובץ הזה בפרמטר requirements_file כשיוצרים את המכונה של Agent Platform.

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

הצמדת גרסאות החבילה כדי ליצור גרסאות build שניתן לשחזר. חבילות נפוצות שכדאי לעקוב אחריהן: google-cloud-aiplatform, cloudpickle, langchain, langchain-core, langchain-google-vertexai ו-pydantic.
צמצמו את מספר יחסי התלות בנציג. כך מצמצמים את מספר שינויי התוכנה שעלולים לגרום לכשל כשמעדכנים את יחסי התלות ואת הסוכן.

אם לנציג אין יחסי תלות, אפשר להגדיר את requirements לערך None:

requirements = None

אם הנציג משתמש בתבנית ספציפית ל-framework, צריך לציין את גרסת ה-SDK שיובאה (למשל 1.112.0) כשמפתחים את הנציג.

ADK

requirements = [
    "google-cloud-aiplatform[agent_engines,adk]",
    # any other dependencies
]

A2A

requirements = [
    "google-cloud-aiplatform[agent_engines]",
    "google-adk[a2a]",
    # any other dependencies
]

LangChain

requirements = [
    "google-cloud-aiplatform[agent_engines,langchain]",
    # any other dependencies
]

LangGraph

requirements = [
    "google-cloud-aiplatform[agent_engines,langgraph]",
    # any other dependencies
]

AG2

requirements = [
    "google-cloud-aiplatform[agent_engines,ag2]",
    # any other dependencies
]

LlamaIndex

ההוראות הבאות מיועדות ל-LlamaIndex Query Pipeline:

requirements = [
    "google-cloud-aiplatform[agent_engines,llama_index]",
    # any other dependencies
]

אתם יכולים גם לבצע את הפעולות הבאות בחבילה requirements:

מגדירים גבול עליון או מצמידים את הגרסה של חבילה נתונה (כמו google-cloud-aiplatform):

  requirements = [
      # See https://pypi.org/project/google-cloud-aiplatform for the latest version.
      "google-cloud-aiplatform[agent_engines,adk]==1.112.0",
  ]

הוספת חבילות ואילוצים:

  requirements = [
      "google-cloud-aiplatform[agent_engines,adk]==1.112.0",
      "cloudpickle==3.0", # new
  ]

מצביעים על גרסת החבילה בהסתעפות או בבקשת משיכה ב-GitHub:

  requirements = [
      "google-cloud-aiplatform[agent_engines,adk] @ git+https://github.com/googleapis/python-aiplatform.git@BRANCH_NAME", # new
  ]

שומרים את רשימת הדרישות בקובץ (למשל path/to/requirements.txt):
```
  requirements = "path/to/requirements.txt"
  
```
path/to/requirements.txt הוא קובץ טקסט בפורמט Requirements File Format. לדוגמה:
```
  google-cloud-aiplatform[agent_engines,adk]
  cloudpickle==3.0
  
```

הגדרת חבילות נוספות

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

אפשר לכלול קבצים מקומיים או ספריות שמכילות קובצי מקור מקומיים נדרשים של Python. בהשוואה לדרישות החבילה, כך אתם יכולים להשתמש בכלי שירות פרטיים שפיתחתם, שלא זמינים ב-PyPI או ב-GitHub.

אם לא נדרשות חבילות נוספות לסוכן, אפשר להגדיר את extra_packages ל-None:

extra_packages = None

אתם יכולים גם לבצע את הפעולות הבאות באמצעות extra_packages:

הכללת קובץ אחד (למשל agents/agent.py):
```
  extra_packages = ["agents/agent.py"]
  
```
כוללים את קבוצת הקבצים בספרייה שלמה (לדוגמה, agents/):
```
  extra_packages = ["agents"] # directory that includes agents/agent.py
  
```

מציינים קבצים בינאריים של Python wheel (לדוגמה, path/to/python_package.whl):

  requirements = [
      "google-cloud-aiplatform[agent_engines,adk]",
      "cloudpickle==3.0",
      "python_package.whl",  # install from the whl file that was uploaded
  ]
  extra_packages = ["path/to/python_package.whl"]  # bundle the whl file for uploading

הגדרה של משתני סביבה

אם יש משתני סביבה שהסוכן תלוי בהם, אפשר לציין אותם בארגומנט env_vars=. אם הסוכן לא תלוי במשתני סביבה, אפשר להגדיר אותו ל-None:

env_vars = None

אם אתם משתמשים בסודות כמשתני סביבה עם סוכן שמוגדר להשתמש בזהות הסוכן, תנו את ההרשאה secretmanager.versions.access (שכלולה בתפקיד roles/secretmanager.secretAccessor) לסוכן השירות של פלטפורמת הסוכנים, בפורמט הבא:

service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com

זהות הסוכן שהגדרתם משמשת בזמן הריצה, אבל סוכן השירות של Agent Platform משמש לאחזור סודות במהלך הפריסה. ההרשאה שנוספה מאפשרת לסוכן השירות לאחזר את ערכי הסודות מ-Secret Manager במהלך תהליך הפריסה.

אזהרה: אל תגדירו את משתני הסביבה הבאים: GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_QUOTA_PROJECT, GOOGLE_CLOUD_LOCATION, PORT, K_SERVICE, K_REVISION, K_CONFIGURATION ו-GOOGLE_APPLICATION_CREDENTIALS. בנוסף, כדאי להימנע מהתחילית GOOGLE_CLOUD_AGENT_ENGINE כדי למנוע התנגשויות בשמות עם משתני הסביבה של Agent Runtime.

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

מילון

env_vars = {
  "VARIABLE_1": "VALUE_1",
  "VARIABLE_2": "VALUE_2",
}
# These environment variables will become available in Agent Platform
# through `os.environ`, e.g.
#
#   import os
#   os.environ["VARIABLE_1"] # will have the value "VALUE_1"
#
# and
#
#   os.environ["VARIABLE_2"] # will have the value "VALUE_2"
#

כדי להפנות לסוד ב-Secret Manager ולהפוך אותו לזמין כמשתנה סביבה (לדוגמה, CLOUD_SQL_CREDENTIALS_SECRET), קודם צריך לפעול לפי ההוראות ליצירת סוד בשביל CLOUD_SQL_CREDENTIALS_SECRET בפרויקט, ואז לציין את משתני הסביבה באופן הבא:

env_vars = {
  # ... (other environment variables and their values)
  "CLOUD_SQL_CREDENTIALS_SECRET": {"secret": SECRET_ID, "version": SECRET_VERSION_ID},
}

כאשר

‫SECRET_VERSION_ID הוא המזהה של גרסת הסוד.
‫SECRET_ID הוא המזהה של הסוד.

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

secret = os.environ.get("CLOUD_SQL_CREDENTIALS_SECRET")
if secret:
  # Secrets are stored as strings, so use json.loads to parse JSON
  # payloads.
  return json.loads(secret)

רשימה

env_vars = ["VARIABLE_1", "VARIABLE_2"]
# This corresponds to the following code snippet:
#
#   import os
#
#   env_vars = {
#     "VARIABLE_1": os.environ["VARIABLE_1"],
#     "VARIABLE_2": os.environ["VARIABLE_2"],
#   }

צריך גם לפעול לפי ההוראות במאמר הגדרת הזהות וההרשאות של הנציג כדי לתת לנציג את ההרשאה Secret Manager Secret Accessor (roles/secretmanager.secretAccessor).

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

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

‫min_instances: המספר המינימלי של מכונות של האפליקציה שצריך להפעיל כל הזמן, בטווח של [0, 75]. ערך ברירת המחדל הוא 1.

הערה: כשהתכונה הזו נמצאת בגרסת טרום-השקה (Preview), גם אם מגדירים מספר גבוה יותר של מכונות מינימליות, לא תחויבו על הזמן שבו הנציג לא פעיל. התנהגות החיוב הזו עשויה להשתנות בעתיד.
‫max_instances: המספר המקסימלי של מכונות של האפליקציה שאפשר להפעיל כדי לטפל בתנועה מוגברת, בטווח של [1, 1000]. ערך ברירת המחדל הוא 100. אם VPC-SC או PSC-I מופעלים, הטווח הקביל הוא [1, 100] לכל משאב של Agent Platform.
‫resource_limits: מגבלות המשאבים לכל קונטיינר. יש תמיכה רק במפתחות cpu ו-memory. ערך ברירת המחדל הוא {"cpu": "4", "memory": "4Gi"}.
- הערכים הנתמכים היחידים עבור cpu הם 1, ‏ 2, ‏ 4, ‏ 6 ו-8. מידע נוסף מופיע במאמר הגדרת הקצאת המעבד (CPU).
- הערכים הנתמכים היחידים עבור memory הם 1Gi, ‏ 2Gi,‏ … 32Gi.
- במאמר הגדרת מגבלות זיכרון מפורטות דרישות המעבד (CPU) לערכי זיכרון שונים.
‫container_concurrency: מספר הפעולות בו-זמנית בכל קונטיינר ובכל שרת של סוכן. הערך המומלץ הוא 2 * cpu + 1. ערך ברירת המחדל הוא 9.

remote_agent = client.runtimes.create(
    agent=local_agent,
    config={
        "min_instances": 1,
        "max_instances": 10,
        "resource_limits": {"cpu": "4", "memory": "8Gi"},
        "container_concurrency": 9,
        # ... other configs
    }
)

במאמר אופטימיזציה ושינוי קנה המידה של Agent Runtime מפורטות שיטות מומלצות לאופטימיזציה של משאבי זמן הריצה.

הגדרת אפשרויות הבילד

אתם יכולים לציין אפשרויות build לסוכן, כמו סקריפטים של התקנה שיופעלו כשיוצרים את קובץ האימג' של הקונטיינר של הסוכן. האפשרות הזו שימושית להתקנת יחסי תלות של המערכת (לדוגמה, gcloud cli, ‏ npx) או הגדרות אישיות אחרות. הסקריפטים מופעלים עם הרשאות ברמת הבסיס (root).

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

.
├── ...
└── installation_scripts/
    └── install.sh

אחר כך מציינים את הספרייה installation_scripts ב-extra_packages ואת נתיבי הסקריפטים ב-build_options:

extra_packages = [..., "installation_scripts/install.sh"]
build_options = {"installation_scripts": ["installation_scripts/install.sh"]}

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

install_npx.sh

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

echo "--- Installing System-Wide Node.js v20.x ---"

# 1. Install prerequisites
apt-get update
apt-get install -y ca-certificates curl gnupg

# 2. Add the NodeSource repository GPG key
mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

# 3. Add the NodeSource repository for Node.js v20
NODE_MAJOR=20
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

# 4. Update package lists again and install Node.js
apt-get update
apt-get install nodejs -y

echo "--- System-wide Node.js installation complete ---"
echo "Verifying versions:"

# These commands will now work for ANY user because node and npx
# are installed in /usr/bin/ which is in everyone's default PATH.
node -v
npm -v
npx -v

install_uvx.sh

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

echo "Starting setup..."

# Install uv
apt-get update
apt-get install -y curl
curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR="/usr/local/bin" sh

# These commands will now work for ANY user because uv and uvx
# are installed in /usr/local/bin/ which is in everyone's default PATH.
uv --version
uvx --version

install_gcloud_cli.sh

#!/bin/bash

# Exit immediately if a command exits with a non-zero status.
set -e

apt-get install -y curl gpg
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
apt-get update -y && apt-get install google-cloud-cli -y

gcloud --version

הגדרת מסגרת הסוכן

אתם יכולים לציין את מסגרת הסוכן שבה הסוכן שלכם משתמש:

agent_framework = "google-adk"

אלה הערכים הנתמכים:

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

הגדרת תיקייה ב-Cloud Storage

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

אם פריטי ה-Staging תואמים לתיקייה קיימת בקטגוריה של Cloud Storage, הם יוחלפו. במקרה הצורך, אפשר לציין את התיקייה ב-Cloud Storage שבה יישמרו פריטי ה-staging. אם לא אכפת לכם שהקבצים בתיקיית ברירת המחדל יוחלפו, אתם יכולים להגדיר את gcs_dir_name לערך None:

gcs_dir_name = None

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

gcs_dir_name = "dev" # or "staging" or "prod"

אם אתם רוצים או צריכים להימנע מהתנגשויות, אתם יכולים ליצור uuid אקראי:

import uuid
gcs_dir_name = str(uuid.uuid4())

הגדרת השם לתצוגה

אפשר להגדיר את השם המוצג של המשאב ReasoningEngine:

display_name = "Currency Exchange Rate Agent (Staging)"

הגדרת התיאור

אפשר להגדיר את התיאור של המשאב ReasoningEngine:

description = """
An agent that has access to tools for looking up the exchange rate.

If you run into any issues, please contact the dev team.
"""

הגדרת התוויות

אפשר להגדיר את התוויות של המשאב ReasoningEngine כמילון של צמדי מפתח/ערך של מחרוזות. לדוגמה:

labels = {"author": "username", "version": "latest"}

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

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

identity_type=AGENT_IDENTITY

מידע נוסף זמין במאמר יצירת נציג עם זהות נציג.

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

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

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

# Create a new instance
client.runtimes.create(
    agent=local_agent,
    config={
        "service_account": "my-custom-service-account@my-project.iam.gserviceaccount.com",
        # ...
    },
)

# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
client.runtimes.update(
    name=resource_name,
    agent=local_agent,
    config={
        "service_account": "my-new-custom-service-account@my-project.iam.gserviceaccount.com",
        # ...
    },
)

הערה: צריך לציין רק את כתובת האימייל של חשבון השירות, ולא את ה-URI המלא של המשאב, כמו projects/{project_id}/serviceAccounts/{service_account_email}.

הגדרת ממשק Private Service Connect

אם הגדרתם ממשק Private Service Connect ותחום DNS פרטי, אתם יכולים לציין את מחבר הרשת וליצור קישור בין רשתות שכנות (peering) ב-DNS פרטי בזמן פריסת הנציג:

remote_agent = client.runtimes.create(
    agent=local_agent,
    config={
        "psc_interface_config": {
            "network_attachment": "NETWORK_ATTACHMENT",
            "dns_peering_configs": [
                {
                    "domain": "DOMAIN_SUFFIX",
                    "target_project": "TARGET_PROJECT",
                    "target_network": "TARGET_NETWORK",
                },
            ],
        },
    },
)

כאשר

‫NETWORK_ATTACHMENT הוא השם או הנתיב המלא של חיבור הרשת. אם מחבר הרשת נוצר בפרויקט (כמו פרויקט מארח של VPC משותף) שונה מהפרויקט שבו אתם משתמשים ב-Agent Platform, אתם צריכים להעביר את הנתיב המלא של מחבר הרשת.
‫DOMAIN_SUFFIX הוא שם ה-DNS של תחום ה-DNS הפרטי ב-Cloud.
‫TARGET_PROJECT הוא הפרויקט שמארח את רשת ה-VPC. הוא יכול להיות שונה מהפרויקט של חיבור הרשת.
‫TARGET_NETWORK הוא השם של רשת ה-VPC ב-`TARGET_PROJECT` שאליה נוצר הקישור בין רשתות שכנות (peering) ב-DNS.

אתם יכולים להגדיר כמה סוכנים שישתמשו בחיבור רשת אחד משותף או בחיבורי רשת ייחודיים וייעודיים. כדי להשתמש במחבר רשת משותף, צריך לציין את אותו מחבר רשת ב-psc_interface_config לכל סוכן שיוצרים.

הגדרת מפתחות הצפנה בניהול הלקוח

אתם יכולים להשתמש במפתח בהתאמה אישית כדי להצפין את הנתונים של הנציג במצב מנוחה. פרטים נוספים זמינים במאמר מפתחות הצפנה בניהול הלקוח (CMEK) ב-Agent Engine.

כדי להגדיר את המפתח המותאם אישית (CMEK) לנציג, צריך לספק את שם המשאב של המפתח לפרמטר encryption_spec כשיוצרים את המכונה של Agent Platform.

# The fully qualified key name
kms_key_name = "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"

remote_agent = client.runtimes.create(
    agent=local_agent,
    config={
        "encryption_spec": {"kms_key_name": kms_key_name},
        # ... other parameters
    },
)

הגדרת קישור למאגר Git ב-Developer Connect

כדי לפרוס ממאגר Git באמצעות Developer Connect, פועלים לפי המסמכים של Developer Connect כדי ליצור חיבור ולקשר למאגר הספציפי. שם המשאב של הקישור משמש כ-git_repository_link במהלך הפריסה, והוא בפורמט הבא: projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID.

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

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

Developer Connect

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

אפשר להשתמש בשיטת הפריסה הזו רק עם Python.

remote_agent = client.runtimes.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 של commit).
- ‫dir (str): תיקיית השורש של קוד הסוכן במאגר.
‫entrypoint_module (str): השם של מודול Python שמכיל את נקודת הכניסה של הסוכן, ביחס לספרייה שצוינה ב-developer_connect_source.dir.
‫entrypoint_object (str): השם של האובייקט שניתן לקרוא לו בתוך entrypoint_module שמייצג את אפליקציית הנציג (לדוגמה, root_agent).
‫requirements_file (str): אופציונלי: הנתיב לקובץ דרישות של pip ביחס לשורש המקור. ברירת המחדל היא requirements.txt.

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

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

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

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

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

קובצי מקור

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

אפשר להשתמש בשיטת הפריסה הזו רק עם Python.

# 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.runtimes.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": "",  # Options: "", "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 בתיקיית השורש של המקור הארוז.

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

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

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

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

קובץ Docker

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

אפשר להשתמש בשיטת הפריסה הזו בכל שפה. הדוגמה בקטע הזה משתמשת ב-Python.

הדוגמה הבאה היא של פריסת סוכן באמצעות קובץ Docker:

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

remote_agent = client.runtimes.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",
    }
)

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

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

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

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

אפשר להשתמש בשיטת הפריסה הזו בכל שפה. הדוגמה בקטע הזה משתמשת ב-Python.

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

remote_agent = client.runtimes.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 תואם למחלקה AgentRuntime שמכילה את הפרטים הבאים:

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

Agent Platform SDK

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

remote_agent = client.runtimes.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.
    },
)

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

חבילה של פריטי המידע שנוצרו באופן מקומי:
- ‫*.pkl קובץ pickle שתואם ל-local_agent.
- ‫requirements.txt קובץ טקסט שמכיל את הדרישות של החבילה.
- ‫dependencies.tar.gz קובץ tar שמכיל חבילות נוספות.
החבילה מועלית ל-Cloud Storage (בתיקייה המתאימה) כדי להכין את פריטי המידע שנוצרו בתהליך הפיתוח (Artifacts).
מזהי ה-URI של Cloud Storage לפריטי המידע שנוצרו בתהליך הפיתוח (Artifacts) מצוינים ב-PackageSpec.
שירות Agent Runtime מקבל את הבקשה, יוצר קונטיינרים ומפעיל שרתי HTTP בקצה העורפי.

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

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"

כאשר

‫PROJECT_ID הוא Google Cloud מזהה הפרויקט שבו פועל הסוכן שנפרס.
‫LOCATION הוא האזור שבו הנציג שנפרס פועל.
‫RESOURCE_ID הוא המזהה של הנציג שנפרס כמשאב reasoningEngine.

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

לכל נציג פרוס יש רשימה של פעולות נתמכות. אפשר להשתמש ב-AgentRuntime.operation_schemas כדי לקבל את רשימת הפעולות שנתמכות על ידי הנציג שנפרס:

remote_agent.operation_schemas()

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

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

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

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

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

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

מדריך

ניהול הסוכנים שנפרסו

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

מדריך

שימוש בסוכן

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

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

Developer Connect

קובצי מקור

קובץ Docker

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

Agent Platform SDK

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

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

הגדרת דרישות החבילה

ADK

A2A

LangChain

LangGraph

AG2

LlamaIndex

הגדרת חבילות נוספות

הגדרה של משתני סביבה

מילון

רשימה

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

הגדרת אפשרויות הבילד

install_npx.sh

install_uvx.sh

install_gcloud_cli.sh

הגדרת מסגרת הסוכן

הגדרת תיקייה ב-Cloud Storage

הגדרת השם לתצוגה

הגדרת התיאור

הגדרת התוויות

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

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

הגדרת ממשק Private Service Connect

הגדרת מפתחות הצפנה בניהול הלקוח

הגדרת קישור למאגר Git ב-Developer Connect

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

Developer Connect

קובצי מקור

קובץ Docker

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

Agent Platform SDK

אופציונלי: קבלת מזהה המשאב של הנציג

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

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

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

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

ניהול הסוכנים שנפרסו

שימוש בסוכן

פריסת סוכן