Migrer vers un nouveau modèle

Ce document explique comment migrer une application d'agent CX Agent Studio existante vers un autre modèle de fondation, valider la qualité de l'agent et déployer la configuration mise à jour par étapes sans perturber le trafic de production en direct.

Présentation du workflow de migration

Une migration de modèle complète se déroule en quatre étapes :

  1. Isolez vos modifications : créez une version immuable de votre application d'agent de production, ou exportez et importez l'application dans un environnement de test distinct.
  2. Mettre à jour les paramètres du modèle : modifiez le modèle global, examinez les remplacements de modèles de sous-agents et d'outils, et vérifiez les paramètres de nouvelle tentative et de remplacement à l'aide de la console, des fichiers de configuration exportés ou de l'API REST.
  3. Évaluer et affiner les performances : testez les conversations dans le simulateur, exécutez des évaluations avec Détecter les problèmes avec l'IA et utilisez AI Co-Builder: Arc pour ajuster les instructions jusqu'à ce que vos métriques de qualité atteignent les seuils cibles.
  4. Déployer par étapes : enregistrez la configuration validée en tant que version et utilisez la répartition du trafic sur votre canal de déploiement pour déplacer progressivement le trafic en direct tout en surveillant les résultats.

Étape 1 : Isoler vos modifications

Avant de modifier les paramètres du modèle, isolez votre travail afin que les mises à jour et les tests n'affectent pas les conversations en direct avec les clients. Vous pouvez isoler les modifications en utilisant des versions au sein de la même application d'agent ou en exportant l'application vers un environnement de bac à sable distinct.

Utiliser des versions dans la même application d'agent

Lorsque vos canaux de déploiement pointent vers une version immuable spécifique, les modifications que vous apportez à l'application de l'agent brouillon n'affectent pas le trafic en ligne tant que vous n'avez pas créé de version et que vous ne l'avez pas attribuée à un canal de déploiement.

Pour enregistrer un instantané de référence de votre configuration actuelle :

  1. Ouvrez la console CX Agent Studio et sélectionnez votre application d'agent.
  2. Ouvrez le volet Versions dans Agent Builder.
  3. Cliquez sur + Créer une version.
  4. Saisissez un nom descriptif, tel que pre-model-migration-baseline, et une description facultative, puis cliquez sur Créer.
  5. Ouvrez l'onglet Déployer et vérifiez que vos canaux de déploiement actifs pointent vers une version immuable (indiquée par un badge En ligne dans le volet Versions) plutôt que vers le brouillon modifiable.

Exporter et importer vers un environnement de bac à sable

Si vous préférez tester les modifications du modèle dans un projet ou une application de préproduction distincts, exportez votre application d'agent et importez-la dans votre environnement de test :

  1. Ouvrez la console CX Agent Studio et sélectionnez votre projet.
  2. Dans la liste des applications de l'agent, ouvrez le menu de votre application, puis sélectionnez Exporter.
  3. Si votre environnement de bac à sable utilise des dépendances externes différentes, telles que des datastores ou des points de terminaison de service, extrayez l'archive téléchargée, mettez à jour le fichier environment.json et compressez le répertoire dans une archive ZIP. Pour en savoir plus, consultez Fichier d'environnement.
  4. Dans votre projet de bac à sable ou votre application de test, ouvrez le menu de l'application, sélectionnez Importer, puis importez l'archive.
  5. Facultatif : Exportez vos scénarios de test d'évaluation depuis l'application source et importez-les dans l'application de bac à sable afin de pouvoir exécuter des tests de régression.

Étape 2 : Mettre à jour les paramètres du modèle

Consultez la liste des modèles compatibles pour choisir un modèle Gemini cible qui correspond à la modalité de votre agent (texte ou voix). Vous pouvez modifier les paramètres du modèle à l'aide de la console, de fichiers de configuration exportés ou de l'API REST.

Mettre à jour des modèles à l'aide de la console

Lorsque vous migrez une application d'agent dans la console, vérifiez le modèle d'application global, les remplacements d'agent individuels, les modèles d'outils de data store et les paramètres de remplacement :

  1. Modifier le modèle global :
    1. Dans le générateur d'agents, ouvrez Paramètres pour afficher les paramètres de l'application de l'agent.
    2. Sous De base > Interactions, sélectionnez votre modèle cible dans le champ Modèle global. Ce modèle sert de modèle par défaut pour tous les agents de l'application qui ne spécifient pas de forçage.
  2. Vérifiez les remplacements de modèle de l'agent racine et des sous-agents :
    1. Dans Agent Builder, ouvrez le menu dans la barre de titre de l'agent racine, puis sélectionnez Modifier la configuration pour afficher les paramètres de l'agent.
    2. Vérifiez le champ Modèle. Si l'agent remplace le modèle global, sélectionnez votre modèle cible ou effacez le remplacement pour que l'agent hérite du modèle global.
    3. Répétez cette vérification pour chaque sous-agent de la hiérarchie de votre agent.
  3. Vérifier les modèles d'outils de datastore :
    1. Si votre application utilise des outils de datastore, ouvrez le panneau Outils et sélectionnez chaque outil de data store.
    2. Développez Avancé > Modalités, puis vérifiez les sélections Modèle de réécriture et Modèle de résumé pour les configurations Texte et Voix.
  4. Vérifiez les paramètres de nouvelle tentative et de remplacement :
    1. Ouvrez les paramètres de l'application de l'agent, puis accédez à De base > Comportement > Comportement de remplacement.
    2. Vérifiez que les options Nouvelles tentatives, Réponse de l'agent et Remplacement sont configurées de manière appropriée pour la gestion des exceptions lors de la génération du modèle.

Mettre à jour des modèles à l'aide de fichiers de configuration exportés

Si vous gérez votre application d'agent via un contrôle des versions ou des pipelines CI/CD, vous pouvez mettre à jour les paramètres du modèle dans l'archive exportée et réimporter le package :

  1. Extrayez l'archive ZIP de l'application de l'agent exportée.

  2. Pour chaque répertoire d'agent sous agents/<var>AGENT_NAME</var>/, ouvrez le fichier agents/<var>AGENT_NAME</var>/<var>AGENT_NAME</var>.yaml et remplacez le champ modelSettings.model par l'ID du modèle cible :

    displayName: "AGENT_NAME"
modelSettings:
  model: "MODEL_ID"
instruction: "agents/AGENT_NAME/instruction.txt"

    Remplacez les éléments suivants :

    • <var>AGENT_NAME</var> : nom à afficher de l'agent.
    • <var>MODEL_ID</var> : identifiant du modèle cible, tel que gemini-3.5-flash ou gemini-composite-v2.

  3. Compressez le répertoire racine dans une archive ZIP et importez l'archive mise à jour dans CX Agent Studio.

Mettre à jour des modèles à l'aide de l'API REST

Vous pouvez mettre à jour ModelSettings de manière programmatique sur votre application d'agent et sur des agents individuels à l'aide de l'API REST CX Agent Studio.

Avant d'appeler l'API, rassemblez les valeurs suivantes :

  • <var>PROJECT_ID</var> : ID de votre projet Google Cloud .
  • <var>LOCATION_ID</var> : région de votre application d'agent, par exemple us ou eu.
  • <var>APP_ID</var> : ID de ressource de votre application d'agent.
  • <var>AGENT_ID</var> : ID de ressource d'un agent racine ou d'un sous-agent spécifique.
  • <var>MODEL_ID</var> : identifiant du modèle cible, tel que gemini-3.5-flash.

Pour mettre à jour le modèle global par défaut de l'application de l'agent, envoyez une requête PATCH à la méthode projects.locations.apps.patch avec updateMask=modelSettings :

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID?updateMask=modelSettings" \
  -d '{
    "modelSettings": {
      "model": "MODEL_ID"
    }
  }'

Pour mettre à jour le remplacement de modèle sur un agent racine ou un sous-agent individuel, envoyez une requête PATCH à la méthode projects.locations.apps.agents.patch avec updateMask=modelSettings :

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID/agents/AGENT_ID?updateMask=modelSettings" \
  -d '{
    "modelSettings": {
      "model": "MODEL_ID"
    }
  }'

Étape 3 : Évaluer et affiner les performances de l'agent

Les modèles de fondation peuvent différer en termes de style de raisonnement, de respect des instructions, de niveau de détail et de comportement d'appel d'outil. Après avoir changé de modèle, testez votre agent et affinez ses instructions avant d'acheminer le trafic client en direct vers la configuration mise à jour.

Tester de manière interactive dans le simulateur

Exécutez des vérifications initiales de l'intégrité dans le simulateur de l'agent de prévisualisation :

  1. Ouvrez le simulateur dans Agent Builder, puis cliquez sur Démarrer une nouvelle conversation.
  2. Testez des interactions textuelles ou audio représentatives et vérifiez que l'agent suit les instructions, appelle les outils avec des arguments valides et passe d'un sous-agent à l'autre comme prévu.
  3. Développez les détails de la trace pour chaque tour afin d'inspecter la latence des étapes, les entrées et sorties des outils, ainsi que les réponses JSON brutes.
  4. Facultatif : Pour ajouter une conversation à votre suite de régression, ouvrez le menu du simulateur et sélectionnez Enregistrer en tant que golden.

Exécuter des évaluations et diagnostiquer les problèmes avec l'IA

Utilisez les évaluations pour mesurer les performances de vos scénarios de test de référence, de scénario et de simulation, et comparez les résultats à votre version de référence :

  1. Cliquez sur Évaluer en haut du générateur d'agent.
  2. Sélectionnez les scénarios de test qui couvrent vos parcours utilisateur critiques et vos variantes d'agent, puis cliquez sur Exécuter la sélection.
  3. Dans la boîte de dialogue d'exécution, sélectionnez Identifier les problèmes avec l'IA, définissez le nombre d'exécutions sur 3 ou plus pour une analyse optimale de l'IA, puis lancez l'exécution. Pour en savoir plus, consultez Utiliser l'IA pour améliorer les scénarios de test.
  4. Une fois l'exécution terminée, examinez les métriques d'évaluation, y compris l'exactitude de l'outil, la correspondance sémantique, la satisfaction de l'objectif de l'utilisateur, les objectifs réalisés, les hallucinations et l'accomplissement de la tâche, et inspectez les tours ayant échoué ou les objectifs non atteints.
  5. Sur la page des résultats, cliquez sur Demander à Gemini pour examiner le loss_report généré, résumer les causes principales des exécutions ayant échoué et afficher les corrections d'instructions ou de configuration suggérées.

Instructions pour la course de côte avec le Co-Builder IA : Arc

Si les résultats de votre évaluation montrent des régressions ou des changements de comportement sous le modèle cible, utilisez AI Co-Builder: Arc et l'assistant d'évaluation pour affiner vos requêtes de manière itérative :

  1. Cliquez sur Arc en haut du générateur d'agents pour ouvrir AI Co-Builder.
  2. Cliquez sur Sélectionner le contexte, puis sélectionnez les agents ou les instructions spécifiques à ajuster, ou joignez les transcriptions ayant échoué et les rapports de perte.
  3. Demandez à Arc de mettre à jour vos instructions ou les descriptions des outils pour corriger les échecs observés, tout en préservant le comportement dans les autres scénarios de test. Vous pouvez également utiliser la fonctionnalité Restructurer les instructions pour organiser les instructions dans un format structuré.
  4. Réexécutez votre suite d'évaluation après avoir appliqué les corrections et répétez l'opération jusqu'à ce que tous les scénarios de test répondent à vos critères de réussite. Pour en savoir plus, consultez Évaluations et bonnes pratiques d'optimisation.

Étape 4 : Déployer par étapes avec la répartition du trafic

Une fois que votre agent mis à jour a réussi les évaluations, déployez-le progressivement à l'aide des versions et de la répartition du trafic de déploiement.

Créer une version pour l'agent migré

Enregistrez un instantané immuable de votre configuration validée :

  1. Si vous avez testé les modifications dans une application de bac à sable distincte, exportez le package d'application validé et importez-le dans votre application de production.
  2. Dans votre application de production, ouvrez le volet Versions, puis cliquez sur + Créer une version.
  3. Saisissez un nom et une description qui identifient le modèle cible, par exemple v2-gemini-3-5-flash, puis cliquez sur Créer.

Basculer progressivement le trafic en direct

Utilisez la répartition du trafic pour acheminer un faible pourcentage de conversations en direct vers la version migrée avant de la promouvoir à 100 % du trafic :

  1. Cliquez sur l'onglet Déployer en haut du générateur d'agent, puis sélectionnez votre canal de déploiement.
  2. Sous Version de l'agent, cliquez sur Ajouter une version et incluez votre version en production de référence et votre version candidate migrée.
  3. Attribuez un faible pourcentage de trafic initial à la version candidate (par exemple, 90 % pour la version de référence et 10 % pour la version candidate, soit un total de 100 %), puis enregistrez la configuration du canal. Vous pouvez également configurer experimentConfig.versionRelease.trafficAllocations de manière programmatique à l'aide de l'API REST.
  4. Surveillez les performances en direct des différentes versions :
  5. Une fois que vous avez confirmé la stabilité et la qualité, augmentez progressivement le pourcentage de trafic pour la version migrée jusqu'à ce qu'elle diffuse 100 % du trafic en ligne. Si vous détectez des problèmes inattendus lors du déploiement, redirigez 100 % du trafic vers la version de référence ou restaurez la version précédente dans le volet Versions.