Men-deploy 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 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.112.0) saat mengembangkan agen.

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

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

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

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

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

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

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

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

env_vars = {
  # ... (other environment variables and their values)
  "CLOUD_SQL_CREDENTIALS_SECRET": {"secret": SECRET_ID, "version": SECRET_VERSION_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"],
#   }

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

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.

• 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:

#!/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

#!/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

#!/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())

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 set 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
client.agent_engines.create(
    agent=local_agent,
    config={
        "service_account": "my-custom-service-account@my-project.",
        # ...
    },
)

# 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": "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 = 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.
• 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
    },
)