Men-deploy agen

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

1. Konfigurasikan agen untuk deployment.
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.

Mengonfigurasi agen untuk deployment

Anda dapat membuat konfigurasi opsional berikut:

• Persyaratan paket
• Paket tambahan
• Variabel lingkungan
• Folder Cloud Storage
• Metadata resource

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. Gunakan praktik terbaik berikut:

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 agen Anda.

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.

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

• Batas atas atau sematkan 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",
  ]
  

• Tambahkan paket dan batasan tambahan:

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

• Arahkan 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",
  ]
  

• 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 Anda kembangkan dan 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 roda 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 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:

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

Menentukan folder Cloud Storage

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

gcs_dir_name = None

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

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

Membuat instance AgentEngine

Untuk men-deploy agen di Vertex AI, gunakan agent_engines.create untuk meneruskan objek local_agent beserta 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.
)

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 folder 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 dan mem-build penampung serta 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. Instance ini terpisah dari instance lokal agen.

Memberikan izin agen yang di-deploy

Jika agen yang di-deploy perlu diberi izin tambahan, ikuti petunjuk di Menyiapkan izin agen layanan.

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

Langkah berikutnya

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