Gérer les révisions et le trafic

Dans Gemini Enterprise Agent Platform, vous pouvez créer des versions immuables, ou révisions, d'un agent. Vous pouvez ensuite répartir le trafic entre les différentes révisions actives. La répartition du trafic vous permet de tester de nouvelles révisions et d'augmenter progressivement le trafic vers celles-ci, ou de répartir le trafic entre les révisions à d'autres fins.

La possibilité de créer des révisions est toujours activée. Vous n'avez pas besoin d'activer la fonctionnalité. Pour savoir comment créer des révisions, consultez Révisions et états.

Si vous n'avez pas encore créé de révisions, vous devrez en créer avant de pouvoir les afficher et configurer le trafic entre elles, comme décrit sur cette page.

Pour le moment, les révisions et la répartition du trafic sont disponibles via l'API v1beta1.

Cette page explique comment gérer les révisions d'agents et le fractionnement du trafic.

Révisions et états

Une révision est un instantané d'un agent. Lorsque vous créez un agent ou mettez à jour ses champs versionnés, une révision immuable de l'agent est créée. Une révision est active lorsqu'elle est disponible pour les requêtes. Notez qu'il est possible qu'il ne reçoive aucune requête, selon la configuration du trafic. Lorsqu'une révision est archivée, elle est définitivement retirée de la diffusion du trafic et ne peut pas être restaurée. Les révisions archivées ne sont conservées qu'à des fins de référence historique.

Vous pouvez identifier une révision à l'aide de son nom de ressource, que vous pouvez trouver en listant les révisions de l'agent.

Limites de révision

Les révisions archivées n'occupent plus d'emplacement de révision. La modification d'une liaison Agent Gateway archive toutes les révisions préexistantes (voir Agent Gateway et révisions). Par conséquent, une modification de liaison libère du quota au lieu d'en consommer. Les révisions archivées peuvent toujours être supprimées.

Champs versionnés et non versionnés

Cette section liste les champs de la définition ReasoningEngineSpec d'un agent déployé que vous pouvez mettre à jour pour créer une révision de l'agent.

Lorsque vous mettez à jour des champs avec gestion des versions,une révision est créée.

Lorsque vous mettez à jour des champs sans version ou des champs de la définition d'un agent autres que les champs avec version, l'agent est mis à jour dans toutes ses révisions.

Voici les champs versionnés :

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

Lister les révisions d'un agent

Vous pouvez lister toutes les révisions d'un agent déployé.

Pour trouver l'ID de ressource de votre agent, consultez Obtenir l'ID de ressource de l'agent.

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

Obtenir les détails d'une révision

Vous pouvez récupérer les détails d'une révision spécifique.

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

Configurer la répartition du trafic entre les révisions

Vous pouvez gérer la répartition du trafic entre les révisions actives. Notez que seules les requêtes adressées à la ressource racine reasoningEngine sont soumises à la répartition du trafic. En dirigeant une requête vers un chemin d'accès à une ressource de révision spécifique, vous contournez explicitement les règles de trafic.

Le trafic est distribué à l'aide de l'une des deux méthodes suivantes :

• Par pourcentage : lorsque vous configurez le routage par pourcentage, un pourcentage spécifié du trafic est dirigé vers chaque révision d'agent. Chaque pourcentage spécifié doit être un entier. La somme des pourcentages doit être égale à 100%. Même s'il n'y a qu'une seule révision active, vous pouvez toujours configurer la répartition du trafic (où 100% du trafic est redirigé).
• Vers la révision la plus récente : tout le trafic est dirigé vers la dernière révision. Lorsqu'une révision d'agent est créée, le trafic est automatiquement redirigé vers cette nouvelle révision.

Une division manuelle ne peut cibler que les révisions actives. Nommer une révision archivée renvoie 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
}

Interroger une révision spécifique

Vous pouvez interroger une révision spécifique via le SDK ou les API. La révision doit être active pour pouvoir être interrogée. Les requêtes directes adressées à une révision spécifique contournent les règles de répartition du trafic.

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 et révisions

Lorsque vous associez, modifiez ou dissociez une liaison Agent Gateway sur un agent, une révision est créée et toutes les révisions existantes avant la modification sont archivées. Seule la nouvelle révision reste active. Cette action est irréversible. Les révisions archivées ne peuvent pas être restaurées.

Étant donné qu'une modification de liaison archive toutes les révisions existantes, elle n'est autorisée que lorsque tout le trafic est déjà sur la dernière révision. L'API refuse la modification si une répartition manuelle est définie, même si elle place 100% du trafic sur la dernière révision. Le refus renvoie 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.

Pour modifier la passerelle sur un agent qui utilise une répartition manuelle du trafic :

1. Passez au routage "toujours la dernière version" en définissant traffic_config.traffic_split_always_latest (ou en effaçant traffic_config). Consultez Configurer la répartition du trafic entre les révisions.
2. Modifiez spec.deployment_spec.agent_gateway_config. La nouvelle révision est alors créée et toutes les précédentes sont archivées.
3. Si vous avez de nouveau besoin d'une division manuelle, créez-la à partir des révisions créées après la modification de l'association.

Les révisions archivées restent accessibles via l'API et leur ReasoningEngineSpec complet est conservé. Pour créer une révision équivalente à une révision archivée, récupérez les détails de la révision archivée et déployez une nouvelle révision avec les mêmes champs versionnés. La réutilisation du même URI d'image de conteneur reproduit le même environnement d'exécution. La réutilisation du même emplacement de code source et des mêmes méthodes de classe reproduit le même comportement.

Surveiller les révisions

Surveillez les révisions pour détecter les activités et les problèmes en suivant le numéro de révision en tant que métadonnées dans les journaux. Pour savoir comment configurer la journalisation, consultez Configurer la journalisation.

Créer une révision d'agent

Pour créer une révision, vous devez mettre à jour les champs versionnés d'un agent déployé. Pour obtenir des instructions, consultez Mettre à jour un agent déployé.

Si vous mettez à jour des champs avec gestion des versions, une révision est automatiquement créée. Si vous mettez à jour des champs sans version, l'agent est mis à jour dans toutes ses révisions existantes sans en créer une.

Gérer le nettoyage des révisions

Gemini Enterprise Agent Platform supprime automatiquement les anciennes révisions pour vous aider à respecter les limites de révisions. Vous pouvez également supprimer manuellement des révisions.

Récupération automatique de mémoire

Par défaut, Gemini Enterprise Agent Platform active la récupération de mémoire automatique pour tous les agents. Vous ne pouvez pas le désactiver. La récupération de mémoire ne s'exécute que dans le cadre d'une opération de mise à jour de l'agent. Elle ne s'exécute pas en tant que job en arrière-plan.

• Quand s'exécute-t-il ? Si une opération de mise à jour tente de dépasser la limite de révisions configurée, Gemini Enterprise Agent Platform supprime les révisions éligibles les plus anciennes lors de la même opération avant de créer la nouvelle révision. Si vous réduisez la limite, Gemini Enterprise Agent Platform supprime immédiatement les révisions éligibles les plus anciennes jusqu'à atteindre la nouvelle limite.
• Révisions éligibles : une révision ne peut être supprimée que si elle remplit toutes les conditions suivantes :
  • Il est dans l'état ACTIVE.
  • Elle n'est pas incluse dans la configuration du trafic (elle reçoit 0% du trafic).
• Échecs : si le nombre de révisions éligibles n'est pas suffisant pour libérer de l'espace, Gemini Enterprise Agent Platform rejette l'opération de mise à jour avec une erreur FAILED_PRECONDITION. Cette opération ne supprime aucune révision et n'en crée pas. Vous devez supprimer des révisions de la configuration du trafic ou augmenter la limite avant de réessayer.

Configurer la limite

La limite est définie par le champ revision_garbage_collection_strategy.keep_n_latest.max_revisions de l'agent. Vous pouvez définir ce champ lorsque vous créez l'agent ou le modifier ultérieurement à l'aide d'une requête de mise à jour.

• Par défaut pour les nouveaux agents : 100 révisions.
• Par défaut pour les agents existants : 950 révisions.
• Plage autorisée : de 1 à 950. Une valeur de 0 ou moins est refusée. Une valeur supérieure à 950 est refusée, car 950 est un quota fixe qui ne peut pas être augmenté.

Suppression manuelle

Vous pouvez supprimer manuellement une révision d'agent. Vous ne pouvez supprimer que les révisions qui ne sont pas actives pour la gestion du trafic, car elles ne sont pas configurées pour recevoir du trafic. Pour savoir comment configurer la réception de trafic par une révision, consultez Configurer la répartition du trafic entre les révisions.

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