Mengelola revisi dan traffic

Di Gemini Enterprise Agent Platform, Anda dapat membuat versi agen yang tidak dapat diubah, atau revisi. Kemudian, Anda dapat memisahkan traffic di antara berbagai revisi aktif. Pemisahan traffic memungkinkan Anda menguji dan meningkatkan traffic secara bertahap ke revisi baru serta memisahkan traffic antar-revisi untuk tujuan lain.

Kemampuan untuk membuat revisi selalu diaktifkan. Anda tidak perlu mengaktifkan fitur ini. Untuk mengetahui informasi tentang pembuatan revisi, lihat Revisi dan status.

Jika belum membuat revisi, Anda harus membuat revisi sebelum dapat melihat revisi dan mengonfigurasi traffic di antara revisi tersebut, seperti yang dijelaskan di halaman ini.

Saat ini, revisi dan pembagian traffic tersedia melalui v1beta1 API.

Halaman ini menjelaskan cara mengelola revisi agen dan pembagian traffic.

Revisi dan status

Revisi adalah snapshot agen. Saat Anda membuat agen atau mengupdate kolom yang diberi versi, revisi agen yang tidak dapat diubah akan dibuat. Revisi dapat memiliki status berikut:

  • Aktif: Revisi tersedia untuk kueri. Perhatikan bahwa versi tersebut mungkin tidak menerima kueri apa pun, bergantung pada konfigurasi traffic.
  • Tidak digunakan lagi: Revisi tidak dapat dikueri.

Anda dapat mengidentifikasi revisi menggunakan nama resource-nya, yang dapat ditemukan dengan mencantumkan revisi agen.

Kolom berversi dan tidak berversi

Bagian ini mencantumkan kolom dalam definisi ReasoningEngineSpec agen yang di-deploy yang dapat Anda perbarui untuk membuat revisi agen.

Saat Anda memperbarui kolom berversi, revisi baru akan dibuat.

Saat Anda memperbarui kolom yang tidak memiliki versi,atau kolom dalam definisi agen selain kolom yang memiliki versi, agen akan diperbarui di semua revisinya.

Berikut adalah kolom berversi:

  • PackageSpec
    • pickleObjectGcsUri
    • dependencyFilesGcsUri
    • requirementsGcsUri
    • pythonVersion
  • DeploymentSpec
    • env[]
    • secretEnv[]
    • firstPartyImageOverride
    • agentServerMode
    • pscInterfaceConfig
    • minInstances
    • maxInstances
    • resourceLimits
    • containerConcurrency
  • classMethods[]
  • agentFramework
  • SourceCodeSpec
    • source
    • languageSpec
  • identityType
  • agentCard[]

Mencantumkan revisi agen

Anda dapat mencantumkan semua revisi agen yang di-deploy—baik yang aktif maupun yang tidak digunakan lagi.

Untuk menemukan ID resource agen Anda, lihat Mendapatkan ID resource agen.

Konsol

  1. Di Google Agent Platform, buka Govern > Deployments.

    Buka Deployment

  2. Klik nama agen.

  3. Pilih tab Revisi.

  4. Bagian atas halaman menampilkan informasi berikut tentang revisi:

    1. Mode pemisahan: Dapat berupa "Manual" atau "Terbaru". Lihat "Mengelola traffic ke revisi" untuk mengetahui informasi selengkapnya.
    2. Revisi aktif: Jumlah revisi aktif dibandingkan dengan jumlah total revisi.
    3. Revisi terbaru: Nama revisi terbaru dan persentase traffic yang diterimanya.
    4. Revisi utama: Nama revisi utama, yang menerima sebagian besar traffic.

  5. Daftar ini menampilkan semua revisi untuk agen, dan mencakup informasi berikut:

    1. Nama: Nama atau nomor revisi.
    2. Status: Apakah revisi diterapkan atau tidak digunakan lagi.
    3. Traffic: Persentase traffic yang dirutekan ke revisi.
    4. Dibuat: Tanggal dan waktu revisi dibuat.

Agent Platform SDK

Kode berikut mencantumkan histori revisi untuk agen yang di-deploy tertentu. Untuk mencantumkan revisi, Anda harus mengidentifikasi ID resource unik agen Anda.

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

revisions = client.agent_engines.runtimes.revisions.list(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID"
)

for revision in revisions:
    print(revision)

Ganti variabel berikut dalam kode:

  • PROJECT_ID: Project ID Google Cloud Anda
  • LOCATION: wilayah yang didukung
  • RESOURCE_ID: ID resource agen yang di-deploy

REST

Panggil metode reasoningEngineRuntimeRevisions.list.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Google Cloud Anda
  • LOCATION: wilayah yang didukung
  • RESOURCE_ID: ID resource agen yang di-deploy.

Metode HTTP dan URL: 

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "reasoningEngineRuntimeRevisions": [
      {
        "name": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID",
        "spec": {
          // Revision-specific config attributes (e.g., package specs, requirements)
        },
        "createTime": "2026-05-01T13:26:01Z",
        "state": "ACTIVE"
      }...
    ]
}

Mendapatkan detail revisi

Anda dapat mengambil detail untuk revisi tertentu.

Agent Platform SDK

Kode berikut mengambil detail resource untuk revisi agen yang di-deploy tertentu:

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

revision = client.agent_engines.runtimes.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

print(revision)

Ganti variabel berikut dalam kode:

  • PROJECT_ID: Project ID Google Cloud Anda
  • LOCATION: wilayah yang didukung
  • RESOURCE_ID: ID resource agen yang di-deploy
  • REVISION_ID: ID unik untuk revisi runtime tertentu

REST

Panggil metode reasoningEngineRuntimeRevisions.get .

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Google Cloud Anda
  • LOCATION: wilayah yang didukung
  • RESOURCE_ID: ID resource agen yang di-deploy
  • REVISION_ID: ID unik untuk revisi runtime tertentu

Metode HTTP dan URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID",
  "spec": {
    // Revision-specific config attributes (e.g., package specs, requirements)
  },
  "createTime": "2026-05-06T13:05:24Z",
  "state": "ACTIVE"
}

Mengonfigurasi distribusi traffic antar-revisi

Anda dapat mengelola cara traffic didistribusikan di seluruh revisi aktif. Perhatikan bahwa hanya kueri yang diarahkan ke resource reasoningEngine root yang mengalami pembagian traffic. Mengarahkan kueri pada jalur resource revisi tertentu secara eksplisit akan melewati aturan traffic.

Traffic didistribusikan menggunakan salah satu dari dua metode:

  • Menurut persentase: Saat mengonfigurasi menurut persentase, persentase traffic yang ditentukan akan masuk ke setiap revisi agen. Setiap persentase yang ditentukan harus berupa bilangan bulat. Jumlah persentase harus sama dengan 100%. Meskipun hanya ada 1 revisi yang aktif, Anda tetap dapat mengonfigurasi pembagian traffic (dengan pengalihan 100%).

  • Ke revisi terbaru: Semua traffic diarahkan ke revisi terbaru. Saat revisi agen baru dibuat, traffic akan otomatis diarahkan ke revisi baru tersebut.

Konsol

Untuk mengonfigurasi pengelolaan traffic:

  1. Buka Govern > Deployments.

    Buka Deployment

  2. Klik nama agen.

  3. Buka tab Revisi.

  4. Di halaman detail revisi, klik Kelola traffic.

  5. Di bagian Mode pemisahan, pilih salah satu opsi berikut:

    1. Manual: Tentukan persentase traffic yang akan dialirkan ke setiap revisi.
    2. Selalu yang terbaru: Dalam hal ini, 100% traffic akan masuk ke revisi terbaru (yang baru saja dibuat).

  6. Pilih Simpan untuk menyimpan perubahan.

Agent Platform SDK

Kode berikut menunjukkan contoh konfigurasi distribusi traffic berbasis persentase.

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

client.agent_engines.update(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    config={
        "traffic_config": {
            "trafficSplitManual": {
                "targets": [
                    {
                        "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_1",
                        "percent": 50,
                    },
                    {
                        "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_2",
                        "percent": 50,
                    },
                ]
            }
        }
    },
)

Ganti variabel berikut dalam kode:

  • PROJECT_ID: Project ID Google Cloud Anda
  • LOCATION: wilayah yang didukung
  • RESOURCE_ID: ID resource agen yang di-deploy
  • REVISION_ID_1: ID revisi untuk revisi pertama
  • REVISION_ID_2: ID revisi untuk revisi kedua

REST

Untuk mengonfigurasi traffic agar selalu menuju revisi terbaru (default), perbarui resource ReasoningEngine dengan kolom traffic_config dan tentukan trafficSplitAlwaysLatest:

{
  "trafficConfig": {
    "trafficSplitAlwaysLatest": {}
  }
}

Untuk membagi traffic antara revisi runtime agen, perbarui resource ReasoningEngine dengan kolom traffic_config dan berikan daftar target traffic dengan persentase masing-masing. Berikut cara menetapkan pemisahan manual di dua revisi.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Google Cloud Anda
  • LOCATION: wilayah yang didukung
  • RESOURCE_ID: ID resource agen yang di-deploy
  • REVISION_ID_1: ID revisi untuk revisi pertama
  • REVISION_ID_2: ID revisi untuk revisi kedua
  • TRAFFIC_PERCENTAGE_1: persentase alur traffic yang Anda inginkan untuk revisi pertama
  • TRAFFIC_PERCENTAGE_2: persentase alur traffic yang Anda inginkan untuk revisi kedua

Metode HTTP dan URL: 

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask=traffic_config

Meminta isi JSON: 

{
  "trafficConfig": {
    "trafficSplitManual": {
      "targets": [
          {
            "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_1",
            "percent": TRAFFIC_PERCENTAGE_1
          },
          {
            "runtimeRevisionName": "projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID_2",
            "percent": TRAFFIC_PERCENTAGE_2
          }
        ]
      }
    }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Permintaan ini memulai Operasi yang Berjalan Lama (LRO). Awalnya, Anda akan menerima respons operasi standar. Setelah perubahan konfigurasi selesai, respons akan menampilkan done dan mengulangi setelan konfigurasi Anda. 
{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "done": false
}

Membuat kueri revisi tertentu

Anda dapat membuat kueri revisi tertentu melalui SDK atau API. Revisi harus aktif untuk dikueri. Kueri langsung ke revisi tertentu akan melewati aturan distribusi traffic.

Agent Platform SDK

Kode berikut mengkueri revisi aktif tertentu:

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

revision = client.agent_engines.runtimes.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

response = revision.query(
    input={"your_input_key": "your_input_value"},
    config={"class_method": "your_class_method"},
)

print(response)

Ganti variabel berikut dalam kode:

  • PROJECT_ID: Project ID Google Cloud Anda
  • LOCATION: wilayah yang didukung
  • RESOURCE_ID: ID resource agen yang di-deploy
  • REVISION_ID: ID unik untuk revisi runtime tertentu

REST

Panggil metode reasoningEngineRuntimeRevisions.query.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Google Cloud Anda
  • LOCATION: wilayah yang didukung
  • RESOURCE_ID: ID resource agen yang di-deploy
  • REVISION_ID: ID unik untuk revisi runtime tertentu

Metode HTTP dan URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

 

Memantau revisi

Pantau revisi untuk aktivitas dan masalah dengan melacak nomor revisi sebagai metadata dalam log. Lihat Menyiapkan logging untuk mengetahui informasi tentang cara menyiapkan logging.

Memperbarui revisi

Perbarui agen yang di-deploy dengan mengikuti petunjuk di Memperbarui agen yang di-deploy. Anda dapat memperbaruikolom yang memiliki versi atau tidak memiliki versi. Jika Anda memperbarui kolom yang diberi versi, Anda akan membuat revisi baru.

Menghapus revisi agen

Anda dapat menghapus revisi agen dengan menghapusnya. Anda hanya dapat menghapus revisi yang tidak aktif untuk pengelolaan traffic karena sudah tidak digunakan lagi atau tidak dikonfigurasi untuk menerima traffic. Lihat Mengonfigurasi distribusi traffic antar-revisi untuk mengetahui petunjuk cara mengonfigurasi apakah suatu revisi menerima traffic atau tidak.

Konsol

Untuk menghapus revisi agen:

  1. Buka Govern > Deployments.

    Buka Deployment

  2. Klik nama agen.

  3. Buka tab Revisi.

  4. Di halaman detail revisi, klik Nama revisi.

  5. Temukan baris untuk revisi yang akan dihapus.

  6. Klik ikon Hapus (tempat sampah).

  7. Saat diminta, konfirmasi penghapusan revisi.

Agent Platform SDK

Kode berikut menghapus revisi agen tertentu:

import vertexai
from google.genai import types as genai_types

http_options = genai_types.HttpOptions(
    api_version="v1beta1",
)

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options=http_options,
)

client.agent_engines.runtimes.revisions.delete(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"
)

Ganti variabel berikut dalam kode:

  • PROJECT_ID: Project ID Google Cloud Anda
  • LOCATION: wilayah yang didukung
  • RESOURCE_ID: ID resource agen yang di-deploy
  • REVISION_ID: ID unik untuk revisi runtime tertentu

REST

Panggil metode reasoningEngineRuntimeRevisions.delete.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: Project ID Google Cloud Anda
  • LOCATION: wilayah yang didukung
  • RESOURCE_ID: ID resource agen yang di-deploy
  • REVISION_ID: ID unik untuk revisi runtime tertentu

Metode HTTP dan URL: 

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

 

Batasan

  • Agent Gateway tidak didukung untuk agen Agent Runtime yang menggunakan revisi. Anda tidak akan dapat menggunakan fitur terkait pembuatan versi seperti konfigurasi pemisahan traffic dan kueri per revisi jika Agent Gateway dilampirkan ke konfigurasi agen.