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 secara bertahap meningkatkan traffic 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 memperbarui kolom berversi-nya, revisi agen yang tidak dapat diubah akan dibuat. Revisi akan Aktif jika tersedia untuk kueri. Perhatikan bahwa versi tersebut mungkin tidak menerima kueri apa pun, bergantung pada konfigurasi traffic. Jika direvisi, revisi tersebut akan diarsipkan secara permanen dari penayangan traffic dan tidak dapat dipulihkan. Revisi yang diarsipkan hanya dipertahankan untuk referensi historis.

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

Batas revisi

Revisi yang diarsipkan berhenti menempati slot revisi. Mengubah binding Agent Gateway mengarsipkan setiap revisi yang sudah ada sebelumnya (lihat Agent Gateway dan revisi), sehingga perubahan binding membebaskan kuota, bukan menggunakannya. Revisi yang diarsipkan tetap dapat dihapus.

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.

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

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

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

for revision in revisions:
    print(revision)

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions" | Select-Object -Expand Content

{
  "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.

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

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

print(revision)

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

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID" | Select-Object -Expand Content

{
  "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 ke 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.

Pemisahan manual hanya dapat menargetkan revisi Aktif. Memberi nama revisi yang diarsipkan akan menampilkan FAILED_PRECONDITION:

Traffic target revision {revision} is not an active revision of this Agent Engine. Update traffic_config to reference only active revisions.

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

client.runtimes.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,
                    },
                ]
            }
        }
    },
)

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

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

{
  "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
          }
        ]
      }
    }
}

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask=traffic_config"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask=traffic_config" | Select-Object -Expand Content

{
  "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.

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

revision = client.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)

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID:query" | Select-Object -Expand Content

Agent Gateway dan revisi

Melampirkan, mengubah, atau melepaskan binding Agent Gateway pada agen akan membuat revisi baru dan Mengarsipkan setiap revisi yang ada sebelum perubahan. Hanya revisi baru yang tetap Aktif. Tindakan ini tidak dapat diurungkan; revisi yang diarsipkan tidak dapat dipulihkan.

Karena perubahan binding mengarsipkan setiap revisi yang ada, perubahan ini hanya diizinkan saat semua traffic sudah berada di revisi terbaru. API akan menolak perubahan jika ada pemisahan manual yang ditetapkan, bahkan yang kebetulan menempatkan 100% traffic pada revisi terbaru. Penolakan menampilkan FAILED_PRECONDITION:

Changing spec.deployment_spec.agent_gateway_config archives every existing runtime revision, so it is only allowed while all traffic is on the latest revision. Set traffic_config.traffic_split_always_latest, or clear traffic_config, before changing the Agent Gateway configuration.

Untuk mengubah gateway pada agen yang menggunakan pemisahan traffic manual:

1. Beralihlah ke perutean selalu terbaru dengan menyetel traffic_config.traffic_split_always_latest (atau dengan menghapus traffic_config). Lihat Mengonfigurasi distribusi traffic antar-revisi.
2. Ubah spec.deployment_spec.agent_gateway_config. Tindakan ini akan membuat revisi baru dan mengarsipkan setiap revisi sebelumnya.
3. Jika Anda memerlukan pemisahan manual lagi, buat dari revisi yang dibuat setelah perubahan pengikatan.

Revisi yang diarsipkan tetap dapat diakses melalui API, dan ReasoningEngineSpec lengkapnya tetap dipertahankan. Untuk membuat revisi baru yang setara dengan revisi yang diarsipkan, dapatkan detail revisi yang diarsipkan dan deploy revisi baru dengan kolom berversi yang sama. Menggunakan kembali URI image container yang sama akan mereproduksi runtime yang sama; menggunakan kembali lokasi kode sumber dan metode class yang sama akan mereproduksi perilaku yang sama.

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.

Membuat revisi agen baru

Untuk membuat revisi baru, Anda mengupdate kolom berversi dari agen yang di-deploy. Lihat Memperbarui agen yang di-deploy untuk mengetahui petunjuknya.

Jika Anda memperbarui kolom berversi, revisi baru akan otomatis dibuat. Jika Anda memperbarui kolom yang tidak diberi versi, agen akan diperbarui di semua revisi yang ada tanpa membuat revisi baru.

Mengelola pembersihan revisi

Gemini Enterprise Agent Platform otomatis menghapus revisi lama untuk membantu Anda tetap berada dalam batas revisi. Anda juga dapat menghapus revisi secara manual.

Pembersihan sampah memori otomatis

Secara default, Gemini Enterprise Agent Platform mengaktifkan pembersihan sampah memori otomatis untuk semua agen. Anda tidak dapat menonaktifkannya. Pembersihan sampah memori hanya berjalan sebagai bagian dari operasi update agen; tidak berjalan sebagai tugas latar belakang.

• Saat dijalankan: Jika operasi update mencoba melampaui batas revisi yang dikonfigurasi, Gemini Enterprise Agent Platform akan menghapus revisi terlama yang memenuhi syarat dalam operasi yang sama sebelum membuat revisi baru. Jika Anda menurunkan batas, Gemini Enterprise Agent Platform akan segera menghapus revisi lama yang memenuhi syarat dalam jumlah yang cukup untuk memenuhi batas baru.
• Revisi yang memenuhi syarat: Revisi memenuhi syarat untuk dihapus hanya jika memenuhi semua kondisi berikut:
  • Statusnya adalah ACTIVE.
  • Tidak disertakan dalam konfigurasi traffic (menerima 0% traffic).
• Kegagalan: Jika revisi yang memenuhi syarat tidak cukup untuk mengosongkan ruang, Gemini Enterprise Agent Platform akan menolak operasi update dengan error FAILED_PRECONDITION. Tindakan ini tidak menghapus revisi apa pun atau membuat revisi baru. Anda harus menghapus revisi dari konfigurasi traffic atau menaikkan batas sebelum mencoba lagi.

Mengonfigurasi batas

Batas ditentukan oleh kolom revision_garbage_collection_strategy.keep_n_latest.max_revisions pada agen. Anda dapat menyetel kolom ini saat membuat agen atau mengubahnya nanti dengan permintaan update.

• Default untuk agen baru: 100 revisi.
• Default untuk agen lama: 950 revisi.
• Rentang yang diizinkan: 1 hingga 950. Nilai 0 atau kurang akan ditolak. Nilai yang lebih besar dari 950 ditolak karena 950 adalah kuota tetap yang tidak dapat dinaikkan.

Penghapusan manual

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

import agentplatform

client = agentplatform.Client(
    project="PROJECT_ID",
    location="LOCATION",
    http_options={"api_version": "v1beta1"},
)

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

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

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID/runtimeRevisions/REVISION_ID" | Select-Object -Expand Content