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

פריסת סוכן

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

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

Developer Connect

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

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

קובצי מקור

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

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

קובץ Docker

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

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

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

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

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

Agent Platform SDK

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

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

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

אם הסוכן משתמש בתבנית ספציפית למסגרת, צריך לציין את גרסת ה-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 הוא קובץ טקסט שעומד בדרישות של פורמט קובץ הדרישות. לדוגמה:
```
  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

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

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

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

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

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

הערה: בזמן שהתכונה הזו בגרסת טרום-השקה, גם אם תגדירו מספר גבוה יותר של מופעים מינימליים, לא תחויבו על זמן שבו הסוכן לא פעיל. התנהלות החיוב הזו עשויה להשתנות בעתיד.
‫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, אפשר לעיין במאמר אופטימיזציה של Agent Runtime והתאמה שלו לשינויים.

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

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

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

.
├── ...
└── 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 משמש רק כשמבצעים פריסה מאובייקט של סוכן.

אם יש חפצים זמניים שמתאימים לתיקייה קיימת בקטגוריה של Cloud Storage, הם יוחלפו. אם צריך, אפשר לציין את תיקיית Cloud Storage עבור פריטי הביניים של ההעלאה. אפשר להגדיר את 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 כשיוצרים את הסוכן. הזהות משויכת למזהה משאב הסוכן של פלטפורמת הסוכנים, והיא לא תלויה במסגרת הסוכנים שבה השתמשתם כדי לפתח את הסוכן:

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 פרטי, תוכלו לציין את קובץ הרשת המצורף וליצור שיתוף 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 של תחום Cloud DNS פרטי.
‫TARGET_PROJECT הוא הפרויקט שמארח את רשת ה-VPC. הוא יכול להיות שונה מהפרויקט Network Attachment.
‫TARGET_NETWORK הוא השם של רשת ה-VPC ב-`TARGET_PROJECT` שאליה נוצר הקישור בין רשתות ה-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 של קומיט).
- ‫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 בספריית הבסיס של המקור הארוז.

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

‫Agent Platform SDK יוצר ארכיון 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 דומה לפריסה מקובצי מקור, רק שבמקום entrypoint_module, entrypoint_object ו-requirements_file משתמשים ב-image_spec בהגדרה. הקונטיינר שנבנה מקובץ ה-Dockerfile חייב לעמוד בדרישות החוזה של זמן הריצה.

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

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

# 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 (בתיקייה המתאימה) כדי להכין את הארטיפקטים.
מזהי ה-URI של Cloud Storage עבור הפריטים הרלוונטיים שנוצרו בתהליך פיתוח מצוינים ב-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

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

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

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

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

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

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

שימוש בסוכן

פריסת סוכן