Mengelola agen yang di-deploy

Agent Runtime memungkinkan Anda mengelola agen yang telah di-deploy ke platform. Anda dapat mencantumkan, mendapatkan, memperbarui, dan menghapus agen yang di-deploy menggunakan konsol, SDK, atau REST API.

Dokumen ini menjelaskan cara mengelola agen yang di-deploy di Agent Platform. Jika Anda ingin men-deploy agen baru, lihat Men-deploy agen.

Mencantumkan agen yang di-deploy

Mencantumkan semua agen yang di-deploy untuk project dan lokasi tertentu:

Konsol

  1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.

    Buka Deployment

Agen yang di-deploy dan merupakan bagian dari project yang dipilih akan muncul dalam daftar (instance Memory Bank mandiri tanpa runtime yang di-deploy akan muncul di halaman Memory Bank). Anda dapat menggunakan kolom Filter untuk memfilter daftar menurut kolom yang Anda tentukan.

Agent Platform SDK

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

for agent in client.runtimes.list():
    print(agent)

Untuk memfilter daftar menurut display_name:

for agent in client.runtimes.list(
    config={
        "filter": 'display_name="DISPLAY_NAME"',
    },
):
    print(agent)

REST

Panggil metode reasoningEngines.list.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: project ID GCP Anda
  • LOCATION: wilayah yang didukung

Metode HTTP dan URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan menerima kode status berhasil (2xx) dan respons kosong.

Mendapatkan agen yang di-deploy

Setiap agen yang di-deploy memiliki ID RESOURCE_ID yang unik. Untuk mempelajari lebih lanjut, lihat Men-deploy agen.

Konsol

  1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.

    Buka Deployment

    Agen yang di-deploy dan merupakan bagian dari project yang dipilih akan muncul dalam daftar. Anda dapat menggunakan kolom Filter untuk memfilter daftar menurut kolom yang ditentukan.

  2. Klik nama agen yang ditentukan. Halaman Metrics untuk agen akan terbuka.

  3. Opsional: Untuk melihat detail deployment agen, klik Deployment details. Panel Deployment details akan terbuka. Untuk menutup panel, klik Selesai.

  4. Opsional: Untuk melihat URL query dan streamQuery untuk agen, klik API URLs. Panel API URLs akan terbuka. Untuk menutup panel, klik Selesai.

Agent Platform SDK

Kode berikut memungkinkan Anda mendapatkan agen tertentu yang di-deploy:

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

remote_agent = client.runtimes.get(
    name="projects/PROJECT_ID_OR_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"
)

REST

Panggil metode reasoningEngines.get.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: project ID GCP Anda
  • LOCATION: wilayah yang didukung
  • RESOURCE_ID: ID resource agen yang di-deploy

Metode HTTP dan URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan menerima kode status berhasil (2xx) dan respons kosong.

Mengupdate agen yang di-deploy

Anda dapat memperbarui satu atau beberapa kolom agen yang di-deploy secara bersamaan, tetapi Anda harus menentukan setidaknya satu kolom yang akan diperbarui.

Anda dapat memperbarui kolom tanpa versi atau berversi dari agen yang di-deploy. Jika Anda memperbarui kolom berversi, Anda akan membuat revisi baru. Untuk mengetahui informasi selengkapnya tentang kolom berversi dan mengelola revisi, lihat Mengelola revisi dan traffic.

Jumlah waktu yang diperlukan untuk mengupdate agen yang di-deploy bergantung pada update yang dilakukan, tetapi umumnya memerlukan waktu antara beberapa detik hingga beberapa menit.

Konsol

  1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.

    Buka Deployment

  2. Untuk agen yang Anda tentukan, klik menu more actions ().

  3. Klik Edit. Panel Edit untuk agen akan terbuka.

  4. Edit Nama tampilan atau Deskripsi untuk agen.

  5. Klik Simpan.

Agent Platform SDK

Untuk mengupdate agen yang di-deploy (sesuai dengan RESOURCE_NAME) ke agen yang diupdate (sesuai dengan UPDATED_AGENT):

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

client.runtimes.update(
    name=RESOURCE_NAME,                    # Required.
    agent=UPDATED_AGENT,                   # Optional.
    config={                                                # Optional.
        "requirements": REQUIREMENTS,      # Optional.
        "display_name": "DISPLAY_NAME",    # Optional.
        "description": "DESCRIPTION",      # Optional.
        "extra_packages": EXTRA_PACKAGES,  # Optional.
    },
)

Argumennya sama seperti saat Anda men-deploy agen.

REST

Panggil metode reasoningEngines.patch dan berikan update_mask untuk menentukan kolom yang akan diperbarui.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: project ID GCP Anda
  • LOCATION: wilayah yang didukung
  • RESOURCE_ID: ID resource agen yang di-deploy
  • update_mask: daftar kolom yang dipisahkan koma untuk diupdate

Metode HTTP dan URL:

PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask="display_name,description"

Meminta isi JSON:

{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION"
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan menerima kode status berhasil (2xx) dan respons kosong.

Mengonfigurasi telemetri untuk agen yang di-deploy

Jika Anda mengaktifkan trace selama pengembangan agen, Anda dapat menggunakan konsol Google Cloud untuk mengonfigurasi telemetri untuk agen yang di-deploy.

Konfigurasikan telemetri untuk agen yang di-deploy dengan telemetri diaktifkan:

  1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.

    Buka Deployment

    Instance Agent Platform yang merupakan bagian dari project yang dipilih akan muncul dalam daftar. Anda dapat menggunakan kolom Filter untuk memfilter daftar menurut kolom yang Anda tentukan.

  2. Temukan baris untuk instance Agent Platform Anda. Di kolom Telemetry configuration, klik Configure. Panel Service configuration akan terbuka.

  3. Anda dapat membuat konfigurasi berikut:

    • Kemampuan observasi: Anda dapat mengonfigurasi hal berikut:

      • Enable instrumentation of OpenTelemetry traces and logs: Untuk mengisi halaman trace dan dasbor observabilitas agen, klik tombol ke posisi aktif.

      • Enable logging of prompt inputs and response outputs: Untuk mengumpulkan dan menyimpan konten lengkap perintah dan respons pengguna, klik tombol ke posisi aktif.

      Jika pengumpulan telemetri dinonaktifkan untuk agen, Anda harus men-deploy ulang agen dan mengupdate versi Vertex AI SDK ke >= 1.126.1 agar dapat melihat opsi konfigurasi untuk Kemampuan Observasi.

    • Container: Konfigurasikan setelan container untuk agen yang di-deploy:

      • Scaling: Masukkan Minimum number of instances dan Maximum number of instances.

      • Resource: Pilih batas untuk Memori dan CPU untuk setiap container.

      • Container concurrency: Masukkan Minimum number of instances untuk menetapkan konkurensi untuk setiap container dan server agen. Nilai yang direkomendasikan adalah (2 * CPU + 1), dan nilai defaultnya adalah 9.

    • Access and Permissions: Klik Manage Permissions in IAM untuk mengelola izin agen di akun layanan terkait.

    • Detail deployment: Lihat detail deployment untuk agen, termasuk Nama resource dan Nama tampilan.

    • Memory bank: Lihat dan edit setelan Memory Bank Generation, Retrieval, dan Retention untuk agen. Pengeditan memerlukan izin aiplatform.reasoningEngines.update; tanpa izin ini, setelan ini bersifat hanya baca.

  4. Klik Update atau Close.

Melihat metrik untuk agen yang di-deploy

Untuk agen yang di-deploy, Anda dapat menggunakan konsol untuk melihat metrik agen:

  1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.

    Buka Deployment

    Agen yang di-deploy dan merupakan bagian dari project yang dipilih akan muncul dalam daftar. Anda dapat menggunakan kolom Filter untuk memfilter daftar menurut kolom yang ditentukan.

  2. Klik nama agen Anda. Dasbor akan ditampilkan untuk agen yang Anda pilih.

  3. Pilih salah satu tab Dasbor berikut:

    • Ringkasan: Melihat dasbor ringkasan metrik untuk agen Anda, termasuk latensi agen, jumlah permintaan agen, dan tingkat error agen.

    • Model: Lihat dasbor metrik untuk model agen Anda, termasuk jumlah panggilan model, tingkat error model, dan penggunaan token model.

    • Tools: Melihat dasbor metrik untuk alat agen Anda, termasuk jumlah panggilan alat, tingkat error alat, dan latensi alat.

    • Usage: Lihat dasbor metrik untuk penggunaan agen Anda, termasuk penggunaan token berdasarkan input dan output, alokasi CPU container, dan alokasi memori container.

    • Logs: Lihat log agen Anda, jika Anda mengaktifkan Cloud Logging untuk agen Anda.

Dasbor Gemini Enterprise Agent Platform

Penghentian darurat dan pencabutan akses

Jika agen yang di-deploy berperilaku tidak terduga, menunjukkan penggunaan alat yang tidak normal, atau terlibat dalam insiden keamanan, Anda dapat menghentikan aktivitasnya dengan menghentikan atau mengalihkan instance runtime, atau dengan mencabut akses downstream-nya melalui kontrol kebijakan di Agent Gateway dan Identity and Access Management (IAM) (IAM).

Karena operasi runtime dan update kebijakan memiliki model penerapan dan periode propagasi yang berbeda, pilih kontrol yang sesuai dengan persyaratan waktu respons insiden Anda.

Mekanisme penghentian darurat dan waktu propagasi

Tabel berikut membandingkan mekanisme yang tersedia untuk menghentikan agen atau mencabut aksesnya, dampaknya terhadap traffic aktif, dan perkiraan waktu propagasinya:

Mekanisme Pengaruh pada traffic dan sesi aktif Waktu penerapan standar
Menghapus agen yang di-deploy (runtimes.delete atau reasoningEngines.delete) Menghentikan semua instance container runtime, menghentikan pemanggilan aktif dan sesi streaming (streamQuery), serta membatalkan identitas SPIFFE agen secara permanen (principal://...). Segera setelah operasi penghapusan selesai (biasanya dalam hitungan detik hingga beberapa menit).
Mengalihkan traffic revisi atau mengarsipkan revisi (trafficSplitManual atau agent_gateway_config) Mengalihkan 100% traffic yang dikirim ke endpoint agen root ke revisi aktif yang diketahui baik, atau mengarsipkan revisi yang ada saat mengupdate spec.deployment_spec.agent_gateway_config. Permintaan langsung ke jalur resource revisi aktif tertentu akan berlanjut hingga revisi tersebut diarsipkan atau dihapus. Beberapa detik hingga beberapa menit untuk menyelesaikan operasi update.
Menerapkan aturan penolakan di Unified Access Policies (UAP) di Agent Gateway (iamEnforcementMode: "ENFORCE") Memblokir panggilan alat keluar, permintaan Model Context Protocol (MCP), dan panggilan agen ke agen yang dirutekan melalui Agent Gateway sambil tetap mengaktifkan container runtime untuk pemeriksaan. Dievaluasi pada pemeriksaan otorisasi baru; tidak menghentikan paksa koneksi streaming terbuka kecuali jika diotorisasi ulang. Konsistensi tertunda: biasanya diterapkan dalam waktu 2 menit, tetapi dapat memerlukan waktu 7 menit atau lebih untuk diterapkan secara global. Pembaruan keanggotaan grup atau principalSet dapat memerlukan waktu beberapa menit hingga jam untuk disinkronkan.
Menerapkan kebijakan penolakan IAM, mencabut peran IAM, atau mengikat kebijakan Principal Access Boundary (Principal Access Boundary) Memblokir identitas agen atau akun layanan terlampir agar tidak memanggil API dan resource Google Cloud . Dievaluasi pada setiap permintaan API; tidak menghentikan container runtime itu sendiri. Konsistensi tertunda: biasanya diterapkan dalam waktu 2 menit, dan hingga 7 menit atau lebih (lihat Transmisi perubahan akses).

Melakukan penghentian darurat

Untuk segera menghentikan agen yang disusupi atau berperilaku buruk dan mencegah tindakan downstream lebih lanjut, selesaikan langkah-langkah berikut:

  1. Menghentikan eksekusi runtime aktif atau mengisolasi traffic:
    • Penghentian penuh (kill switch): Untuk segera menghentikan semua container yang berjalan dan membatalkan validasi identitas SPIFFE agen, hapus agen yang di-deploy menggunakan konsol Google Cloud , client.runtimes.delete(name="RESOURCE_NAME", force=True) di Agent Platform SDK, atau metode REST reasoningEngines.delete.
    • Rollback traffic tanpa menghapus agen: Untuk mempertahankan resource agen dan identitasnya sekaligus menghentikan traffic ke revisi yang salah, update agen dengan trafficSplitManual untuk merutekan 100% traffic root ke revisi yang diketahui baik, atau update spec.deployment_spec.agent_gateway_config untuk mengarsipkan revisi yang sudah ada sebelumnya. Jika pemanggil memanggil jalur resource revisi secara langsung, hapus atau arsipkan revisi tertentu tersebut. Untuk mengetahui petunjuknya, lihat Mengelola revisi dan traffic.
  2. Mencabut akses alat dan resource downstream:
  3. Perhitungkan periode propagasi dan verifikasi pembatasan:
    • Saat agen secara aktif menjalankan panggilan alat yang tidak diinginkan, jangan hanya mengandalkan update kebijakan IAM atau UAP. Perubahan kebijakan memerlukan waktu 2 hingga 7 menit (atau lebih lama untuk update principalSet) untuk diterapkan secara global. Selalu pasangkan pencabutan kebijakan dengan penghapusan runtime atau pengalihan ulang traffic revisi untuk mencapai penghentian langsung.
    • Pastikan aktivitas agen telah berhenti dengan mengkueri Cloud Logging untuk penolakan is_agentic=true dan networkservices.googleapis.com/gateway_requests. Untuk mengetahui detail tentang penyerapan log dan latensi temuan keamanan, lihat Mengaudit tindakan agen dan Memantau traffic melalui Agent Gateway.

Menghapus agen yang di-deploy

Menghapus agen yang di-deploy dari runtime terkelola Agent Runtime. Menghapus runtime agen akan membatalkan identitas agennya. Setiap Kebijakan Akses Terpadu (UAP) IAM yang memberikan izin kepada akun utama tersebut akan mempertahankan akun utama yang tidak aktif dalam aturannya. Selain itu, binding kebijakan tetap aktif. Untuk menghapus akun utama yang tidak berfungsi, perbarui UAP untuk menghapus akun utama dari aturannya. Jika kebijakan tidak lagi berisi akun utama yang aktif, hapus binding kebijakan.

Konsol

  1. Di konsol Google Cloud , buka halaman Deployments Agent Platform.

    Buka Deployment

  2. Untuk agen yang Anda tentukan, klik menu more actions ().

  3. Klik Hapus.

  4. Klik Delete agent.

Agent Platform SDK

Jika Anda sudah memiliki instance agen yang di-deploy (sebagai remote_agent), Anda dapat menjalankan perintah berikut:

remote_agent.delete(
    force=True, # Optional, if the agent has resources (e.g. sessions, memory)
)

Atau, Anda dapat memanggil runtimes.delete() untuk menghapus agen yang di-deploy yang sesuai dengan RESOURCE_NAME dengan cara berikut:

import agentplatform

client = agentplatform.Client(  # For service interactions via client.runtimes
    project="PROJECT_ID",
    location="LOCATION",
)

client.runtimes.delete(
    name=RESOURCE_NAME,
    force=True, # Optional, if the agent has resources (e.g. sessions, memory)
)

REST

Panggil metode reasoningEngines.delete.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: project ID GCP Anda
  • LOCATION: wilayah yang didukung
  • RESOURCE_ID: ID resource agen yang di-deploy

Metode HTTP dan URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan menerima kode status yang berhasil (2xx) dan respons kosong.

Langkah berikutnya

Panduan

Menggunakan agen dengan Agent Platform Runtime.