Men-deploy agen

Men-deploy agen di Agent Runtime akan membuatnya tersedia dari jarak jauh untuk menangani permintaan. Dokumen ini menjelaskan cara men-deploy agen berdasarkan alur kerja pengembangan Anda: dari objek eksekusi, file sumber lokal, Dockerfile, image container yang dihosting di Artifact Registry, atau langsung melalui repositori Git yang terhubung.

Untuk men-deploy agen di Agent Runtime, pilih salah satu metode berikut:

Developer Connect

Direkomendasikan untuk project yang dikelola di repositori Git yang ditautkan melalui Developer Connect. Metode ini menyederhanakan deployment agen langsung dari kode sumber Anda dan secara native mendukung kontrol versi, kolaborasi tim, dan pipeline CI/CD. Sebelum menggunakan metode ini, siapkan link repositori Git Anda dengan mengikuti petunjuk di Menyiapkan link repositori Git Developer Connect.

Anda hanya dapat menggunakan metode deployment ini dengan Python.

File sumber

Sangat cocok untuk alur kerja otomatis seperti pipeline CI/CD dan alat Infrastructure as Code seperti Terraform, yang memungkinkan deployment yang sepenuhnya deklaratif dan otomatis. Alat ini men-deploy agen Anda langsung dari kode sumber lokal dan tidak memerlukan bucket Cloud Storage.

Anda hanya dapat menggunakan metode deployment ini dengan Python.

Dockerfile

Serupa dengan men-deploy dari file sumber. Anda men-deploy agen langsung dari kode sumber lokal tanpa memerlukan bucket Cloud Storage. Metode ini sesuai jika Anda perlu menentukan dan memiliki kontrol atas server API yang di-deploy. Container yang di-deploy harus mematuhi kontrak runtime.

Anda dapat menggunakan metode deployment ini dengan bahasa apa pun. Contoh di halaman ini menggunakan Python.

Image container

Mirip dengan men-deploy dari Dockerfile. Anda men-deploy image container yang dihosting di Artifact Registry. Gunakan metode ini jika Anda memerlukan kontrol atas proses build untuk image container dan latensi deployment yang lebih rendah. Image container harus mematuhi kontrak runtime.

Anda dapat menggunakan metode deployment ini dengan bahasa apa pun. Contoh di halaman ini menggunakan Python.

Agent Platform SDK

Ideal untuk pengembangan interaktif di lingkungan seperti Colab, yang memungkinkan deployment objek local_agent dalam memori. Metode ini paling cocok untuk agen dengan struktur yang tidak berisi komponen kompleks yang tidak dapat diserialisasi.

Untuk memulai, ikuti langkah-langkah berikut:

  1. Selesaikan prasyarat
  2. Opsional: Mengonfigurasi agen untuk deployment
  3. Membuat instance Gemini Enterprise Agent Platform
  4. Opsional: Mendapatkan ID resource agen
  5. Opsional: Mencantumkan operasi yang didukung
  6. Opsional: Memberikan izin agen yang di-deploy

Prasyarat

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

  1. Menyiapkan lingkungan Anda
  2. Membuat agen

Opsional: Mengonfigurasi agen untuk deployment

Anda dapat membuat konfigurasi opsional untuk agen Anda. Contoh di bagian ini menggunakan Python.

Membuat instance Agent Platform

Bagian ini menjelaskan cara membuat instance Agent Platform untuk men-deploy agen. Anda dapat memilih di antara metode berikut:

Developer Connect

Untuk men-deploy dari Developer Connect di Agent Platform, gunakan client.runtimes.create dengan memberikan developer_connect_source, entrypoint_module, dan entrypoint_object dalam kamus konfigurasi, beserta konfigurasi opsional lainnya. Metode ini memungkinkan Anda men-deploy kode langsung dari repositori Git yang terhubung.

Anda hanya dapat menggunakan metode deployment ini dengan Python. 

remote_agent = client.runtimes.create(
    config={
        "developer_connect_source": {                   # Required.
            "git_repository_link": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID/gitRepositoryLinks/REPO_ID",
            "revision": "main",
            "dir": "path/to/dir",
        },
        "entrypoint_module": "agent",                   # Required.
        "entrypoint_object": "root_agent",              # Required.
        "requirements_file": "requirements.txt",        # Optional.
        # Other optional configs:
        # "env_vars": {...},
        # "service_account": "...",
    },
)

Parameter untuk deployment Developer Connect adalah:

  • developer_connect_source (dict): Konfigurasi untuk mengambil kode sumber. Lihat menyiapkan link repositori Git Developer Connect untuk mengetahui detailnya.
    • git_repository_link (str): Nama resource link repositori Git Developer Connect.
    • revision (str): Revisi yang akan diambil (cabang, tag, atau SHA commit).
    • dir (str): Direktori root kode agen dalam repositori.
  • entrypoint_module (str): Nama modul Python yang berisi titik entri agen, relatif terhadap direktori yang ditentukan di developer_connect_source.dir.
  • entrypoint_object (str): Nama objek yang dapat dipanggil dalam entrypoint_module yang mewakili aplikasi agen (misalnya, root_agent).
  • requirements_file (str): Opsional: Jalur ke file persyaratan pip yang relatif terhadap root sumber. Setelan defaultnya adalah requirements.txt.

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

  1. Layanan Agent Runtime mengambil kode sumber dari revisi repositori Git yang ditentukan.
  2. Layanan ini menginstal dependensi dari requirements_file (jika disediakan).
  3. Layanan akan memulai aplikasi agen menggunakan entrypoint_module dan entrypoint_object yang ditentukan.

Latensi deployment bergantung pada total waktu yang diperlukan untuk menginstal paket yang diperlukan. Setelah di-deploy, remote_agent akan sesuai dengan instance local_agent yang berjalan di Agent Platform dan dapat dikueri atau dihapus.

Objek remote_agent sesuai dengan class AgentRuntime yang berisi hal berikut:

File sumber

Untuk men-deploy dari file sumber di Agent Platform, gunakan client.runtimes.create dengan menyediakan source_packages, entrypoint_module, entrypoint_object, dan class_methods dalam kamus konfigurasi, bersama dengan konfigurasi opsional lainnya. Dengan metode ini, Anda tidak perlu meneruskan objek agen atau bucket Cloud Storage.

Anda hanya dapat menggunakan metode deployment ini dengan Python. 

# Example file structure:
# /agent_directory
#     ├── agent.py
#     ├── requirements.txt

# Example agent_directory/agent.py:
# class MyAgent:
#     def ask(self, question: str) -> str:
#         return f"Answer to {question}"
# root_agent = MyAgent()

remote_agent = client.runtimes.create(
    config={
        "source_packages": source_packages,             # Required.
        "entrypoint_module": entrypoint_module,         # Required.
        "entrypoint_object": entrypoint_object,         # Required.
        "class_methods": class_methods,                 # Required.
        "requirements_file": requirements_file,         # Optional.
        "display_name": display_name,                   # Optional.
        "description": description,                     # Optional.
        "labels": labels,                               # Optional.
        "env_vars": env_vars,                           # Optional.
        "build_options": build_options,                 # Optional.
        "identity_type": identity_type,                 # 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.
        "agent_framework": agent_framework,             # Optional.
    },
)

Parameter untuk deployment sumber inline adalah:

  • source_packages (list[str]): Daftar jalur file atau direktori lokal yang akan disertakan dalam deployment. Ukuran total file dan direktori di source_packages tidak boleh melebihi 8 MB.
  • entrypoint_module (str): Nama modul Python yang sepenuhnya memenuhi syarat yang berisi titik entri agen (misalnya, agent_dir.agent).
  • entrypoint_object (str): Nama objek yang dapat dipanggil dalam entrypoint_module yang mewakili aplikasi agen (misalnya, root_agent).
  • class_methods (list[dict]): Daftar kamus yang menentukan metode yang diekspos agen. Setiap kamus menyertakan kolom name, api_mode, dan parameters opsional. Lihat Mencantumkan operasi yang didukung untuk mengetahui informasi selengkapnya tentang metode untuk agen kustom.

    Contoh:

    class_methods = [
    {
        "name": "method_name",
        "api_mode": "",  # Options: "", "async", "async_stream", "stream", "bidi_stream"
        "parameters": {
            "type": "object",
            "properties": {
                "param1": {"type": "string", "description": "Description of param1"},
                "param2": {"type": "integer"}
            },
            "required": ["param1"]
        }
    }
]
  • requirements_file (str): Opsional: Jalur ke file persyaratan pip dalam jalur yang ditentukan di source_packages. Defaultnya adalah requirements.txt di direktori utama sumber yang dipaketkan.

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

  1. Agent Platform SDK membuat arsip tar.gz dari jalur yang ditentukan di source_packages.
  2. Arsip ini dienkode dan dikirim langsung ke Agent Platform API.
  3. Layanan Agent Runtime menerima arsip, mengekstraknya, menginstal dependensi dari requirements_file (jika disediakan), dan memulai aplikasi agen menggunakan entrypoint_module dan entrypoint_object yang ditentukan.

Latensi deployment bergantung pada total waktu yang diperlukan untuk menginstal paket yang diperlukan. Setelah di-deploy, remote_agent akan sesuai dengan instance local_agent yang berjalan di Agent Platform dan dapat dikueri atau dihapus.

Objek remote_agent sesuai dengan class AgentRuntime yang berisi hal berikut:

Dockerfile

Men-deploy dari Dockerfile di Agent Platform mengikuti pendekatan yang serupa dengan men-deploy dari file sumber, kecuali bahwa Anda menggunakan image_spec dalam konfigurasi, bukan entrypoint_module, entrypoint_object, dan requirements_file. Container yang dibangun dari Dockerfile harus mematuhi kontrak runtime.

Anda dapat menggunakan metode deployment ini dengan bahasa apa pun. Contoh di bagian ini menggunakan Python.

Berikut adalah contoh deployment agen menggunakan Dockerfile:

# Example file structure:
# /current_directory
#     ├── agent.py
#     ├── main.py
#     ├── requirements.txt
#     ├── Dockerfile

remote_agent = client.runtimes.create(
    config={
        "source_packages": [
            "agent.py",
            "main.py",
            "requirements.txt",
            "Dockerfile",
        ],
        "image_spec": {},  # tells Agent Runtime to use the Dockerfile
        # Other optional configs
        "display_name": "Dockerfile agent",
    }
)

Latensi deployment bergantung pada total waktu yang diperlukan untuk menginstal paket yang diperlukan. Setelah di-deploy, remote_agent akan sesuai dengan instance local_agent yang berjalan di Agent Platform dan dapat dikueri atau dihapus.

Objek remote_agent sesuai dengan class AgentRuntime yang berisi hal berikut:

Image container

Untuk men-deploy dari image container, ikuti petunjuk penyiapan untuk Menggunakan container Anda sendiri terlebih dahulu, dan pastikan untuk menginstal versi google-cloud-aiplatform yang memenuhi >=1.144. Image container harus mematuhi kontrak runtime.

Anda dapat menggunakan metode deployment ini dengan bahasa apa pun. Contoh di bagian ini menggunakan Python.

Berikut adalah contoh deployment agen menggunakan image container:

remote_agent = client.runtimes.create(
    config={
        "container_spec": {
            "image_uri": "CONTAINER_IMAGE_URI",
        },
        # Other optional configs
        "display_name": "Container image agent",
    },
)

Dengan CONTAINER_IMAGE_URI sesuai dengan URI image container di Artifact Registry (seperti us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag).

Latensi deployment bergantung pada total waktu yang diperlukan untuk menginstal paket yang diperlukan. Setelah di-deploy, remote_agent akan sesuai dengan instance local_agent yang berjalan di Agent Platform dan dapat dikueri atau dihapus.

Objek remote_agent sesuai dengan class AgentRuntime yang berisi hal berikut:

Agent Platform SDK

Untuk men-deploy agen di Agent Platform, gunakan client.runtimes.create untuk meneruskan objek local_agent beserta konfigurasi opsional: 

remote_agent = client.runtimes.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.
        "identity_type": identity_type,                 # 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.
        "agent_framework": agent_framework,             # Optional.
    },
)

Deployment memerlukan waktu beberapa menit, dan selama itu, 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 folder yang sesuai) untuk melakukan staging artefak.
  3. Cloud Storage URI untuk setiap artefak ditentukan dalam PackageSpec.
  4. Layanan Agent Runtime menerima permintaan dan membangun container serta memulai server HTTP di backend.

Latensi deployment bergantung pada total waktu yang diperlukan untuk menginstal paket yang diperlukan. Setelah di-deploy, remote_agent akan sesuai dengan instance local_agent yang berjalan di Agent Platform dan dapat dikueri atau dihapus.

Objek remote_agent sesuai dengan class AgentRuntime yang berisi hal berikut:

Opsional: Mendapatkan 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 menggunakan AgentRuntime.operation_schemas 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:

Opsional: Memberikan izin agen yang di-deploy

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

Opsional: Men-deploy agen dengan infrastruktur perusahaan

Untuk men-deploy agen Anda dengan lingkungan lengkap yang mencakup lapisan keamanan dan tata kelola, salin dan sesuaikan template Application Design Center berikut:

Langkah berikutnya

Panduan

Pelajari cara mengelola agen yang telah di-deploy ke runtime terkelola Agent Platform.

Panduan

Menggunakan agen dengan Agent Platform Runtime.