Men-deploy agen

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

  1. Konfigurasikan agen Anda untuk deployment. Anda dapat membuat konfigurasi opsional berikut:
  2. Buat instance AgentEngine.
  3. Berikan izin agen yang di-deploy.
  4. Mendapatkan ID resource agen.

Anda juga dapat menggunakan template Paket Awal Agen untuk deployment.

Sebelum memulai

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

  1. Menyiapkan lingkungan Anda
  2. Mengembangkan agen.

(Opsional) Menentukan persyaratan paket

Berikan kumpulan paket yang diperlukan oleh agen untuk deployment. Kumpulan paket dapat merupakan daftar item yang akan diinstal oleh pip, atau jalur ke file yang mengikuti Format File Persyaratan.

Jika agen tidak memiliki dependensi, Anda dapat menetapkan 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
]

(Opsional) Batasan versi

Untuk menetapkan batas atas atau menyematkan versi paket tertentu (seperti google-cloud-aiplatform), tentukan hal berikut:

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

Anda dapat menambahkan paket dan batasan tambahan ke daftar:

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

(Opsional) Menentukan cabang pengembangan

Anda dapat mengarahkan ke versi paket yang ada di cabang GitHub atau permintaan pull. Contoh:

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

(Opsional) Menentukan format file persyaratan

Anda dapat mempertahankan 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

(Opsional) 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 dan tidak tersedia di PyPI atau GitHub.

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

extra_packages = None

(Opsional) Menentukan file dan direktori

Untuk menyertakan satu file (seperti agents/agent.py), tambahkan ke daftar extra_packages:

extra_packages = ["agents/agent.py"]

Untuk menyertakan kumpulan file di seluruh direktori (misalnya, agents/), tentukan direktori:

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

(Opsional) Menentukan biner roda

Anda dapat menentukan biner wheel Python (misalnya, path/to/python_package.whl) di persyaratan paket:

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

(Opsional) Menentukan variabel lingkungan

Jika ada variabel lingkungan yang menjadi dependensi agen, 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 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 petunjuk untuk Membuat secret untuk CLOUD_SQL_CREDENTIALS_SECRET di project Anda terlebih dahulu, 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.

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

(Opsional) Menentukan direktori Cloud Storage

Artefak staging akan ditimpa jika sesuai dengan sub-bucket yang ada (folder di bucket Cloud Storage). Jika perlu, Anda dapat menentukan subbucket untuk artefak staging. Anda dapat menetapkan gcs_dir_name ke None jika tidak keberatan untuk menimpa file di sub-bucket default:

gcs_dir_name = None

Untuk menghindari file ditimpa (seperti untuk lingkungan yang berbeda seperti pengembangan, staging, dan produksi), Anda dapat menyiapkan sub-bucket yang sesuai, dan menentukan sub-bucket untuk melakukan staging artefak:

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

Jika ingin atau perlu menghindari konflik, Anda dapat membuat UUID acak:

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

(Opsional) Mengonfigurasi metadata resource

Anda dapat menetapkan metadata pada resource ReasoningEngine yang dibuat di Vertex AI:

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.

Membuat instance AgentEngine

Untuk men-deploy agen di Vertex AI, gunakan agent_engines.create dan teruskan objek sebagai parameter:

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

Deployment memerlukan waktu beberapa menit, selama proses tersebut, langkah-langkah berikut akan terjadi di latar belakang:

  1. Paket 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. Paket diupload ke Cloud Storage (di bagian sub-bucket yang sesuai) untuk melakukan staging artefak.

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

  4. Layanan Vertex AI Agent Engine menerima permintaan, membuat penampung, dan mengaktifkan 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. Instance ini terpisah dari instance lokal agen.

(Opsional) Berikan izin agen yang di-deploy

Jika agen yang di-deploy perlu diberi izin tambahan, Anda dapat mengikuti petunjuk di Menyiapkan izin agen layanan.

Jika telah 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 resource reasoningEngine.

Men-deploy dalam produksi dengan Paket Awal Agen

Paket Awal Agen adalah kumpulan template agen AI generatif siap produksi yang dibuat untuk Vertex AI Agent Engine. Alat ini mempercepat deployment dengan menyediakan:

  • Template Agen Siap Pakai: ReAct, RAG, multi-agen, dan lainnya.
  • Interactive Playground: Menguji dan berinteraksi dengan agen Anda.
  • Infrastruktur Otomatis: Menggunakan Terraform untuk pengelolaan resource yang disederhanakan.
  • Pipeline CI/CD: Alur kerja deployment otomatis yang memanfaatkan Cloud Build.
  • Kemampuan observasi: Mencakup dukungan bawaan untuk Cloud Trace dan Cloud Logging.

Mulai: Panduan memulai

Praktik terbaik untuk deployment

  1. Sematkan versi paket Anda (untuk build yang dapat direproduksi). Paket umum yang perlu dilacak mencakup hal berikut: 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 error saat mengupdate dependensi dan mempermudah update agen dari waktu ke waktu untuk fitur yang lebih baru.

Langkah berikutnya