Gestire le revisioni e il traffico

In Gemini Enterprise Agent Platform, puoi creare versioni immutabili, o revisioni, di un agente. Puoi quindi dividere il traffico tra le diverse revisioni attive. La suddivisione del traffico ti consente di testare e aumentare gradualmente il traffico verso le nuove revisioni e di dividere il traffico tra le revisioni per altri scopi.

La possibilità di creare revisioni è sempre abilitata. Non è necessario attivare la funzionalità. Per informazioni sulla creazione di revisioni, vedi Revisioni e stati.

Se non hai ancora creato revisioni, devi crearle prima di poterle visualizzare e configurare il traffico tra loro, come descritto in questa pagina.

Al momento, le revisioni e la suddivisione del traffico sono disponibili tramite l'API v1beta1.

Questa pagina descrive come gestire le revisioni degli agenti e la suddivisione del traffico.

Revisioni e stati

Una revisione è uno snapshot di un agente. Quando crei un agente o aggiorni i relativi campi con controllo delle versioni, viene creata una revisione immutabile dell'agente. Una revisione è Attiva quando è disponibile per le query. Tieni presente che potrebbe non ricevere query, a seconda della configurazione del traffico. Quando una revisione viene archiviata, viene ritirata definitivamente dalla gestione del traffico e non può essere ripristinata. Le revisioni archiviate vengono conservate solo come riferimento storico.

Puoi identificare una revisione utilizzando il nome della risorsa, che puoi trovare elencando le revisioni dell'agente.

Limiti di revisione

Le revisioni archiviate non occupano più uno spazio di revisione. La modifica di un binding di Agent Gateway archivia ogni revisione preesistente (vedi Agent Gateway e revisioni), quindi una modifica del binding libera la quota anziché consumarla. Le revisioni archiviate rimangono eliminabili.

Campi con controllo delle versioni e senza controllo delle versioni

Questa sezione elenca i campi nella definizione ReasoningEngineSpec di un agente di cui è stato eseguito il deployment che puoi aggiornare per creare una revisione dell'agente.

Quando aggiorni i campi con controllo delle versioni,viene creata una nuova revisione.

Quando aggiorni i campi senza controllo delle versioni o i campi nella definizione di un agente diversi dai campi con controllo delle versioni, l'agente viene aggiornato in tutte le sue revisioni.

Questi sono i campi con controllo delle versioni:

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

Elenca le revisioni dell'agente

Puoi elencare tutte le revisioni di un agente di cui è stato eseguito il deployment.

Per trovare l'ID risorsa del tuo agente, consulta Recuperare l'ID risorsa dell'agente.

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

Visualizzare i dettagli di una revisione

Puoi recuperare i dettagli di una revisione specifica.

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

Configurare la distribuzione del traffico tra le revisioni

Puoi gestire la distribuzione del traffico tra le revisioni attive. Tieni presente che solo le query indirizzate alla risorsa reasoningEngine principale vengono sottoposte alla suddivisione del traffico. L'indirizzamento di una query a un percorso di risorse di revisione specifico ignora esplicitamente le regole di traffico.

Il traffico viene distribuito utilizzando uno dei due metodi seguenti:

• Per percentuale: quando la configurazione avviene per percentuale, una percentuale specificata di traffico viene indirizzata a ogni revisione dell'agente. Ogni percentuale specificata deve essere un numero intero. La somma delle percentuali deve essere pari al 100%. Anche se è attiva una sola revisione, puoi comunque configurare la suddivisione del traffico (in cui il 100% viene reindirizzato).
• All'ultima revisione: tutto il traffico viene indirizzato all'ultima revisione. Quando viene creata una nuova revisione dell'agente, il traffico viene indirizzato automaticamente a questa nuova revisione.

Una suddivisione manuale può avere come target solo le revisioni attive. Se assegni un nome a una revisione archiviata, viene restituito 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
}

Eseguire una query per una revisione specifica

Puoi eseguire query su una revisione specifica tramite l'SDK o le API. La revisione deve essere attiva per poter essere interrogata. Le query dirette a una revisione specifica ignorano le regole di distribuzione del traffico.

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 e revisioni

Il collegamento, la modifica o lo scollegamento di un binding di Agent Gateway a un agente crea una nuova revisione e archivia ogni revisione esistente prima della modifica. Solo la nuova revisione rimane attiva. Questa operazione è irreversibile: le revisioni archiviate non possono essere ripristinate.

Poiché una modifica del binding archivia ogni revisione esistente, è consentita solo quando tutto il traffico si trova già nell'ultima revisione. L'API rifiuta la modifica se è impostata una suddivisione manuale, anche una che assegna il 100% del traffico all'ultima revisione. Il rifiuto restituisce 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.

Per modificare il gateway di un agente che utilizza una suddivisione manuale del traffico:

1. Passa al routing sempre più recente impostando traffic_config.traffic_split_always_latest (o deselezionando traffic_config). Vedi Configurare la distribuzione del traffico tra le revisioni.
2. Modifica spec.deployment_spec.agent_gateway_config. Viene creata la nuova revisione e vengono archiviate tutte le precedenti.
3. Se hai di nuovo bisogno di una suddivisione manuale, creala a partire dalle revisioni create dopo la modifica del binding.

Le revisioni archiviate rimangono accessibili tramite l'API e la relativa ReasoningEngineSpec completa viene conservata. Per creare una nuova revisione equivalente a una archiviata, recupera i dettagli della revisione archiviata e implementa una nuova revisione con gli stessi campi con controllo delle versioni. Il riutilizzo dello stesso URI dell'immagine container riproduce lo stesso runtime; il riutilizzo della stessa posizione del codice sorgente e degli stessi metodi della classe riproduce lo stesso comportamento.

Monitorare le revisioni

Monitora le revisioni di attività e problemi monitorando il numero di revisione come metadati nei log. Per informazioni sulla configurazione della registrazione, consulta Configurare la registrazione.

Crea una nuova revisione dell'agente

Per creare una nuova revisione, aggiorna i campi con controllo delle versioni di un agente di cui è stato eseguito il deployment. Per istruzioni, vedi Aggiornare un agente di cui è stato eseguito il deployment.

Se aggiorni i campi con controllo delle versioni, viene creata automaticamente una nuova revisione. Se aggiorni i campi senza controllo delle versioni, l'agente viene aggiornato in tutte le revisioni esistenti senza crearne una nuova.

Gestisci pulizia delle revisioni

Gemini Enterprise Agent Platform rimuove automaticamente le revisioni precedenti per aiutarti a rispettare i limiti di revisione. Puoi anche eliminare manualmente le revisioni.

Garbage collection automatica

Per impostazione predefinita, Gemini Enterprise Agent Platform abilita la garbage collection automatica per tutti gli agenti. Non puoi disattivarlo. La garbage collection viene eseguita solo nell'ambito di un'operazione di aggiornamento dell'agente e non come job in background.

• Quando viene eseguita:se un'operazione di aggiornamento tenta di superare il limite di revisione configurato, Gemini Enterprise Agent Platform elimina le revisioni idonee meno recenti nella stessa operazione prima di creare la nuova revisione. Se abbassi il limite, Gemini Enterprise Agent Platform elimina immediatamente un numero sufficiente di revisioni idonee più vecchie per rispettare il nuovo limite.
• Revisioni idonee:una revisione è idonea all'eliminazione solo se soddisfa tutte le seguenti condizioni:
  • Si trova nello stato ACTIVE.
  • Non è inclusa nella configurazione del traffico (riceve lo 0% del traffico).
• Errori: se non sono presenti revisioni idonee sufficienti per liberare spazio, Gemini Enterprise Agent Platform rifiuta l'operazione di aggiornamento con un errore FAILED_PRECONDITION. Non elimina alcuna revisione né ne crea una nuova. Prima di riprovare, devi rimuovere le revisioni dalla configurazione del traffico o aumentare il limite.

Configurare il limite

Il limite è definito dal campo revision_garbage_collection_strategy.keep_n_latest.max_revisions dell'agente. Puoi impostare questo campo quando crei l'agente o modificarlo in un secondo momento con una richiesta di aggiornamento.

• Valore predefinito per i nuovi agenti:100 revisioni.
• Valore predefinito per gli agenti esistenti:950 revisioni.
• Intervallo consentito: da 1 a 950. Un valore pari o inferiore a 0 viene rifiutato. Un valore superiore a 950 viene rifiutato perché 950 è una quota rigida che non può essere aumentata.

Eliminazione manuale

Puoi rimuovere manualmente una revisione dell'agente eliminandola. Puoi eliminare solo le revisioni che non sono attive per la gestione del traffico perché non sono configurate per ricevere traffico. Consulta Configurare la distribuzione del traffico tra le revisioni per istruzioni su come configurare se una revisione riceve traffico.

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