Crea agentes de datos

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

En un nivel superior, un agente de datos es una combinación de persona, un conjunto de fuentes de datos, con acceso a un conjunto de conocimientos empresariales fundamentales para sus propósitos.

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

  • Alta precisión: Si usas el contexto creado, puedes lograr una alta precisión para preguntas empresariales específicas. El contexto creado es el factor clave principal que los creadores de agentes pueden usar para mejorar la precisión. Incluye descripciones de esquemas, instrucciones del sistema y contexto estructurado que proporciona información adicional sobre las consultas de bases de datos esperadas.
  • Complejidad reducida: Los agentes traducen el lenguaje natural a consultas de SQL, ejecución e incluso resumen o visualización 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 con la API.

Antes de comenzar

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

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

    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: Usuario de datos de consulta de Gemini Data Analytics (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 Gemini Data Analytics (roles/geminidataanalytics.dataAgentOwner) a nivel del proyecto.
  • Crear 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 Propietario del agente de datos de Gemini Data Analytics 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 del 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 PostgreSQL, 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 la nube. Esto incluye permisos para conectarse, administrar la instancia y ejecutar consultas de SQL, por ejemplo, con el permiso executeSql.
  • Permisos de base de datos: Controlan el acceso a los objetos de la base de datos, como tablas, vistas y esquemas. Estos se administran con comandos de SQL como GRANT y sistemas de usuarios y roles específicos de la base de datos.

En el caso de Cloud SQL para PostgreSQL, necesitas los roles de IAM de Cloud SQL adecuados para conectarte a la instancia y tener autorización para 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 PostgreSQL. Para obtener más información, consulta Información sobre los usuarios y los roles de PostgreSQL. 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 Google Cloud consola de, ve a la página Cloud SQL para PostgreSQL.

    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 lo que hace el agente, qué datos usa y te ayuda a determinar si este 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 conversacional, puedes proporcionar metadatos de tabla adicionales de forma opcional. Solo el agente de datos usa estos metadatos, y no afecta la tabla de origen. Puedes agregar los siguientes metadatos:

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

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

  • Agrega descripciones a tu definición de datos en lugar de solo a la definición de tu agente de datos. De esta manera, te aseguras de 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 agregarla a tu 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 Editar agente.
  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 cualquier descripción de 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 desees personalizar.

Agrega etiquetas a los agentes de datos

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

  1. En la pestaña Catálogo de agentes, abre el agente al que deseas agregar una etiqueta.
  2. Haz clic en Editar agente.
  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 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 muestre los datos que esperas, revisa la respuesta del agente. Si la respuesta no es la que esperas, cambia la configuración en la sección Editor para refinar la configuración del agente de datos hasta que obtengas respuestas satisfactorias. Puedes seguir probando y modificando tu agente para refinar los resultados del agente.

  2. Haz clic en Guardar.

  3. Para colocar el agente de datos en modo borrador, que puedes volver a editar más adelante, haz clic en Volver para regresar a la página Catálogo de agentes. Como tu agente ahora está en modo borrador, aparece en la sección Mis agentes de 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. La publicación del 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 usando la página Agentes en la Google Cloud consola. 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 Compartir permisos, haz clic en Agregar principal.
    2. En el campo Principales nuevas, ingresa uno o más principales.
    3. Haz clic en la lista Selecciona 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 datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor): Otorga permiso para editar el agente de datos.
      • Visualizador de agentes de datos de Gemini Data Analytics (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 los agentes de datos

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

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

Edita un agente de datos

Para editar un agente de datos, sigue estos pasos:

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

    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 Agentes 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 Agentes, haz clic en Volver.

Comparte un agente de datos

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

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

    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 Agentes 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 Compartir permisos, 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 datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor): Otorga permiso para editar el agente de datos.
    • Visualizador de agentes de datos de Gemini Data Analytics (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 Google Cloud consola de, ve a la página Cloud SQL para PostgreSQL.

    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 Agentes 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, ubica la tarjeta del agente de datos que deseas borrar.

  7. Haz clic en Abrir acciones > Borrar.

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

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

Ubicaciones

Conversational Analytics opera de forma global, por lo que no puedes elegir qué región usar.

¿Qué sigue?