Crear 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 por personas, 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 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 permisos de IAM que coincidan con tu caso de uso. En la siguiente tabla, se enumeran los roles obligatorios según si creas y publicas agentes, los aprovisionas en Gemini Enterprise o los descubres y usas. Para obtener más información, consulta Roles de IAM de la API de Conversational Analytics.

Caso de uso Roles obligatorios
Crear, editar, publicar, compartir y borrar agentes
  • Para crear agentes de datos en un proyecto, usa el Creador de agentes de datos de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentCreator) en el proyecto. Este rol te otorga automáticamente el rol de propietario del agente de datos de Gemini Data Analytics en los agentes de datos que crees.
  • Para editar, compartir o borrar un agente de datos: Propietario del agente de datos de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentOwner) en el agente o proyecto
  • Para editar un agente de datos en un proyecto, debes tener el rol de editor de agentes de datos de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentEditor) en el proyecto.
  • Para ver los agentes de datos en un proyecto, debes tener el rol de Visualizador de agentes de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) en el proyecto.
  • Además, debes tener los siguientes roles para crear o editar un agente de datos:
Aprovisiona agentes en Gemini Enterprise

Para que un agente publicado esté disponible para los usuarios en Gemini Enterprise, necesitas permisos para registrar y administrar agentes A2A en la Consola del administrador de Gemini Enterprise.
Descubre y usa agentes
  • Para chatear con agentes de datos: Usuario del agente de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser).
  • Para ver todos los agentes de datos del proyecto, usa el visualizador de agentes de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer).

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 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 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 Acerca de 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 consola de Google Cloud , ve a la página de 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 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 usa 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 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 Edit Agent.
  3. En Fuentes de conocimiento, busca la tabla que quieras 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 Configuración del agente, 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 Agent Catalog, 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.
    5. Haz clic en Guardar.

  6. Opcional: Puedes publicar el agente de datos en Gemini Enterprise. Para obtener más información, consulta Cómo publicar un agente de datos en Gemini Enterprise.

  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 agentes en borrador: Son los agentes que aún no publicaste. No puedes compartir borradores de agentes.
  • Compartido por otras personas de tu organización: Son 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 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 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 Agentes, 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 en borrador.

  1. En la consola de Google Cloud , ve a la página de 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 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 análisis de datos de Gemini (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 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 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.

Publica un agente de datos en Gemini Enterprise

La publicación de un agente de datos implica la colaboración entre analistas de datos, administradores de Gemini Enterprise y usuarios empresariales. Para obtener información sobre los roles requeridos para estos usuarios, consulta Roles requeridos.

Crea y publica un agente

Para crear, editar y publicar un agente, sigue estos pasos:

  1. Crea o edita tu agente de datos en Cloud SQL para PostgreSQL.
  2. Publica el agente. Cuando publiques el agente, selecciona Gemini Enterprise como opción de publicación.
  3. Para copiar el JSON del extremo de A2A, haz clic en Copiar JSON.
  4. Comparte el JSON del extremo de A2A y la lista de usuarios con tu administrador de Gemini Enterprise para que pueda registrar el agente personalizado en la consola Google Cloud y configurar los permisos de acceso. Para obtener más información, consulta Cómo aprovisionar un agente.
  5. Comparte el agente con los usuarios y grupos que necesiten acceso.

Aprovisiona un agente

Para que un agente publicado esté disponible para los usuarios en la consola de Google Cloud , sigue estos pasos:

  1. En la consola de Google Cloud , ve a Gemini Enterprise.

    Gemini Enterprise

  2. Haz clic en el nombre de la app en la que deseas registrar el agente.

  3. Haz clic en Agentes > Agregar agentes.

  4. En la sección Elige un tipo de agente, haz clic en Agregar para Agente personalizado a través de A2A.

  5. En el campo JSON de la tarjeta del agente, ingresa los detalles de la tarjeta del agente que recibiste anteriormente del analista de datos en formato JSON.

  6. Haz clic en Preview agent details > Next.

  7. Para permitir que el agente acceda a los recursos Google Cloud en tu nombre, sigue estos pasos:

    1. Ingresa el ID de cliente y el secreto del cliente que generaste en la sección Configura los detalles de autorización.

    2. En el campo URI de autorización, ingresa lo siguiente:

      https://accounts.google.com/o/oauth2/v2/auth?client_id=client_id&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

      Reemplaza client_id por el ID de cliente que generaste en Configura los detalles de autorización.

    3. En el campo URI del token, ingresa lo siguiente:

      https://oauth2.googleapis.com/token

    4. En el campo Alcances, ingresa lo siguiente:

      https://www.googleapis.com/auth/cloud-platform

  8. Haz clic en Finalizar.

  9. Comparte el agente con los usuarios o grupos.

Para obtener más información, consulta Cómo registrar y administrar agentes de A2A.

Cómo encontrar y usar un agente

Puedes encontrar y usar un agente de datos en Gemini Enterprise con cualquiera de los siguientes métodos:

  • Busca el agente en la Galería de agentes y comienza un chat dedicado.
  • Usa la URL dedicada del agente para abrir Gemini Enterprise directamente en una sesión con ese agente de datos específico de Cloud SQL para PostgreSQL.
  • Invoca al agente escribiendo un @mention, como @sales_pipeline_agent, en el chat principal de Gemini Enterprise.
  • Haz una pregunta analítica general, como "¿Cómo ha sido la tendencia de nuestro canal de ventas en los últimos 3 meses?", para permitir que Gemini Enterprise dirija automáticamente la consulta al agente de datos pertinente.

Después de encontrar el agente, puedes interactuar con él de una de las siguientes maneras:

  • Completa el acceso único con OAuth para autenticarte de forma segura en Cloud SQL para PostgreSQL.
  • Haz preguntas en lenguaje natural. El agente de análisis conversacional procesa tus solicitudes y transmite la respuesta a Gemini Enterprise como texto, Markdown, gráficos o tablas.
  • Consulta tu historial de conversaciones en el panel de historial, donde las conversaciones se guardan automáticamente.

Ubicaciones

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

¿Qué sigue?