Gestire le revisioni e il traffico

In Gemini Enterprise Agent Platform, puoi creare versioni immutabili, o revisioni, di un agente. Puoi quindi suddividere il traffico tra le diverse revisioni attive. La suddivisione del traffico 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 può avere i seguenti stati:

  • Attiva: la revisione è disponibile per le query. Tieni presente che potrebbe non ricevere query, a seconda della configurazione del traffico.
  • Obsoleta: non è possibile eseguire query sulla revisione.

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

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 revisioni dell'agente

Puoi elencare tutte le revisioni di un agente di cui è stato eseguito il deployment, sia attive che ritirate.

Per trovare l'ID risorsa del tuo agente, vedi Ottenere l'ID risorsa dell'agente.

Console

  1. In Google Agent Platform, vai a Govern > Deployments.

    Vai a Deployment

  2. Fai clic sul nome dell'agente.

  3. Seleziona la scheda Revisioni.

  4. Nella parte superiore della pagina sono visualizzate le seguenti informazioni sulle revisioni:

    1. Modalità di divisione: può essere "Manuale" o "Più recente". Per ulteriori informazioni, consulta la sezione "Gestire il traffico verso le revisioni".
    2. Revisioni attive: il numero di revisioni attive rispetto al numero totale di revisioni.
    3. Ultima revisione: il nome dell'ultima revisione e la percentuale di traffico che riceve.
    4. Revisione principale: il nome della revisione principale, che riceve la maggior parte del traffico.

  5. L'elenco mostra tutte le revisioni dell'agente e include le seguenti informazioni:

    1. Nome: il nome o il numero della revisione.
    2. Stato: indica se la revisione è implementata o deprecata.
    3. Traffico: la percentuale di traffico indirizzato alla revisione.
    4. Creata: la data e l'ora in cui è stata creata la revisione.

SDK Agent Platform

Il seguente codice elenca la cronologia delle revisioni per un agente di cui è stato eseguito il deployment specificato. Per elencare le revisioni, devi identificare l'ID risorsa univoco del tuo agente.

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)

Sostituisci le seguenti variabili nel codice:

  • PROJECT_ID: il tuo Google Cloud ID progetto
  • LOCATION: una regione supportata
  • RESOURCE_ID: l'ID risorsa dell'agente di cui è stato eseguito il deployment

REST

Chiama il metodo reasoningEngineRuntimeRevisions.list.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo Google Cloud ID progetto
  • LOCATION: una regione supportata
  • RESOURCE_ID: l'ID risorsa dell'agente di cui è stato eseguito il deployment.

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

SDK Agent Platform

Il seguente codice recupera i dettagli delle risorse per una revisione dell'agente di cui è stato eseguito il deployment specificata:

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)

Sostituisci le seguenti variabili nel codice:

  • PROJECT_ID: il tuo Google Cloud ID progetto
  • LOCATION: una regione supportata
  • RESOURCE_ID: l'ID risorsa dell'agente di cui è stato eseguito il deployment
  • REVISION_ID: l'ID univoco per una revisione specifica del runtime

REST

Chiama il metodo reasoningEngineRuntimeRevisions.get .

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo Google Cloud ID progetto
  • LOCATION: una regione supportata
  • RESOURCE_ID: l'ID risorsa dell'agente di cui è stato eseguito il deployment
  • REVISION_ID: l'ID univoco per una revisione specifica del runtime

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Console

Per configurare la gestione del traffico:

  1. Vai a Governa > Deployment.

    Vai a Deployment

  2. Fai clic sul nome dell'agente.

  3. Vai alla scheda Revisioni.

  4. Nella pagina dei dettagli delle revisioni, fai clic su Gestisci traffico.

  5. In Modalità Split, seleziona una delle seguenti opzioni:

    1. Manuale: specifica la percentuale di traffico da indirizzare a ciascuna revisione.
    2. Sempre l'ultima: in questo caso, il 100% del traffico viene indirizzato all'ultima revisione (creata più di recente).

  6. Seleziona Salva per salvare le modifiche.

SDK Agent Platform

Il seguente codice mostra un esempio di configurazione della distribuzione del traffico basata sulla percentuale.

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

Sostituisci le seguenti variabili nel codice:

  • PROJECT_ID: il tuo Google Cloud ID progetto
  • LOCATION: una regione supportata
  • RESOURCE_ID: l'ID risorsa dell'agente di cui è stato eseguito il deployment
  • REVISION_ID_1: l'ID revisione della prima revisione
  • REVISION_ID_2: l'ID revisione della seconda revisione

REST

Per configurare il traffico in modo che venga sempre indirizzato all'ultima revisione (impostazione predefinita), aggiorna la risorsa ReasoningEngine con il campo traffic_config e specifica trafficSplitAlwaysLatest:

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

Per dividere il traffico tra le revisioni di runtime di un agente, aggiorna la risorsa ReasoningEngine con il campo traffic_config e fornisci un elenco di destinazioni del traffico con le rispettive percentuali. Di seguito viene mostrato come impostare la suddivisione manuale in due revisioni.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo Google Cloud ID progetto
  • LOCATION: una regione supportata
  • RESOURCE_ID: l'ID risorsa dell'agente di cui è stato eseguito il deployment
  • REVISION_ID_1: l'ID revisione della prima revisione
  • REVISION_ID_2: l'ID revisione della seconda revisione
  • TRAFFIC_PERCENTAGE_1: il flusso di traffico percentuale che vuoi per la prima revisione
  • TRAFFIC_PERCENTAGE_2: il flusso di traffico percentuale che vuoi per la seconda revisione

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, espandi una di queste opzioni:

Questa richiesta avvia un'operazione a lunga esecuzione (LRO). Inizialmente, riceverai una risposta standard all'operazione. Al termine delle modifiche alla configurazione, la risposta mostra done e ripete le impostazioni di configurazione. 
{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "done": false
}

Eseguire query su 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.

SDK Agent Platform

Il seguente codice esegue una query su una revisione attiva specifica:

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)

Sostituisci le seguenti variabili nel codice:

  • PROJECT_ID: il tuo Google Cloud ID progetto
  • LOCATION: una regione supportata
  • RESOURCE_ID: l'ID risorsa dell'agente di cui è stato eseguito il deployment
  • REVISION_ID: l'ID univoco per una revisione specifica del runtime

REST

Chiama il metodo reasoningEngineRuntimeRevisions.query.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo Google Cloud ID progetto
  • LOCATION: una regione supportata
  • RESOURCE_ID: l'ID risorsa dell'agente di cui è stato eseguito il deployment
  • REVISION_ID: l'ID univoco per una revisione specifica del runtime

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

 

Monitorare le revisioni

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

Aggiorna una revisione

Aggiorna gli agenti di cui è stato eseguito il deployment seguendo le istruzioni riportate in Aggiornare un agente di cui è stato eseguito il deployment. Puoi aggiornare i campi con o senza controllo delle versioni. Se aggiorni i campi con controllo delle versioni, creerai una nuova revisione.

Eliminare una revisione dell'agente

Puoi rimuovere una revisione dell'agente eliminandola. Puoi eliminare solo le revisioni che non sono attive per la gestione del traffico perché sono ritirate o 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.

Console

Per eliminare una revisione per un agente:

  1. Vai a Governa > Deployment.

    Vai a Deployment

  2. Fai clic sul nome dell'agente.

  3. Vai alla scheda Revisioni.

  4. Nella pagina dei dettagli delle revisioni, fai clic sul nome della revisione.

  5. Trova la riga della revisione da rimuovere.

  6. Fai clic sull'icona Elimina (cestino).

  7. Quando richiesto, conferma l'eliminazione della revisione.

SDK Agent Platform

Il seguente codice elimina una revisione dell'agente specificata:

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

Sostituisci le seguenti variabili nel codice:

  • PROJECT_ID: il tuo Google Cloud ID progetto
  • LOCATION: una regione supportata
  • RESOURCE_ID: l'ID risorsa dell'agente di cui è stato eseguito il deployment
  • REVISION_ID: l'ID univoco per una revisione specifica del runtime

REST

Chiama il metodo reasoningEngineRuntimeRevisions.delete.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo Google Cloud ID progetto
  • LOCATION: una regione supportata
  • RESOURCE_ID: l'ID risorsa dell'agente di cui è stato eseguito il deployment
  • REVISION_ID: l'ID univoco per una revisione specifica del runtime

Metodo HTTP e URL: 

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

Per inviare la richiesta, espandi una di queste opzioni:

 

Limitazioni

  • Agent Gateway non è supportato per gli agenti Agent Runtime che utilizzano le revisioni. Non potrai utilizzare le funzionalità correlate al controllo delle versioni, come la configurazione della suddivisione del traffico e le query per revisione, se un Agent Gateway è collegato alla configurazione di un agente.