Crea agentes de datos

Los agentes de datos conversacionales te permiten interactuar con los datos de tu base de datos a través de una interfaz de lenguaje natural. Cuando creas estos agentes, ayudas a los usuarios a "hablar con sus datos", lo que les permite obtener estadísticas de las bases de datos operativas sin necesidad de escribir consultas en SQL complejas.

En términos generales, un agente de datos es una combinación de arquetipo y un conjunto de fuentes de datos, con acceso a un conjunto de conocimientos empresariales fundamentales para sus fines.

Para los desarrolladores de aplicaciones, estos agentes proporcionan los siguientes beneficios:

  • Alta precisión: Con el uso de contexto creado, puedes lograr una alta precisión para preguntas comerciales específicas. El contexto creado es el factor clave principal que los creadores de agentes pueden usar para mejorar la precisión. Incluye descripciones del esquema, instrucciones del sistema y contexto estructurado que proporciona información adicional sobre las consultas de bases de datos esperadas.
  • Menor complejidad: Los agentes traducen el lenguaje natural en consultas SQL, ejecución e incluso resúmenes o visualizaciones de datos.
  • Flexibilidad: Puedes crear agentes para pruebas personales o publicarlos para que estén disponibles para otros usuarios de tu proyecto o de forma programática a través de la API.

Antes de comenzar

  1. Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

  2. Habilita Cloud SQL, la API de Data Analytics with Gemini y Gemini para las APIs. Google Cloud

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

    Habilitar las API

Roles obligatorios

Para trabajar con agentes de datos, debes tener uno de los siguientes roles de Identity and Access Management (IAM) de la API de Conversational Analytics:

  • Consultar datos de fuentes de bases de datos compatibles con el método QueryData: Gemini Data Analytics Data Query User (roles/geminidataanalytics.queryDataUser) a nivel del proyecto
  • Crear, editar, compartir y borrar todos los agentes de datos del proyecto: Propietario del agente de datos de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentOwner) a nivel del proyecto
  • Crea tus propios agentes de datos en el proyecto: Creador de agentes de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentCreator) a nivel del proyecto. Este rol te otorga automáticamente el rol de propietario del agente de datos de análisis de datos de Gemini en los agentes de datos que crees.
  • Ver y editar todos los agentes de datos del proyecto: Editor de agentes de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor) a nivel del proyecto
  • Ver todos los agentes de datos en el proyecto: Visualizador de agentes de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) a nivel del proyecto

Además, debes tener los siguientes roles para crear o editar un agente de datos:

Cuando administres el acceso a los recursos de la base de datos de Cloud SQL para MySQL, ten en cuenta los siguientes niveles de permisos:

  • Google Cloud IAM: Controla el acceso a la instancia de base de datos como un recurso de nube. Esto incluye permisos para conectarse, administrar la instancia y ejecutar consultas SQL, por ejemplo, con el permiso executeSql.
  • Permisos de la base de datos: Controlan el acceso a los objetos de la base de datos, como tablas, vistas y esquemas. Estos se administran con comandos SQL, como GRANT, y sistemas de usuarios y roles específicos de la base de datos.

En el caso de Cloud SQL para MySQL, necesitas los roles de IAM de Cloud SQL adecuados para conectarte a la instancia y estar autorizado a enviar consultas. Para interactuar con objetos como tablas y vistas, el usuario de la base de datos que se conecta debe tener los privilegios necesarios otorgados con el sistema GRANT de Cloud SQL para MySQL. Para obtener más información, consulta Acerca de los usuarios de Cloud SQL para MySQL. Si el agente usa una cuenta de servicio, puedes obtener un rol de base de datos asignado. Por ejemplo, consulta Administra usuarios con autenticación de la base de datos de IAM.

Crea un agente de datos

En las siguientes secciones, se describe cómo crear un agente de datos. Después de crear un agente, puedes editar su configuración.

Configura los aspectos básicos

  1. En la consola de Google Cloud , ve a la página de Cloud SQL para MySQL.

    Ir a Cloud SQL

  2. Elige una instancia de la lista.

  3. En el menú de navegación, haz clic en Agentes.

  4. Haz clic en la pestaña Agentes.

  5. Selecciona una base de datos y accede con tu cuenta de IAM.

  6. Haz clic en Agente nuevo. Se abrirá la página Agente nuevo.

  7. En la sección Editor, en el campo Nombre del agente, ingresa un nombre descriptivo para el agente de datos, por ejemplo, Q4 sales data o User activity logs.

  8. En el campo Descripción del agente, ingresa una descripción del agente de datos. Una buena descripción explica qué hace el agente y qué datos usa, y te ayuda a determinar si es el agente de datos correcto para usar en una conversación (por ejemplo, What are the top 10 selling products in Q2?).

  9. En la sección Fuentes de conocimiento, haz clic en Agregar fuente. Se abrirá la página Agregar datos.

  10. Selecciona las tablas en las que se enfocará el agente cuando responda preguntas. Para ver fuentes de conocimiento adicionales, selecciona Mostrar más.

  11. Haz clic en Agregar. Se volverá a abrir la página del agente nuevo.

Personaliza las descripciones de tablas y campos

Para mejorar la precisión del agente de datos conversacionales, puedes proporcionar metadatos de tabla adicionales de forma opcional. Solo el agente de datos usa estos metadatos, y no afectan la tabla de origen. Puedes agregar los siguientes metadatos:

  • Descripciones del esquema: Agrega descripciones para tus tablas y columnas para ayudar al agente a comprender tus datos. Si no agregas descripciones, el agente usará las descripciones del esquema de tus definiciones de datos.

Sigue estas prácticas recomendadas cuando agregues descripciones de tablas y campos:

  • Agrega descripciones a la definición de datos, no solo a la definición del agente de datos. Esto garantiza que otros agentes también se beneficien de las descripciones.
  • Para crear un prototipo de la descripción adecuada que ayude a los agentes de datos a comprender tus datos, agrega descripciones a tu agente específico. Después de verificar que la descripción tenga el impacto deseado, puedes decidir si la agregarás a la definición de datos.

Para configurar las descripciones de tablas y campos, sigue estos pasos:

  1. En la pestaña Catálogo de agentes, abre el agente que deseas personalizar.
  2. Haz clic en Edit Agent.
  3. En Fuentes de conocimiento, busca la tabla que deseas personalizar y, luego, haz clic en Personalizar.
  4. Ingresa una descripción de la tabla.
  5. Para editar la descripción de cualquier campo, haz clic en Editar junto al campo. Se abrirá el panel Editar campo.
    1. En el campo ID, ingresa una descripción del campo.
    2. Para guardar la descripción del campo, haz clic en Actualizar.
  6. Para guardar la descripción y las actualizaciones de los campos, haz clic en Actualizar. Se volverá a abrir la página del agente nuevo.
  7. Repite estos pasos para cada tabla que quieras personalizar.

Agrega etiquetas a los agentes de datos

En la sección Agent Settings, puedes crear etiquetas para organizar tus recursos de Google Cloud . Las etiquetas son pares clave-valor que te permiten agrupar objetos relacionados entre sí o con otros recursos de Google Cloud.

  1. En la pestaña Catálogo de agentes, abre el agente al que quieres agregar una etiqueta.
  2. Haz clic en Edit Agent.
  3. En la sección Configuración del agente, haz clic en Agregar etiqueta. Se abrirá el panel Administrar etiquetas.
  4. Haz clic en Agregar etiqueta.
  5. En los campos clave y valor, ingresa tu par clave-valor para la etiqueta.
  6. Si deseas agregar más etiquetas, vuelve a hacer clic en Agregar etiqueta.
  7. Para borrar una etiqueta, haz clic en borrar.
  8. Cuando termines, haz clic en Agregar. Se volverá a abrir la página del agente nuevo.

Continúa con la siguiente sección para colocar el agente en modo de borrador o publicarlo.

Obtén una vista previa del agente y publícalo

  1. En la sección Vista previa, ingresa una pregunta de ejemplo en el campo Haz una pregunta y, luego, presiona Intro.

    Para verificar que el agente de datos devuelva los datos que esperas, revisa su respuesta. Si la respuesta no es la que esperas, cambia la configuración en la sección Editor para definir mejor la configuración del agente de datos hasta que obtengas respuestas satisfactorias. Puedes seguir probando y modificando tu agente para refinar sus resultados.

  2. Haz clic en Guardar.

  3. Para colocar el agente de datos en modo de borrador, que puedes volver a editar más adelante, haz clic en Volver para regresar a la página del Catálogo de agentes. Como tu agente ahora está en modo de borrador, aparece en la sección Mis agentes en borrador de la pestaña Catálogo de agentes.

    Para publicar tu agente, permanece en la página de creación del agente y continúa con el siguiente paso.

  4. Para publicar el agente de datos y que esté disponible para su uso en el proyecto, haz clic en Publicar. Publicar el agente permite que otros usuarios, que tienen acceso a las mismas tablas de la base de datos, vean tu agente y conversen con él, y se beneficien de las instrucciones y el contexto que creaste.

    Puedes crear conversaciones con el agente de datos en la página Agentes de la consola de Google Cloud . También puedes crear tu propia interfaz para chatear con el agente de datos usando la API de Conversational Analytics.

  5. Opcional: En el diálogo Se publicó tu agente, haz clic en Compartir para compartir el agente de datos con otros usuarios.

    1. En el panel Permisos de uso compartido, haz clic en Agregar principal.
    2. En el campo Principales nuevas, ingresa una o más principales.
    3. Haz clic en la lista Seleccionar un rol.
    4. En la lista Rol, selecciona uno de los siguientes roles:
      • Usuario del agente de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser): Otorga permiso para chatear con el agente de datos.
      • Editor de agentes de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentEditor): Otorga permiso para editar el agente de datos.
      • Visualizador de agentes de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentViewer): Otorga permiso para ver el agente de datos.

  6. Haz clic en Guardar.

  7. Para volver a la página del agente nuevo, haz clic en Cerrar. Después de guardar o publicar tu agente, puedes verlo en el Catálogo de agentes.

Administra agentes de datos

Puedes encontrar agentes existentes en la pestaña Catálogo de agentes, que consta de tres secciones:

  • Mis agentes: Es una lista de todos los agentes que creas y publicas. Puedes modificar y compartir agentes publicados con otras personas.
  • Mis borradores de agentes: Son los agentes que aún no publicaste. No puedes compartir borradores de agentes.
  • Compartidos por otras personas de tu organización: Son los agentes que otras personas crean y comparten contigo. Si otras personas te otorgan permisos, puedes editar estos agentes compartidos.

Cómo editar un agente de datos

Para editar un agente de datos, sigue estos pasos:

  1. En la consola de Google Cloud , ve a la página de Cloud SQL para MySQL.

    Ir a Cloud SQL

  2. Elige una instancia de la lista.

  3. En el menú de navegación, haz clic en Agentes.

  4. Accede a Agents con la autenticación de Identity and Access Management (IAM).

  5. Haz clic en la pestaña Catálogo de agentes.

  6. Ubica la tarjeta del agente de datos que deseas modificar.

  7. Para abrir el agente de datos en el editor de agentes, haz clic en Abrir acciones y, luego, en Editar en la tarjeta del agente.

  8. Edita la configuración del agente de datos según sea necesario.

  9. Para guardar los cambios sin publicar, haz clic en Guardar.

  10. Para publicar los cambios, haz clic en Publicar. En el diálogo Compartir, puedes compartir el agente con otras personas o hacer clic en Cancelar.

  11. Para volver al panel Agents, haz clic en Volver.

Cómo compartir un agente de datos

Sigue estos pasos para compartir un agente de datos publicado. No puedes compartir agentes de borrador.

  1. En la consola de Google Cloud , ve a la página de Cloud SQL para MySQL.

    Ir a Cloud SQL

  2. Elige una instancia de la lista.

  3. En el menú de navegación, haz clic en Agentes.

  4. Accede a Agents con la autenticación de Identity and Access Management (IAM).

  5. Haz clic en la pestaña Catálogo de agentes.

  6. Ubica la tarjeta del agente de datos que deseas modificar.

  7. Para abrir el agente de datos en el editor de agentes, haz clic en Abrir acciones > haz clic en Editar en la tarjeta del agente.

  8. Para compartir el agente de datos con otros usuarios, haz clic en Compartir.

  9. En el panel Permisos de uso compartido, haz clic en Agregar principal.

  10. En el campo Agregar principales, ingresa uno o más principales.

  11. Haz clic en Selecciona un rol.

  12. En la lista Rol, selecciona uno de los siguientes roles:

    • Usuario del agente de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser): Otorga permiso para chatear con el agente de datos.
    • Editor de agentes de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentEditor): Otorga permiso para editar el agente de datos.
    • Visualizador de agentes de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentViewer): Otorga permiso para ver el agente de datos.

  13. Haz clic en Guardar.

  14. Para volver a la página de edición del agente, haz clic en Cerrar.

  15. Para volver al panel Agentes, haz clic en Volver.

Borra un agente de datos

  1. En la consola de Google Cloud , ve a la página de Cloud SQL para MySQL.

    Ir a Cloud SQL

  2. Elige una instancia de la lista.

  3. En el menú de navegación, haz clic en Agentes.

  4. Accede a Agents con la autenticación de Identity and Access Management (IAM).

  5. Selecciona la pestaña Catálogo de agentes.

  6. En la sección Agentes de la pestaña Catálogo de agentes, busca la tarjeta del agente de datos que deseas borrar.

  7. Haz clic en Abrir acciones > Borrar.

  8. En el cuadro de diálogo ¿Borrar agente?, haz clic en Borrar. Si borras el agente de forma permanente, se quitará del proyecto.

    Después de borrar un agente, las conversaciones existentes estarán disponibles en modo de solo lectura. No podrás hacerle preguntas nuevas al agente borrado.

Ubicaciones

El análisis conversacional funciona a nivel mundial, por lo que no puedes elegir qué región usar.

¿Qué sigue?