Esegui la migrazione a un nuovo modello

Questo documento descrive come eseguire la migrazione di un'applicazione agente CX Agent Studio esistente a un modello foundation diverso, convalidare la qualità dell'agente ed eseguire il deployment della configurazione aggiornata in più fasi senza interrompere il traffico di produzione in tempo reale.

Panoramica del workflow di migrazione

Una migrazione completa del modello prevede quattro fasi:

  1. Isola le modifiche: crea una versione immutabile della tua applicazione agente di produzione o esporta e importa l'applicazione in un ambiente di test separato.
  2. Aggiorna le impostazioni del modello: modifica il modello globale, rivedi gli override del modello di agente secondario e dello strumento e verifica le impostazioni di nuovo tentativo e di fallback utilizzando la console, i file di configurazione esportati o l'API REST.
  3. Valuta e perfeziona le prestazioni: testa le conversazioni nel simulatore, esegui valutazioni con Trova problemi con l'AI e utilizza AI Co-Builder: Arc per ottimizzare le istruzioni finché le metriche di qualità non raggiungono le soglie target.
  4. Esegui il deployment in più fasi: salva la configurazione convalidata come versione e utilizza la suddivisione del traffico sul tuo canale di deployment per spostare gradualmente il traffico in tempo reale mentre monitori i risultati.

Passaggio 1: isola le modifiche

Prima di modificare le impostazioni del modello, isola il tuo lavoro in modo che gli aggiornamenti e i test non influiscano sulle conversazioni in tempo reale con i clienti. Puoi isolare le modifiche utilizzando le versioni all'interno della stessa applicazione dell'agente o esportando l'applicazione in un ambiente sandbox separato.

Utilizza le versioni nella stessa applicazione agente

Quando i canali di deployment puntano a una versione immutabile specifica, le modifiche apportate all'applicazione dell'agente bozza non influiscono sul traffico in tempo reale finché non crei una versione e la assegni a un canale di deployment.

Per salvare uno snapshot di riferimento della configurazione attuale:

  1. Apri la console CX Agent Studio e seleziona l'applicazione dell'agente.
  2. Apri il riquadro Versioni in Agent Builder.
  3. Fai clic su + Crea versione.
  4. Inserisci un nome descrittivo, ad esempio pre-model-migration-baseline, e una descrizione facoltativa, quindi fai clic su Crea.
  5. Apri la scheda Esegui il deployment e verifica che i canali di deployment attivi puntino a una versione immutabile (indicata da un badge Pubblicata nel riquadro Versioni) anziché alla bozza modificabile.

Esporta e importa in un ambiente sandbox

Se preferisci testare le modifiche al modello in un progetto o un'applicazione di gestione temporanea separati, esporta l'applicazione dell'agente e importala nell'ambiente di test:

  1. Apri la console CX Agent Studio e seleziona il tuo progetto.
  2. Nell'elenco delle applicazioni dell'agente, apri il menu dell'applicazione, quindi seleziona Esporta.
  3. Se l'ambiente sandbox utilizza dipendenze esterne diverse, ad esempio datastore o endpoint di servizio, estrai l'archivio scaricato, aggiorna il file environment.json e comprimi la directory in un file ZIP. Per saperne di più, consulta File di ambiente.
  4. Nel progetto sandbox o nell'applicazione di test, apri il menu dell'applicazione, seleziona Importa e carica l'archivio.
  5. (Facoltativo) Esporta gli scenari di test di valutazione dall'applicazione di origine e importali nell'applicazione sandbox in modo da poter eseguire test di regressione.

Passaggio 2: aggiorna le impostazioni del modello

Consulta l'elenco dei modelli supportati per scegliere un modello Gemini di destinazione che corrisponda alla modalità dell'agente (testo o voce). Puoi aggiornare le impostazioni del modello utilizzando la console, i file di configurazione esportati o l'API REST.

Aggiorna i modelli utilizzando la console

Quando esegui la migrazione di un'applicazione agente nella console, controlla il modello di applicazione globale, gli override dei singoli agenti, i modelli di strumenti del datastore e le impostazioni di riserva:

  1. Modifica il modello globale:
    1. In Agent Builder, apri Impostazioni per visualizzare le impostazioni dell'applicazione dell'agente.
    2. In Base > Interazioni, seleziona il modello target nel campo Modello globale. Questo modello funge da impostazione predefinita per tutti gli agenti nell'applicazione che non specificano un override.
  2. Controlla gli override dei modelli root e sub-agente:
    1. In Agent Builder, apri il menu nella barra del titolo dell'agente principale e seleziona Modifica configurazione per visualizzare le impostazioni dell'agente.
    2. Controlla il campo Modello. Se l'agente esegue l'override del modello globale, seleziona il modello target o cancella l'override in modo che l'agente erediti il modello globale.
    3. Ripeti questo controllo per ogni agente secondario nella gerarchia degli agenti.
  3. Controlla i modelli di strumenti del datastore:
    1. Se la tua applicazione utilizza strumenti del datastore, apri il riquadro Strumenti e seleziona ogni strumento del datastore.
    2. Espandi Avanzate > Modalità e verifica le selezioni di Modello di riscrittura e Modello di riassunto per le configurazioni Testo e Voce.
  4. Controlla le impostazioni di nuovo tentativo e di riserva:
    1. Apri Impostazioni per l'applicazione dell'agente e vai a Base > Comportamento > Comportamento di riserva.
    2. Verifica che i tentativi, la risposta dell'agente e il fallback siano configurati in modo appropriato per la gestione degli errori durante la generazione del modello.

Aggiorna i modelli utilizzando i file di configurazione esportati

Se gestisci l'applicazione dell'agente tramite il controllo della versione o le pipeline CI/CD, puoi aggiornare le impostazioni del modello nell'archivio esportato e reimportare il pacchetto:

  1. Estrai il file ZIP dell'applicazione dell'agente esportata.

  2. Per ogni directory dell'agente in agents/<var>AGENT_NAME</var>/, apri il file agents/<var>AGENT_NAME</var>/<var>AGENT_NAME</var>.yaml e aggiorna il campo modelSettings.model con l'ID del modello di destinazione:

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

    Sostituisci quanto segue:

    • <var>AGENT_NAME</var>: il nome visualizzato dell'agente.
    • <var>MODEL_ID</var>: l'identificatore del modello di destinazione, ad esempio gemini-3.5-flash o gemini-composite-v2.

  3. Comprimi la directory root in un file ZIP e importa l'archivio aggiornato in CX Agent Studio.

Aggiorna i modelli utilizzando l'API REST

Puoi aggiornare in modo programmatico ModelSettings sulla tua applicazione agente e sui singoli agenti utilizzando l'API REST CX Agent Studio.

Prima di chiamare l'API, raccogli i seguenti valori:

  • <var>PROJECT_ID</var>: il tuo ID progetto Google Cloud .
  • <var>LOCATION_ID</var>: la regione della tua applicazione agente, ad esempio us o eu.
  • <var>APP_ID</var>: l'ID risorsa della tua applicazione agente.
  • <var>AGENT_ID</var>: l'ID risorsa di un agente principale o secondario specifico.
  • <var>MODEL_ID</var>: l'identificatore del modello di destinazione, ad esempio gemini-3.5-flash.

Per aggiornare il modello globale predefinito per l'applicazione dell'agente, invia una richiesta PATCH al metodo projects.locations.apps.patch con 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"
    }
  }'

Per aggiornare l'override del modello su un singolo agente principale o secondario, invia una richiesta PATCH al metodo projects.locations.apps.agents.patch con 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"
    }
  }'

Passaggio 3: valuta e perfeziona le prestazioni dell'agente

I foundation model possono differire per stile di ragionamento, rispetto delle istruzioni, livello di dettaglio e comportamento di chiamata allo strumento. Dopo aver cambiato modello, testa l'agente e perfeziona le istruzioni prima di indirizzare il traffico dei clienti in tempo reale alla configurazione aggiornata.

Esegui test interattivi nel simulatore

Esegui i controlli di integrità iniziali nel simulatore Anteprima agente:

  1. Apri il simulatore in Agent Builder e fai clic su Avvia nuova conversazione.
  2. Testa le interazioni di testo o audio rappresentative e verifica che l'agente segua le istruzioni, richiami gli strumenti con argomenti validi e passi da un sottoagente all'altro come previsto.
  3. Espandi i dettagli della traccia per ogni turno per esaminare la latenza dei passaggi, gli input e gli output degli strumenti e le risposte JSON non elaborate.
  4. (Facoltativo) Per aggiungere una conversazione alla suite di regressione, apri il menu del simulatore e seleziona Salva come golden.

Esegui valutazioni e diagnostica i problemi con l'AI

Utilizza le valutazioni per misurare le prestazioni degli scenari di test golden, scenario e simulazione e confronta i risultati con la versione di riferimento:

  1. Fai clic su Valuta nella parte superiore di Agent Builder.
  2. Seleziona gli scenari di test che coprono i tuoi Critical User Journey e le varianti dell'agente, quindi fai clic su Esegui selezionati.
  3. Nella finestra di dialogo di esecuzione, seleziona Trova problemi con l'AI, imposta il numero di esecuzioni su 3 o più per un'analisi AI ottimale, quindi avvia l'esecuzione. Per saperne di più, consulta Utilizza l'AI per migliorare gli scenari di test.
  4. Al termine dell'esecuzione, esamina le metriche di valutazione, tra cui correttezza dello strumento, corrispondenza semantica, soddisfazione degli obiettivi dell'utente, completamento obiettivo, allucinazioni e completamento attività, e ispeziona eventuali turni non riusciti o obiettivi non completati.
  5. Nella pagina dei risultati, fai clic su Chiedi a Gemini per esaminare il loss_report generato, riassumere le cause principali delle esecuzioni non riuscite e visualizzare le correzioni suggerite per le istruzioni o la configurazione.

Istruzioni per l'hill climbing con AI Co-Builder: Arc

Se i risultati della valutazione mostrano regressioni o modifiche del comportamento nel modello di destinazione, utilizza AI Co-Builder: Arc e l'assistente alla valutazione per perfezionare i prompt in modo iterativo:

  1. Fai clic su Arc nella parte superiore di Agent Builder per aprire AI Co-Builder.
  2. Fai clic su Seleziona contesto e seleziona gli agenti o le istruzioni specifici che richiedono modifiche oppure allega trascrizioni non riuscite e report sulle perdite.
  3. Chiedi ad Arc di aggiornare le tue istruzioni o le descrizioni degli strumenti per risolvere gli errori osservati, preservando al contempo il comportamento negli altri scenari di test. Puoi anche utilizzare la funzionalità di ristrutturazione delle istruzioni per organizzare le istruzioni in un formato strutturato.
  4. Esegui di nuovo la suite di valutazione dopo aver applicato le correzioni e ripeti l'operazione finché tutti gli scenari di test non soddisfano i criteri di superamento. Per ulteriori indicazioni, consulta le best practice per le valutazioni e l'hillclimbing.

Passaggio 4: esegui il deployment in più fasi con la suddivisione del traffico

Una volta che l'agente aggiornato supera le valutazioni, implementalo gradualmente utilizzando le versioni e la suddivisione del traffico di deployment.

Crea una versione per l'agente di cui è stata eseguita la migrazione

Salva uno snapshot immutabile della configurazione convalidata:

  1. Se hai testato le modifiche in un'applicazione sandbox separata, esporta il pacchetto dell'applicazione convalidato e importalo nell'applicazione di produzione.
  2. Nell'applicazione di produzione, apri il riquadro Versioni e fai clic su + Crea versione.
  3. Inserisci un nome e una descrizione che identificano il modello di destinazione, ad esempio v2-gemini-3-5-flash, quindi fai clic su Crea.

Sposta gradualmente il traffico in tempo reale

Utilizza la suddivisione del traffico per indirizzare una piccola percentuale di conversazioni live alla versione di cui è stata eseguita la migrazione prima di promuoverla al 100% del traffico:

  1. Fai clic sulla scheda Esegui il deployment nella parte superiore di Agent Builder e seleziona il canale di deployment.
  2. In Versione agente, fai clic su Aggiungi versione e includi sia la versione di produzione di riferimento sia la versione candidata di cui è stata eseguita la migrazione.
  3. Assegna una piccola percentuale di traffico iniziale alla versione candidata (ad esempio, 90% per la versione di riferimento e 10% per la versione candidata, per un totale del 100%), quindi salva la configurazione del canale. Puoi anche configurare experimentConfig.versionRelease.trafficAllocations in modo programmatico utilizzando l'API REST.
  4. Monitora il rendimento in tempo reale tra le versioni:
  5. Man mano che confermi la stabilità e la qualità, aumenta gradualmente la percentuale di traffico per la versione di cui è stata eseguita la migrazione fino a quando non gestisce il 100% del traffico in tempo reale. Se rilevi problemi imprevisti durante l'implementazione, indirizza il 100% del traffico alla versione di riferimento o ripristina la versione precedente nel riquadro Versioni.