Exportación o restauración de Git

Nota: En febrero del 2025, se lanzó una nueva versión de esta integración. Los usuarios de la versión antigua pueden proporcionar tokens sin usar secretos. La documentación que se indica a continuación se aplica principalmente a la nueva versión.

Los agentes conversacionales (Dialogflow CX) se integran con varios proveedores de Git (GitHub, GitLab, Bitbucket y otros). Esta integración permite exportar tu agente a JSON fácilmente para enviarlo a un proveedor de Git, así como extraerlo de un proveedor de Git para restaurar el agente. El formato JSON exportado que se envía a un proveedor de Git es el contenido del archivo ZIP expandido del agente exportado.

Si usas esta función, podrás aprovechar las funciones de control de versiones de un proveedor de Git, como las siguientes:

• Revisar los cambios de los agentes con herramientas de revisión de código
• Examinar las diferencias de los agentes con herramientas de comparación
• Combinaciones

Limitaciones

Se aplican las siguientes limitaciones:

• [Solo versión antigua de la integración] Las APIs de GitHub tienen una limitación en el número de archivos que se pueden actualizar en una sola confirmación. Si el número de archivos supera los 500, es posible que no puedas enviar contenido a GitHub desde Conversational Agents (Dialogflow CX). En estos casos, puedes exportar el agente como un archivo ZIP y usar la CLI de Git en tu máquina para enviar los archivos del agente a GitHub. Esta limitación se solucionará en una versión posterior de Conversational Agents (Dialogflow CX).
• No se admiten repositorios autohospedados con acceso privado de GitHub, porque Conversational Agents (Dialogflow CX) no puede acceder a ellos.
• El repositorio de Git no puede contener ningún archivo que no sea de agente exportado por la exportación de agentes. Los demás archivos del repositorio se eliminarán en cada envío.

Configuración

Para configurar esta función, debes obtener un token de acceso de tu proveedor de Git, almacenarlo en Secret Manager y proporcionar el recurso secreto a Conversational Agents (Dialogflow CX):

Token de acceso

Para obtener un token de acceso de tu proveedor de Git, sigue estos pasos:

GitHub

Debes obtener un token personal de GitHub. Si usas un token de acceso personal detallado, necesitas los siguientes permisos:

• Permisos del repositorio > Contenido: lectura y escritura
• Permisos del repositorio > Metadatos: solo lectura (debería seleccionarse automáticamente después de seleccionar el permiso de contenido)

GitLab

Debes obtener un token de acceso personal de GitLab.

Bitbucket

Debes obtener un token de acceso de Bitbucket.

Secret Manager

Ahora que tienes un token de acceso, debes crear un secreto para tu token:

1. Habilita la API Secret Manager.
2. Crea un secreto.

Configuración de Conversational Agents (Dialogflow CX)

Para configurar esta integración en Conversational Agents (Dialogflow CX), sigue estos pasos:

1. Proporciona al agente de servicio de Dialogflow permiso para acceder al secreto del token de acceso en Secret Manager. Asigna el rol Secret Manager Secret Accessor a la gcp-sa-dialogflow.iam.gserviceaccount.com cuenta de servicio de tu proyecto de agente. Consulta Conceder acceso a un secreto de Secret Manager.
2. Abre la configuración de la integración de Git:
   • Consola Conversational Agents
     1. Abre la pantalla de configuración haciendo clic en el icono de configuración situado cerca de la esquina superior derecha.
     2. Desplázate hacia abajo y haz clic en Añadir integración de Git.
   • Consola de Dialogflow CX
     1. Haga clic en la pestaña Gestionar.
     2. En la sección Testing & Deployment (Pruebas e implementación), haz clic en Git.
     3. Haz clic en Crear.
3. Proporciona los detalles de la configuración:
   1. Introduce lo siguiente:
      • Nombre visible de la conexión de GitHub.
      • URL del repositorio de Git (por ejemplo, https://github.com/<path-to-repo>.git).
      • Añade las ramas de Git con las que interactuará tu agente. Puedes designar una rama como rama predeterminada haciendo clic en el icono de estrella situado junto a ella.
      • Secreto del token de acceso, que es la versión secreta que has creado en el formulario projects/*/secrets/*/versions/* para una versión específica o projects/*/secrets/*/versions/latest para la versión más reciente.
   2. Haz clic en Conectar.
   3. El servicio Git puede tardar un minuto en estar listo. La consola mostrará notificaciones.

Enviar y restaurar

Una vez configurado, puedes insertar o extraer tu agente en Git.

El botón Enviar se usa para exportar tu agente y hacer un commit en la rama de Git seleccionada en el menú desplegable Rama de Git. Esta confirmación constará de todo el agente y no de cambios específicos, y eliminará los archivos que haya en el repositorio.

Los usuarios con el rol Lector de Dialogflow pueden enviar contenido a repositorios de Git. Para evitar los envíos no deseados, configura estos agentes con tokens de acceso personal de solo lectura.

El botón Restaurar se usa para extraer los datos del agente de la rama de Git seleccionada en el desplegable Rama de Git y restaurar el agente de Conversational Agents (Dialogflow CX) a partir de estos datos. Esto sobrescribirá tu agente de la misma forma que se comporta cualquier restauración de agente.

Caso práctico de ejemplo

En el siguiente ejemplo se muestra cómo pueden usar esta función varias personas para proponer diferentes cambios en un agente de producción.

Supongamos que tu agente usa las siguientes ramas de Git:

• Prod: rama de tu agente de producción
• Dev1 rama para el desarrollo del agente
• Dev2 otra rama para el desarrollo de agentes

El usuario 1 quiere proponer cambios en el agente y sigue estos pasos:

1. Exporta el agente de producción a un nuevo agente.
2. Haz los cambios que quieras en esta copia del agente.
3. Prueba los cambios.
4. Envía el agente modificado a la rama Dev1.
5. Crea una solicitud de combinación en la rama Prod.

El usuario 2 quiere proponer cambios en el agente y sigue estos pasos:

1. Exporta el agente de producción a un nuevo agente.
2. Haz los cambios que quieras en esta copia del agente.
3. Prueba los cambios.
4. Inserta el agente modificado en la rama Dev2.
5. Crea una solicitud de combinación en la rama Prod.

El usuario 3 revisa las solicitudes de combinación de ambos usuarios y sigue estos pasos:

1. Resuelve los conflictos.
2. Confirma los cambios aprobados.
3. Restaura la rama Git de producción en el agente de producción de Conversational Agents (Dialogflow CX).