Exportación o restablecimiento de Git

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

Los agentes conversacionales (Dialogflow CX) se integran con varios proveedores de Git (GitHub, Gitlab, Bitbucket y otros). Esta integración facilita la exportación de tu agente a JSON para enviarlo a un proveedor de Git y extraerlo de un proveedor de Git para un restablecimiento de agente. El formato JSON exportado que se envía a un proveedor de Git es el contenido expandido del archivo ZIP del agente exportado.

El uso de esta función te permite aprovechar las funciones de control de código fuente de un proveedor de Git, como las siguientes:

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

Limitaciones

Se aplica la siguiente limitación:

• [Solo para la versión de integración anterior] Las APIs de GitHub tienen una limitación en la cantidad de archivos que se pueden actualizar en una sola confirmación. Si la cantidad de archivos supera los 500, es posible que no puedas enviar a GitHub desde agentes conversacionales (Dialogflow CX). En esos 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 abordará en una versión posterior de los agentes conversacionales (Dialogflow CX).
• No se admiten los repositorios alojados por el usuario de acceso privado de GitHub, ya que los agentes conversacionales (Dialogflow CX) no pueden acceder a ellos.
• El repositorio de Git no puede contener ningún archivo que no sean los archivos del agente que exporta el agente de exportación. Se quitarán todos los demás archivos del repositorio en cada envío.

Configuración

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

Token de acceso

Para adquirir un token de acceso de tu proveedor de Git, haz lo siguiente:

GitHub

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

• 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 adquirir un token de acceso personal de Gitlab.

Bitbucket

Debes adquirir un token de acceso de Bitbucket.

Secret Manager

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

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

Configuración de agentes conversacionales (Dialogflow CX)

Para configurar esta integración para agentes conversacionales (Dialogflow CX), sigue estos pasos:

1. Otorga permiso al agente de servicio de Dialogflow para acceder a Secret Manager. Proporciona el rol Secret Manager Secret Accessor a la cuenta de servicio gcp-sa-dialogflow.iam.gserviceaccount.com en tu proyecto de agente. Consulta Otorga un rol de IAM.
2. Abre la configuración de integración de Git:
   • Consola de agentes conversacionales
     1. Para abrir la pantalla de configuración, haz clic en el ícono de configuración que se encuentra cerca de la esquina superior derecha.
     2. Desplázate hacia abajo y haz clic en Agregar integración de Git.
   • Consola de Dialogflow CX
     1. Haz clic en la pestaña Administrar.
     2. Haz clic en Git en la sección Pruebas y, luego, Implementación.
     3. Haz clic en Crear nueva.
3. Proporciona los siguientes detalles de configuración:
   1. Ingresa lo siguiente:
      • Es el nombre visible de la conexión de GitHub.
      • URL del repositorio de Git (por ejemplo, https://github.com/<path-to-repo>.git).
      • Agrega las ramas de Git con las que interactuará tu agente. Para designar una rama como la predeterminada, haz clic en el ícono de estrella junto a ella.
      • Secreto de token de acceso, que es la versión secreta que creaste en el formato 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 de Git puede tardar un minuto en estar listo. La consola mostrará notificaciones.

Envío y restablecimiento

Una vez que lo hagas, podrás enviar o extraer tu agente desde o hacia Git.

El botón Push se usa para exportar tu agente y confirmar la rama de Git seleccionada en el menú desplegable de ramas de Git. Esta confirmación consistirá en todo el agente y no en cambios específicos, y borrará todos los archivos existentes en el repositorio.

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

El botón Restore se usa para extraer los datos de tu agente de la rama de Git seleccionada en el menú desplegable de la rama de Git y restablecer tu agente de Agentes conversacionales (Dialogflow CX) a partir de estos datos. Se reemplazará el agente de la misma manera que se comporta cualquier agente de restablecimiento.

Ejemplo de caso de uso

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

Considera que tu agente usa las siguientes ramas de Git:

• Prod: Es la rama de tu agente de producción.
• Dev1: Rama para el desarrollo de agentes
• 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 agente nuevo.
2. Realiza los cambios deseados en esta copia del agente.
3. Prueba los cambios.
4. Envía el agente alterado 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 agente nuevo.
2. Realiza los cambios deseados en esta copia del agente.
3. Prueba los cambios.
4. Envía el agente alterado a 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. Resolver conflictos
2. Confirma los cambios aprobados.
3. Restablece la rama de Git de producción en el agente de agentes de conversación (Dialogflow CX) de producción.