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 en savoir plus sur la création de révisions, consultez Révisions et états.

Si vous n'avez pas encore créé de révisions, vous devrez le faire 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 la répartition 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 peut avoir les états suivants :

  • Active : la révision est disponible pour les requêtes. Notez qu'il peut ne recevoir aucune requête, en fonction de la configuration du trafic.
  • Obsolète : il est impossible d'interroger la révision.

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.

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 nouvelle 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é, qu'elles soient actives ou obsolètes.

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

Console

  1. Dans Google Agent Platform, accédez à Gouvernance > Déploiements.

    Accéder à la page "Déploiements"

  2. Cliquez sur le nom de l'agent.

  3. Sélectionnez l'onglet Révisions.

  4. En haut de la page, les informations suivantes sur les révisions sont affichées :

    1. Mode fractionné : peut être "Manuel" ou "Dernier". Pour en savoir plus, consultez "Gérer le trafic vers les révisions".
    2. Révisions actives : nombre de révisions actives par rapport au nombre total de révisions.
    3. Dernière révision : nom de la dernière révision et pourcentage du trafic qu'elle reçoit.
    4. Révision principale : nom de la révision principale, qui reçoit la majeure partie du trafic.

  5. La liste affiche toutes les révisions de l'agent et inclut les informations suivantes :

    1. Nom : nom ou numéro de la révision.
    2. État : indique si la révision est déployée ou obsolète.
    3. Trafic : pourcentage du trafic acheminé vers la révision.
    4. Créé : date et heure de création de la révision.

SDK Agent Platform

Le code suivant liste l'historique des révisions d'un agent déployé spécifique. Pour lister les révisions, vous devez identifier l'ID de ressource unique de votre agent.

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)

Remplacez les variables suivantes dans le code :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : une région compatible
  • RESOURCE_ID : ID de ressource de l'agent déployé

REST

Appelez la méthode reasoningEngineRuntimeRevisions.list.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : une région compatible
  • RESOURCE_ID : ID de ressource de l'agent déployé.

Méthode HTTP et URL : 

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

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

SDK Agent Platform

Le code suivant récupère les détails des ressources pour une révision d'agent déployée spécifique :

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)

Remplacez les variables suivantes dans le code :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : une région compatible
  • RESOURCE_ID : ID de ressource de l'agent déployé
  • REVISION_ID : ID unique d'une révision d'exécution spécifique

REST

Appelez la méthode reasoningEngineRuntimeRevisions.get .

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : une région compatible
  • RESOURCE_ID : ID de ressource de l'agent déployé
  • REVISION_ID : ID unique d'une révision d'exécution spécifique

Méthode HTTP et URL : 

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

{
  "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 seule la répartition du trafic s'applique aux requêtes adressées à la ressource racine reasoningEngine. Si vous dirigez 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 nombre 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.

Console

Pour configurer la gestion du trafic :

  1. Accédez à Gouverner > Déploiements.

    Accéder à la page "Déploiements"

  2. Cliquez sur le nom de l'agent.

  3. Accédez à l'onglet Révisions.

  4. Sur la page des détails des révisions, cliquez sur Gérer le trafic.

  5. Sous Mode fractionné, sélectionnez l'une des options suivantes :

    1. Manuel : spécifiez le pourcentage de trafic à allouer à chaque révision.
    2. Toujours la dernière : dans ce cas, 100% du trafic est dirigé vers la dernière révision (celle qui a été créée le plus récemment).

  6. Sélectionnez Enregistrer pour enregistrer vos modifications.

SDK Agent Platform

Le code suivant montre un exemple de configuration de la répartition du trafic en pourcentage.

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

Remplacez les variables suivantes dans le code :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : une région compatible
  • RESOURCE_ID : ID de ressource de l'agent déployé
  • REVISION_ID_1 : ID de révision de la première révision
  • REVISION_ID_2 : ID de révision de la deuxième révision

REST

Pour configurer le trafic afin qu'il soit toujours dirigé vers la dernière révision (par défaut), mettez à jour la ressource ReasoningEngine avec le champ traffic_config et spécifiez trafficSplitAlwaysLatest :

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

Pour répartir le trafic entre les révisions d'exécution d'un agent, mettez à jour la ressource ReasoningEngine avec le champ traffic_config et fournissez une liste des cibles de trafic avec leurs pourcentages respectifs. L'exemple suivant montre comment définir le fractionnement manuel sur deux révisions.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : une région compatible
  • RESOURCE_ID : ID de ressource de l'agent déployé
  • REVISION_ID_1 : ID de révision de la première révision
  • REVISION_ID_2 : ID de révision de la deuxième révision
  • TRAFFIC_PERCENTAGE_1 : pourcentage du flux de trafic souhaité pour la première révision
  • TRAFFIC_PERCENTAGE_2 : pourcentage du flux de trafic que vous souhaitez pour la deuxième révision

Méthode HTTP et URL : 

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

Cette requête lance une opération de longue durée (LRO). Au début, vous recevrez une réponse d'opération standard. Une fois les modifications de configuration terminées, la réponse affiche done et répète vos paramètres de configuration. 
{
  "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.

SDK Agent Platform

Le code suivant interroge une révision active spécifique :

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)

Remplacez les variables suivantes dans le code :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : une région compatible
  • RESOURCE_ID : ID de ressource de l'agent déployé
  • REVISION_ID : ID unique d'une révision d'exécution spécifique

REST

Appelez la méthode reasoningEngineRuntimeRevisions.query.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : une région compatible
  • RESOURCE_ID : ID de ressource de l'agent déployé
  • REVISION_ID : ID unique d'une révision d'exécution spécifique

Méthode HTTP et URL : 

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

Pour envoyer votre requête, développez l'une des options suivantes :

 

Surveiller les révisions

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

Modifier une révision

Mettez à jour les agents déployés en suivant les instructions de la section Mettre à jour un agent déployé. Vous pouvez mettre à jour les champs versionnés ou non versionnés. Si vous mettez à jour des champs avec gestion des versions, vous créez une révision.

Supprimer une révision d'agent

Vous pouvez supprimer une révision d'agent en la supprimant. Vous ne pouvez supprimer que les révisions qui ne sont pas actives pour la gestion du trafic, car elles sont obsolètes ou 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.

Console

Pour supprimer une révision d'un agent :

  1. Accédez à Gouverner > Déploiements.

    Accéder à la page "Déploiements"

  2. Cliquez sur le nom de l'agent.

  3. Accédez à l'onglet Révisions.

  4. Sur la page d'informations sur les révisions, cliquez sur le nom de la révision.

  5. Recherchez la ligne correspondant à la révision à supprimer.

  6. Cliquez sur l'icône Supprimer (corbeille).

  7. Lorsque vous y êtes invité, confirmez la suppression de la révision.

SDK Agent Platform

Le code suivant supprime une révision d'agent spécifiée :

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

Remplacez les variables suivantes dans le code :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : une région compatible
  • RESOURCE_ID : ID de ressource de l'agent déployé
  • REVISION_ID : ID unique d'une révision d'exécution spécifique

REST

Appelez la méthode reasoningEngineRuntimeRevisions.delete.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

  • PROJECT_ID : ID de votre projet Google Cloud
  • LOCATION : une région compatible
  • RESOURCE_ID : ID de ressource de l'agent déployé
  • REVISION_ID : ID unique d'une révision d'exécution spécifique

Méthode HTTP et URL : 

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

Pour envoyer votre requête, développez l'une des options suivantes :

 

Limites

  • Agent Gateway n'est pas compatible avec les agents Agent Runtime qui utilisent des révisions. Vous ne pourrez pas utiliser les fonctionnalités liées au versionnement, telles que la configuration de la répartition du trafic et les requêtes par révision, si une passerelle Agent Gateway est associée à la configuration d'un agent.