Men-deploy agen

Untuk men-deploy agen di Vertex AI Agent Engine, gunakan langkah-langkah berikut:

  1. Konfigurasi agen Anda untuk deployment.
  2. Buat instance AgentEngine.
  3. Berikan izin agen yang di-deploy.
  4. Mendapatkan ID resource agen.

Anda juga dapat menggunakan template Agent Starter Pack untuk deployment.

Sebelum memulai

Sebelum men-deploy agen, pastikan Anda telah menyelesaikan tugas berikut:

  1. Menyiapkan lingkungan Anda
  2. Mengembangkan agen.

Mengonfigurasi agen untuk deployment

Anda dapat melakukan konfigurasi opsional berikut:

Menentukan persyaratan paket

Berikan kumpulan paket yang diperlukan oleh agen untuk deployment. Kumpulan paket dapat berupa daftar item yang akan diinstal oleh pip, atau jalur ke file yang mengikuti Format File Persyaratan. Gunakan praktik terbaik berikut:

  1. Sematkan versi paket Anda untuk build yang dapat direproduksi. Paket umum yang perlu diperhatikan mencakup: google-cloud-aiplatform, cloudpickle, langchain, langchain-core, langchain-google-vertexai, dan pydantic.

  2. Minimalkan jumlah dependensi di agen Anda. Hal ini mengurangi jumlah perubahan yang merusak saat memperbarui dependensi dan agen Anda.

Jika agen tidak memiliki dependensi, Anda dapat menyetel requirements ke None:

requirements = None

Jika agen menggunakan template khusus framework, Anda harus menentukan versi SDK yang diimpor (seperti 1.77.0) saat mengembangkan agen.

ADK 

requirements = [
    "google-cloud-aiplatform[agent_engines,adk]",
    # 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

Petunjuk berikut ditujukan untuk Pipeline Kueri LlamaIndex:

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

Anda juga dapat melakukan hal berikut dengan paket requirements:

  • Membatasi atau menyematkan versi paket tertentu (seperti google-cloud-aiplatform):

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

  • Menambahkan paket dan batasan tambahan:

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

  • Menunjuk ke versi paket di cabang atau permintaan pull GitHub:

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

  • Buat daftar persyaratan dalam file (seperti path/to/requirements.txt):

    requirements = "path/to/requirements.txt"

    dengan path/to/requirements.txt adalah file teks yang mengikuti Format File Persyaratan. Contoh:

    google-cloud-aiplatform[agent_engines,adk]
cloudpickle==3.0

Menentukan paket tambahan

Anda dapat menyertakan file atau direktori lokal yang berisi file sumber Python lokal yang diperlukan. Dibandingkan dengan persyaratan paket, hal ini memungkinkan Anda menggunakan utilitas pribadi yang telah Anda kembangkan yang tidak tersedia di PyPI atau GitHub.

Jika agen tidak memerlukan paket tambahan, Anda dapat menyetel extra_packages ke None:

extra_packages = None

Anda juga dapat melakukan hal berikut dengan extra_packages:

  • Sertakan satu file (seperti agents/agent.py):

    extra_packages = ["agents/agent.py"]

  • Sertakan kumpulan file di seluruh direktori (misalnya, agents/):

    extra_packages = ["agents"] # directory that includes agents/agent.py

  • Tentukan biner wheel Python (misalnya, 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

Menentukan variabel lingkungan

Jika ada variabel lingkungan yang bergantung pada agen Anda, Anda dapat menentukannya dalam argumen env_vars=. Jika agen tidak bergantung pada variabel lingkungan apa pun, Anda dapat menyetelnya ke None:

env_vars = None

Untuk menentukan variabel lingkungan, ada beberapa opsi berbeda yang tersedia:

Kamus 

env_vars = {
  "VARIABLE_1": "VALUE_1",
  "VARIABLE_2": "VALUE_2",
}
# These environment variables will become available in Vertex AI Agent Engine
# 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"
#

Untuk mereferensikan secret di Secret Manager dan membuatnya tersedia sebagai variabel lingkungan (misalnya, CLOUD_SQL_CREDENTIALS_SECRET), ikuti terlebih dahulu petunjuk untuk Membuat secret untuk CLOUD_SQL_CREDENTIALS_SECRET di project Anda, sebelum menentukan variabel lingkungan sebagai:

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

di mana

  • SECRET_VERSION_ID adalah ID versi secret.
  • SECRET_ID adalah ID secret.

Dalam kode agen, Anda dapat mereferensikan secret seperti ini:

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)

Daftar 

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"],
#   }

Menentukan kontrol resource yang disesuaikan

Anda dapat menentukan kontrol resource runtime untuk agen, seperti jumlah minimum dan maksimum instance aplikasi, batas resource untuk setiap container, dan serentak untuk setiap container.

  • min_instances: Jumlah minimum instance aplikasi yang harus tetap berjalan setiap saat, dengan rentang [0, 10]. Nilai default adalah 1.

  • max_instances: Jumlah maksimum instance aplikasi yang dapat diluncurkan untuk menangani peningkatan traffic, dengan rentang [1, 1000]. Nilai defaultnya adalah 100. Jika VPC-SC atau PSC-I diaktifkan, rentang yang dapat diterima adalah [1, 100].

  • resource_limits: Batas resource untuk setiap container. Hanya tombol cpu dan memory yang didukung. Nilai defaultnya adalah {"cpu": "4", "memory": "4Gi"}.

    • Satu-satunya nilai yang didukung untuk cpu adalah '1', '2', '4', '6', dan '8'. Untuk informasi selengkapnya, lihat Mengonfigurasi alokasi CPU.

    • Satu-satunya nilai yang didukung untuk memory adalah '1Gi', '2Gi', ... '32Gi'.

    • Untuk CPU yang diperlukan pada nilai memori yang berbeda, lihat Mengonfigurasi batas memori.

  • container_concurrency: Serentak untuk setiap server agen dan container. Nilai yang direkomendasikan adalah 2 * cpu + 1. Nilai defaultnya adalah 9.

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

Menentukan opsi build

Anda dapat menentukan opsi build untuk agen, seperti skrip penginstalan yang akan dijalankan saat membangun image container agen. Hal ini berguna untuk menginstal dependensi sistem (misalnya, gcloud cli, npx) atau penyiapan kustom lainnya. Skrip dijalankan dengan izin root.

Untuk menggunakan skrip penginstalan, buat direktori bernama installation_scripts dan tempatkan skrip shell Anda di dalam direktori tersebut:

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

Selanjutnya, tentukan direktori installation_scripts di extra_packages dan jalur skrip di build_options:

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

Anda dapat menggunakan salah satu skrip penginstalan umum berikut:

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

Tentukan folder Cloud Storage

Artefak penyiapan akan ditimpa jika sesuai dengan folder yang ada di bucket Cloud Storage. Jika perlu, Anda dapat menentukan folder Cloud Storage untuk artefak penyiapan. Anda dapat menyetel gcs_dir_name ke None jika tidak keberatan berpotensi menimpa file di folder default:

gcs_dir_name = None

Untuk menghindari penimpaan file (seperti untuk lingkungan yang berbeda seperti pengembangan, staging, dan produksi), Anda dapat menyiapkan folder yang sesuai, dan menentukan folder untuk melakukan penyiapan artefak di dalamnya:

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

Jika ingin atau perlu menghindari tabrakan, Anda dapat membuat uuid acak:

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

Mengonfigurasi metadata resource

Anda dapat menyetel metadata pada resource ReasoningEngine:

display_name = "Currency Exchange Rate Agent (Staging)"

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

Untuk mengetahui kumpulan lengkap parameter, lihat referensi API.

Mengonfigurasi akun layanan kustom

Anda dapat mengonfigurasi akun layanan kustom sebagai identitas agen yang di-deploy, bukan identitas default.

Untuk melakukannya, tentukan email akun layanan kustom Anda sebagai service_account saat membuat atau memperbarui instance Agent Engine, misalnya:

# Create a new instance
agent_engines.create(
  local_agent=<my-agent>,
  service_account="my-custom-service-account@my-project.",
  ...
)

# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
agent_engines.update(
  resource_name,
  service_account="my-new-custom-service-account@my-project.",
  ...
)

Mengonfigurasi antarmuka Private Service Connect

Jika telah menyiapkan peering DNS dan antarmuka Private Service Connect, Anda dapat menentukan lampiran jaringan dan peering DNS pribadi saat men-deploy agen:

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

di mana

  • NETWORK_ATTACHMENT adalah nama atau jalur lengkap lampiran jaringan Anda.
  • DOMAIN_SUFFIX adalah nama DNS zona Cloud DNS pribadi yang Anda buat saat menyiapkan Peering DNS pribadi.
  • TARGET_PROJECT adalah project yang menghosting jaringan VPC.
  • TARGET_NETWORK adalah nama jaringan VPC.

Anda dapat mengonfigurasi beberapa agen untuk menggunakan lampiran jaringan bersama tunggal atau lampiran jaringan khusus yang unik. Untuk menggunakan lampiran jaringan bersama, berikan lampiran jaringan yang sama di psc_interface_config untuk setiap agen yang Anda buat.

Mengonfigurasi kunci enkripsi yang dikelola pelanggan

Anda dapat menggunakan kunci kustom untuk mengenkripsi data agen Anda saat tidak digunakan. Lihat Kunci enkripsi yang dikelola pelanggan (CMEK) Agent Engine untuk mengetahui detail selengkapnya.

Untuk mengonfigurasi kunci kustom (CMEK) untuk agen, Anda harus memberikan nama resource kunci ke parameter encryption_spec saat membuat instance Agent Engine.

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

remote_agent = agent_engines.create(
    local_agent,
    # ... other parameters
    encryption_spec={"kms_key_name": kms_key_name},
)

Buat instance AgentEngine

Untuk men-deploy agen di Vertex AI, gunakan agent_engines.create untuk meneruskan objek local_agent bersama dengan konfigurasi opsional:

remote_agent = agent_engines.create(
    local_agent,                     # Optional.
    requirements=requirements,       # Optional.
    extra_packages=extra_packages,   # Optional.
    gcs_dir_name=gcs_dir_name,       # Optional.
    display_name=display_name,       # Optional.
    description=description,         # Optional.
    env_vars=env_vars,               # Optional.
    build_options=build_options,     # 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.
)

Deployment memerlukan waktu beberapa menit, dan selama itu langkah-langkah berikut terjadi di latar belakang:

  1. Bundle artefak berikut dibuat secara lokal:

    • *.pkl file pickle yang sesuai dengan local_agent.
    • requirements.txt file teks yang berisi persyaratan paket.
    • dependencies.tar.gz file tar yang berisi paket tambahan.

  2. Bundle diupload ke Cloud Storage (di folder yang sesuai) untuk penyiapan artefak.

  3. URI Cloud Storage untuk artefak masing-masing ditentukan dalam PackageSpec.

  4. Layanan Vertex AI Agent Engine menerima permintaan, membangun container, dan memulai server HTTP di backend.

Latensi deployment bergantung pada total waktu yang diperlukan untuk menginstal paket yang diperlukan. Setelah di-deploy, remote_agent sesuai dengan instance local_agent yang berjalan di Vertex AI dan dapat dikueri atau dihapus. Agent ini terpisah dari instance lokal agent.

Memberikan izin agen yang di-deploy

Jika agen yang di-deploy perlu diberi izin tambahan, ikuti petunjuk di Menyiapkan identitas dan izin untuk agen Anda.

Jika Anda menentukan secret sebagai variabel lingkungan, Anda harus memberikan izin berikut:

  • Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)

Mendapatkan ID resource agen

Setiap agen yang di-deploy memiliki ID unik. Anda dapat menjalankan perintah berikut untuk mendapatkan ID resource_name untuk agen yang di-deploy:

remote_agent.resource_name

Responsnya akan terlihat seperti string berikut:

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

di mana

  • PROJECT_ID adalah Google Cloud project ID tempat agen yang di-deploy berjalan.

  • LOCATION adalah region tempat agen yang di-deploy berjalan.

  • RESOURCE_ID adalah ID agen yang di-deploy sebagai reasoningEngine resource.

Langkah berikutnya