Migra a un modelo nuevo

En este documento, se describe cómo migrar una aplicación de agente de CX Agent Studio existente a un modelo de base diferente, validar la calidad del agente y, luego, implementar la configuración actualizada en etapas sin interrumpir el tráfico de producción en vivo.

Descripción general del flujo de trabajo de migración

Una migración de modelo completa consta de cuatro etapas:

  1. Aísla tus cambios: Crea una versión inmutable de tu aplicación de agente de producción o exporta e importa la aplicación a un entorno de pruebas independiente.
  2. Actualiza la configuración del modelo: Cambia el modelo global, revisa las anulaciones del modelo de subagente y herramienta, y verifica la configuración de reintentos y resguardo con la consola, los archivos de configuración exportados o la API de REST.
  3. Evalúa y define mejor el rendimiento: Prueba las conversaciones en el simulador, ejecuta evaluaciones con Encuentra problemas con la IA y usa AI Co-Builder: Arc para ajustar las instrucciones hasta que tus métricas de calidad cumplan con los umbrales objetivo.
  4. Implementa en etapas: Guarda la configuración validada como una versión y usa la división del tráfico en tu canal de implementación para cambiar el tráfico en vivo de forma gradual mientras supervisas los resultados.

Paso 1: Aísla los cambios

Antes de cambiar la configuración del modelo, aísla tu trabajo para que las actualizaciones y las pruebas no afecten las conversaciones en vivo con los clientes. Puedes aislar los cambios usando versiones dentro de la misma aplicación de agente o exportando la aplicación a un entorno de zona de pruebas independiente.

Usa versiones en la misma aplicación de agente

Cuando tus canales de implementación apuntan a una versión inmutable específica, las ediciones que realices en la aplicación del agente de borrador no afectarán el tráfico en vivo hasta que crees una versión y la asignes a un canal de implementación.

Para guardar una instantánea de referencia de tu configuración actual, haz lo siguiente:

  1. Abre la consola de CX Agent Studio y selecciona tu aplicación de agente.
  2. Abre el panel Versiones en el compilador de agentes.
  3. Haz clic en + Crear versión.
  4. Ingresa un nombre descriptivo, como pre-model-migration-baseline, y una descripción opcional y, luego, haz clic en Crear.
  5. Abre la pestaña Implementar y verifica que tus canales de implementación activos apunten a una versión inmutable (indicada por una insignia Publicada en el panel Versiones) en lugar del borrador mutable.

Exporta y, luego, importa a un entorno de zona de pruebas

Si prefieres probar los cambios del modelo en un proyecto o una aplicación de etapa de pruebas independientes, exporta la aplicación de tu agente y, luego, impórtala a tu entorno de pruebas:

  1. Abre la consola de CX Agent Studio y selecciona tu proyecto.
  2. En la lista de aplicaciones de agentes, abre el menú de tu aplicación y, luego, selecciona Exportar.
  3. Si tu entorno de zona de pruebas usa dependencias externas diferentes, como almacenes de datos o extremos de servicio, extrae el archivo descargado, actualiza el archivo environment.json y comprime el directorio en un archivo ZIP. Para obtener más información, consulta Archivo de entorno.
  4. En tu proyecto de zona de pruebas o aplicación de prueba, abre el menú de la aplicación, selecciona Importar y sube el archivo.
  5. Opcional: Exporta tus casos de prueba de evaluación desde la aplicación de origen y, luego, impórtalos a la aplicación de zona de pruebas para poder ejecutar pruebas de regresión.

Paso 2: Actualiza la configuración del modelo

Revisa la lista de modelos compatibles para elegir un modelo de Gemini de destino que coincida con la modalidad de tu agente (texto o voz). Puedes actualizar la configuración del modelo con la consola, los archivos de configuración exportados o la API de REST.

Actualiza modelos con la consola

Cuando migres una aplicación de agente en la consola, verifica el modelo de aplicación global, las anulaciones de agentes individuales, los modelos de herramientas de almacén de datos y la configuración de resguardo:

  1. Cambia el modelo global:
    1. En el compilador de agentes, abre Configuración para ver la configuración de la aplicación del agente.
    2. En Básico > Interacciones, selecciona tu modelo de destino en el campo Modelo global. Este modelo sirve como el predeterminado para todos los agentes de la aplicación que no especifican una anulación.
  2. Verifica las anulaciones de modelos de agentes raíz y subagentes:
    1. En el compilador de agentes, abre el menú en la barra de título del agente raíz y, luego, selecciona Editar configuración para ver la configuración del agente.
    2. Verifica el campo Modelo. Si el agente anula el modelo global, selecciona tu modelo de destino o borra la anulación para que el agente herede el modelo global.
    3. Repite esta verificación para cada agente secundario de tu jerarquía de agentes.
  3. Verifica los modelos de herramientas del almacén de datos:
    1. Si tu aplicación usa herramientas de almacén de datos, abre el panel Herramientas y selecciona cada herramienta de almacén de datos.
    2. Expande Avanzado > Modalidades y verifica las selecciones de Modelo de reescritura y Modelo de resumen para las configuraciones de Texto y Voz.
  4. Revisa la configuración de reintentos y resguardo:
    1. Abre la Configuración de la aplicación del agente y ve a Básica > Comportamiento > Comportamiento de resguardo.
    2. Verifica que los reintentos, la respuesta del agente y el resguardo estén configurados de forma adecuada para el manejo de errores durante la generación del modelo.

Actualiza modelos con archivos de configuración exportados

Si administras la aplicación de tu agente a través del control de versión o las canalizaciones de CI/CD, puedes actualizar la configuración del modelo en el archivo exportado y volver a importar el paquete:

  1. Extrae el archivo ZIP de la aplicación del agente exportado.

  2. Para cada directorio de agente en agents/<var>AGENT_NAME</var>/, abre el archivo agents/<var>AGENT_NAME</var>/<var>AGENT_NAME</var>.yaml y actualiza el campo modelSettings.model con el ID del modelo de destino:

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

    Reemplaza lo siguiente:

    • <var>AGENT_NAME</var>: Es el nombre visible del agente.
    • <var>MODEL_ID</var>: Es el identificador del modelo de destino, como gemini-3.5-flash o gemini-composite-v2.

  3. Comprime el directorio raíz en un archivo ZIP y, luego, impórtalo en CX Agent Studio.

Actualiza modelos con la API de REST

Puedes actualizar de forma programática ModelSettings en tu aplicación de agente y en agentes individuales con la API de REST de CX Agent Studio.

Antes de llamar a la API, recopila los siguientes valores:

  • <var>PROJECT_ID</var>: Es el ID del proyecto de Google Cloud .
  • <var>LOCATION_ID</var>: Es la región de la aplicación de tu agente, como us o eu.
  • <var>APP_ID</var>: Es el ID de recurso de tu aplicación de agente.
  • <var>AGENT_ID</var>: Es el ID de recurso de un agente raíz o subagente específico.
  • <var>MODEL_ID</var>: Es el identificador del modelo de destino, como gemini-3.5-flash.

Para actualizar el modelo global predeterminado de la aplicación del agente, envía una solicitud PATCH al método 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"
    }
  }'

Para actualizar la anulación del modelo en un agente raíz o secundario individual, envía una solicitud PATCH al método 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"
    }
  }'

Paso 3: Evalúa y mejora el rendimiento del agente

Los modelos de base pueden diferir en el estilo de razonamiento, el cumplimiento de las instrucciones, la verbosidad y el comportamiento de llamada a la herramienta. Después de cambiar de modelo, prueba tu agente y define mejor sus instrucciones antes de enrutar el tráfico de clientes en vivo a la configuración actualizada.

Realiza pruebas de forma interactiva en el simulador

Ejecuta comprobaciones de estado iniciales en el simulador de Preview agent:

  1. Abre el simulador en el compilador de agentes y haz clic en Iniciar nueva conversación.
  2. Prueba las interacciones de texto o audio representativas y verifica que el agente siga las instrucciones, invoque herramientas con argumentos válidos y realice transiciones entre agentes secundarios como se espera.
  3. Expande los detalles de la traza de cada turno para inspeccionar la latencia de los pasos, las entradas y salidas de las herramientas, y las respuestas JSON sin procesar.
  4. Opcional: Para agregar una conversación a tu paquete de regresión, abre el menú del simulador y selecciona Guardar como golden.

Ejecuta evaluaciones y diagnostica problemas con la IA

Usa las evaluaciones para medir el rendimiento en tus casos de prueba de referencia, de situación y de simulación, y comparar los resultados con tu versión de referencia:

  1. Haz clic en Evaluar en la parte superior del compilador de agentes.
  2. Selecciona los casos de prueba que abarcan tus recorridos críticos del usuario y las variantes del agente y, luego, haz clic en Ejecutar seleccionados.
  3. En el diálogo de ejecución, selecciona Find issues with AI, establece el recuento de ejecuciones en 3 o más para un análisis óptimo de la IA y, luego, inicia la ejecución. Para obtener más información, consulta Usa la IA para mejorar los casos de prueba.
  4. Cuando finalice la ejecución, revisa las métricas de evaluación, incluidas la corrección de la herramienta, la coincidencia semántica, la satisfacción del objetivo del usuario, la consecución de objetivos, las alucinaciones y la finalización de tareas, y, luego, inspecciona los turnos fallidos o los objetivos no completados.
  5. En la página de resultados, haz clic en Preguntarle a Gemini para revisar el loss_report generado, resumir las causas raíz de las ejecuciones con errores y ver las correcciones de instrucciones o configuración sugeridas.

Instrucciones para Hill-climb con AI Co-Builder: Arc

Si los resultados de la evaluación muestran regresiones o cambios de comportamiento en el modelo de destino, usa AI Co-Builder: Arc y el asistente de evaluación para definir mejor tus instrucciones de forma iterativa:

  1. Haz clic en Arc en la parte superior del creador de agentes para abrir el Co-Builder de IA.
  2. Haz clic en Seleccionar contexto y elige los agentes o las instrucciones específicos que necesitan ajustes, o adjunta transcripciones con errores y los informes de pérdidas.
  3. Pídele a Arc que actualice tus instrucciones o descripciones de herramientas para abordar las fallas observadas y, al mismo tiempo, preservar el comportamiento en otros casos de prueba. También puedes usar la función restructure instructions para organizar las instrucciones en un formato estructurado.
  4. Vuelve a ejecutar el paquete de evaluación después de aplicar las correcciones y repite el proceso hasta que todos los casos de prueba cumplan con tus criterios de aprobación. Para obtener orientación adicional, consulta las prácticas recomendadas para las evaluaciones y el algoritmo de ascenso de colinas.

Paso 4: Implementa en etapas con la división del tráfico

Una vez que tu agente actualizado apruebe las evaluaciones, impleméntalo de forma gradual con las versiones y la división del tráfico de implementación.

Crea una versión para el agente migrado

Guarda una instantánea inmutable de tu configuración validada:

  1. Si probaste los cambios en una aplicación de zona de pruebas independiente, exporta el paquete de aplicación validado y, luego, impórtalo a tu aplicación de producción.
  2. En tu aplicación de producción, abre el panel Versiones y haz clic en + Crear versión.
  3. Ingresa un nombre y una descripción que identifiquen el modelo de destino, como v2-gemini-3-5-flash, y, luego, haz clic en Crear.

Cambia gradualmente el tráfico en vivo

Usa la división del tráfico para enrutar un pequeño porcentaje de conversaciones en vivo a la versión migrada antes de promoverla al 100% del tráfico:

  1. Haz clic en la pestaña Implementar en la parte superior del compilador de agentes y selecciona tu canal de implementación.
  2. En Versión del agente, haz clic en Agregar versión y, luego, incluye la versión de producción de referencia y la versión candidata migrada.
  3. Asigna un porcentaje de tráfico inicial pequeño a la versión candidata (por ejemplo, 90% para la versión de referencia y 10% para la versión candidata, lo que suma un 100%) y, luego, guarda la configuración del canal. También puedes configurar experimentConfig.versionRelease.trafficAllocations de forma programática con la API de REST.
  4. Supervisa el rendimiento en vivo en todas las versiones:
  5. A medida que confirmes la estabilidad y la calidad, aumenta el porcentaje de tráfico de la versión migrada en etapas hasta que entregue el 100% del tráfico en vivo. Si detectas problemas inesperados durante el lanzamiento, vuelve a enrutar el 100% del tráfico a la versión de referencia o restablece la versión anterior en el panel Versiones.