Men-deploy agen

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

1. Selesaikan prasyarat.
2. (Opsional) Konfigurasi agen Anda untuk deployment.
3. Buat instance AgentEngine.
4. (Opsional) Dapatkan ID resource agen.
5. (Opsional) Mencantumkan operasi yang didukung.
6. (Opsional) Beri izin agen yang di-deploy.

Anda juga dapat menggunakan template Agent Starter Pack untuk deployment.

Catatan: Deployment Vertex AI Agent Engine hanya mendukung Python.

Prasyarat

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

1. Menyiapkan lingkungan Anda
2. Mengembangkan agen.

(Opsional) Mengonfigurasi agen untuk deployment

Anda dapat membuat konfigurasi opsional berikut untuk agen:

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 dipantau 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 menyebabkan gangguan 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.112.0) saat mengembangkan agen.

ADK

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

A2A

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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

Pratinjau

Fitur ini tunduk kepada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

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.112.0",
    ]
    

• Menambahkan paket dan batasan tambahan:

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

• Pertahankan 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 dikembangkan yang tidak tersedia di PyPI atau GitHub.

Jika agen tidak memerlukan paket tambahan, Anda dapat menetapkan 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

Peringatan: Anda tidak boleh menetapkan variabel lingkungan berikut: GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_QUOTA_PROJECT, GOOGLE_CLOUD_LOCATION, PORT, K_SERVICE, K_REVISION, K_CONFIGURATION, dan GOOGLE_APPLICATION_CREDENTIALS. Selain itu, Anda harus menghindari awalan GOOGLE_CLOUD_AGENT_ENGINE untuk menghindari konflik penamaan dengan variabel lingkungan Vertex AI Agent Engine.

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), pertama-tama ikuti 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.

Catatan: Anda hanya dapat mereferensikan secret (dan versinya) yang dikelola dalam project yang sama dengan agen yang di-deploy.

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

Catatan: Opsi ini tidak mendukung integrasi Secret Manager. Jika perlu menentukan secret terkelola, Anda harus menentukan variabel lingkungan sebagai kamus.

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

Anda juga perlu mengikuti petunjuk di Menyiapkan identitas dan izin untuk agen Anda untuk memberikan izin Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) kepada agen Anda.

Menentukan kontrol resource yang disesuaikan

Pratinjau

Fitur ini tunduk kepada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

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

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

  Catatan: Selama fitur ini dalam Pratinjau, meskipun Anda mengonfigurasi jumlah minimum instance yang lebih tinggi, Anda tidak akan ditagih untuk waktu saat agen tidak aktif. Perilaku penagihan ini dapat berubah di masa mendatang.

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

  • Nilai yang didukung untuk cpu hanyalah 1, 2, 4, 6, dan 8. Untuk mengetahui 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 = client.agent_engines.create(
    agent=local_agent,
    config={
        "min_instances": 1,
        "max_instances": 10,
        "resource_limits": {"cpu": "4", "memory": "8Gi"},
        "container_concurrency": 9,
        # ... other configs
    }
)

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:

.
├── ...
└── 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 Anda tidak keberatan file di folder default berpotensi ditimpa:

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 staging 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())

Tentukan nama tampilan

Anda dapat menyetel nama tampilan untuk resource ReasoningEngine:

display_name = "Currency Exchange Rate Agent (Staging)"

Menentukan deskripsi

Anda dapat menyetel deskripsi resource 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.
"""

Tentukan label

Anda dapat menetapkan label resource ReasoningEngine sebagai kamus pasangan string nilai kunci. Berikut adalah contohnya:

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

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
client.agent_engines.create(
    agent=local_agent,
    config={
        "service_account": "[e-mail]",
        # ...
    },
)

# Update an existing instance
resource_name = "projects/{project_id}/locations/{location}/reasoningEngines/{reasoning_engine_id}"
client.agent_engines.update(
    name=resource_name,
    agent=local_agent,
    config={
        "service_account": "[e-mail]",
        # ...
    },
)

Catatan: Tentukan hanya email akun layanan, bukan URI resource lengkap, seperti projects/{project_id}/serviceAccounts/{service_account_email}.

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 = client.agent_engines.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",
                },
            ],
        },
    },
)

di mana

• NETWORK_ATTACHMENT adalah nama atau jalur lengkap lampiran jaringan Anda. Jika lampiran jaringan dibuat di project (seperti project host VPC Bersama) yang berbeda dengan tempat Anda menggunakan Agent Engine, Anda perlu meneruskan jalur lengkap lampiran jaringan.
• 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. Project ini dapat berbeda dengan project Network Attachment.
• 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 = client.agent_engines.create(
    agent=local_agent,
    config={
        "encryption_spec": {"kms_key_name": kms_key_name},
        # ... other parameters
    },
)

Buat instance AgentEngine

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

remote_agent = client.agent_engines.create(
    agent=local_agent,                                  # Optional.
    config={
        "requirements": requirements,                   # Optional.
        "extra_packages": extra_packages,               # Optional.
        "gcs_dir_name": gcs_dir_name,                   # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "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 waktu tersebut, 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.

Objek remote_agent sesuai dengan class AgentEngine yang berisi atribut berikut:

• remote_agent.api_resource dengan informasi tentang agen yang di-deploy. Anda juga dapat memanggil agent.operation_schemas() untuk menampilkan daftar operasi yang didukung agen. Lihat Mencantumkan operasi yang didukung untuk mengetahui detailnya.
• remote_agent.api_client yang memungkinkan interaksi layanan sinkron.
• remote_agent.async_api_client yang memungkinkan interaksi layanan asinkron.

(Opsional) Dapatkan ID resource agen

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

remote_agent.api_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 resource reasoningEngine.

(Opsional) Mencantumkan operasi yang didukung

Setiap agen yang di-deploy memiliki daftar operasi yang didukung. Anda dapat menjalankan perintah berikut untuk mendapatkan daftar operasi yang didukung oleh agen yang di-deploy:

remote_agent.operation_schemas()

Skema untuk setiap operasi adalah kamus yang mendokumentasikan informasi metode untuk agen yang dapat Anda panggil. Kumpulan operasi yang didukung bergantung pada framework yang Anda gunakan untuk mengembangkan agen:

• Agent Development Kit
• Agent2Agent
• LangChain
• LangGraph
• AG2
• LlamaIndex
• Custom

(Opsional) Berikan izin agen yang di-deploy

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

Langkah berikutnya

• Gunakan agen.
• Mengelola agen yang di-deploy.
• Memecahkan masalah deployment agen.
• Dapatkan dukungan.