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

Menyediakan 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

Vertex AI Agent Engine mendukung Antarmuka Private Service Connect dan Peering DNS untuk traffic keluar yang bersifat pribadi dan aman.

Mengapa menggunakan Antarmuka Private Service Connect?

Agen Anda di-deploy di jaringan yang aman dan dikelola Google tanpa akses ke jaringan Virtual Private Cloud (VPC) Anda. Antarmuka PSC membuat jembatan pribadi dan aman ke jaringan Anda, sehingga menjadikannya solusi yang direkomendasikan untuk berinteraksi dengan layanan yang dihosting secara pribadi di seluruh lingkungan VPC, lokal, dan multicloud Anda.

Selain menyediakan akses pribadi, koneksi ini juga diperlukan untuk mengaktifkan akses internet saat menggunakan Kontrol Layanan VPC. Lihat Mengakses Internet Publik.

Cara Kerjanya

Saat Anda mengonfigurasi Antarmuka PSC, Agent Engine akan menyediakan antarmuka di project tenant milik Google tempat agen Anda berjalan. Antarmuka ini terhubung langsung ke Network Attachment di project Anda. Semua traffic antara agen dan VPC Anda berjalan dengan aman dalam jaringan Google, dan tidak pernah melintasi internet publik.

Mengakses Internet Publik

Kemampuan agen untuk mengakses internet publik bergantung pada konfigurasi keamanan project Anda, khususnya apakah Anda menggunakan Kontrol Layanan VPC.

Perilaku Default (Tanpa Kontrol Layanan VPC)
  • Jika Anda mengonfigurasi agen hanya dengan Antarmuka PSC, agen tersebut akan mempertahankan akses internet default-nya. Traffic keluar ini keluar langsung dari lingkungan yang aman dan dikelola Google tempat agen Anda berjalan.
Dengan Kontrol Layanan VPC
  • Jika project Anda adalah bagian dari perimeter Kontrol Layanan VPC, akses internet default agen diblokir oleh perimeter untuk mencegah pemindahan data yang tidak sah. Untuk mengizinkan agen mengakses internet publik dalam skenario ini, Anda harus mengonfigurasi jalur keluar yang aman secara eksplisit yang merutekan traffic melalui VPC Anda. Cara yang direkomendasikan untuk mencapai hal ini adalah dengan menyiapkan server proxy di dalam perimeter VPC Anda dan membuat gateway Cloud NAT untuk mengizinkan VM proxy mengakses internet.

Sebelum memulai

Untuk mengaktifkan konektivitas pribadi bagi agen yang di-deploy menggunakan antarmuka Private Service Connect, Anda perlu menyiapkan jaringan VPC, subnetwork, dan lampiran jaringan di project pengguna Anda.

Persyaratan Rentang IP Subnetwork

Agent Engine merekomendasikan subnetwork /28.

Subnet lampiran jaringan mendukung alamat RFC 1918 dan non-RFC 1918, kecuali subnet 100.64.0.0/10 dan 240.0.0.0/4. Agent Engine hanya dapat terhubung ke rentang alamat IP RFC 1918 yang dapat dirutekan dari jaringan yang ditentukan. Agent Engine tidak dapat menjangkau alamat IP publik yang digunakan secara pribadi atau rentang non-RFC 1918 berikut:

  • 100.64.0.0/10
  • 192.0.0.0/24
  • 192.0.2.0/24
  • 198.18.0.0/15
  • 198.51.100.0/24
  • 203.0.113.0/24
  • 240.0.0.0/4

Lihat Menyiapkan antarmuka Private Service Connect untuk mengetahui detail selengkapnya tentang penyiapan.

Menggunakan dengan VPC Bersama

Anda dapat menggunakan Antarmuka Private Service Connect dengan arsitektur VPC Bersama, yang memungkinkan Anda membuat Agent Engine di Project Layanan sambil menggunakan jaringan dari Project Host pusat.

Saat menyiapkan PSC-I di lingkungan VPC Bersama, buat subnet di Project Host, lalu buat lampiran jaringan di Project Layanan.

Agar Project Layanan dapat menggunakan jaringan Project Host, Anda harus memberikan izin IAM yang sesuai. Agen Layanan Vertex AI dari Project Layanan Anda memerlukan peran Compute Network User (roles/compute.networkUser) di Project Host.

Men-deploy agen dengan Antarmuka Private Service Connect

Setelah lampiran jaringan disiapkan, Anda dapat menentukannya saat membuat instance AgentEngine.

remote_agent = agent_engines.create(
    agent_engine=local_agent,
    psc_interface_config={
      "network_attachment": "NETWORK_ATTACHMENT",
    },
)

di mana

  • NETWORK_ATTACHMENT adalah nama atau jalur lengkap lampiran jaringan yang Anda buat.

Menggunakan Lampiran Jaringan dengan Beberapa Agen

Anda memiliki fleksibilitas untuk memutuskan cara agen Anda membagikan resource jaringan. 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.

Peering DNS

Meskipun Antarmuka Private Service Connect menyediakan jalur jaringan yang aman, Peering DNS menyediakan mekanisme penemuan layanan. Dengan PSC-I, Anda tetap perlu mengetahui alamat IP spesifik layanan di jaringan VPC. Meskipun Anda dapat terhubung ke layanan menggunakan alamat IP internalnya, hal ini tidak direkomendasikan untuk sistem produksi yang IP-nya dapat berubah. Dengan Peering DNS, agen yang di-deploy dapat terhubung ke layanan di jaringan VPC Anda menggunakan nama DNS yang stabil dan mudah dibaca, bukan alamat IP. Peering DNS memungkinkan agen yang di-deploy untuk me-resolve nama DNS menggunakan data dari zona pribadi Cloud DNS di VPC Anda. Lihat Menyiapkan peering DNS pribadi.

Setelah Peering DNS pribadi disiapkan, Anda dapat menentukannya saat membuat instance AgentEngine.

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 yang Anda buat.
  • 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.

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