Crear agentes de datos

En este documento, se describe cómo crear, editar, administrar y borrar agentes de datos en BigQuery.

En BigQuery, puedes tener conversaciones con agentes de datos para hacer preguntas sobre los datos de BigQuery con lenguaje natural. Los agentes de datos contienen metadatos de tablas y procesan instrucciones de consultas específicas para cada caso de uso que definen la mejor manera de responder las preguntas de los usuarios sobre un conjunto de fuentes de conocimiento, como tablas, vistas o funciones definidas por el usuario (UDF) que selecciones.

Antes de comenzar

  1. Verify that billing is enabled for your Google Cloud project.

  2. Enable the BigQuery, Gemini Data Analytics, and Gemini for Google Cloud APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

Roles obligatorios

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

  • 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) en el proyecto
  • Crear, editar, compartir y borrar tus propios agentes de datos en el proyecto: 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 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 del proyecto: Visualizador de agentes de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentViewer).

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

Para trabajar con recursos de BigQuery, como ver tablas o ejecutar consultas, consulta Roles de BigQuery.

Prácticas recomendadas

Cuando usas el análisis conversacional, las consultas se ejecutan automáticamente para responder tus preguntas. Es posible que se generen cargos imprevistos en los siguientes casos:

  • Si tus tablas son grandes
  • Si las consultas usan combinaciones de datos
  • Si las consultas realizan muchas llamadas a funciones de IA

Para evitar este problema, ten en cuenta el tamaño cuando selecciones fuentes de conocimiento y, cuando mantengas conversaciones, considera usar combinaciones.

Generar estadísticas

De manera opcional, puedes generar estadísticas de datos en Dataplex Universal Catalog para cualquier tabla que desees usar como fuente de conocimiento.

Las estadísticas generadas proporcionan metadatos de la tabla que el agente de datos puede usar para ayudar a generar respuestas a tus preguntas.

Si no generas estadísticas con anticipación, el sistema las generará automáticamente cuando selecciones una tabla como fuente de conocimiento mientras creas un agente de datos.

Trabaja con el agente de datos de muestra

Si no sabes cómo configurar agentes para el análisis conversacional, puedes ver de forma opcional el agente de muestra predefinido que se genera para cada proyecto deGoogle Cloud . Puedes chatear con ella y ver sus parámetros para saber cómo se creó, pero no puedes modificarla.

Para ver el agente de muestra, haz lo siguiente:

  1. En la consola de Google Cloud , ve a la página Agents de BigQuery.

    Ir a Agentes

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

  3. En la sección Agentes de muestra de Google, haz clic en la tarjeta del agente de muestra.

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 Agents de BigQuery.

    Ir a Agentes

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

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

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

  5. En el campo Descripción del agente, escribe una descripción del agente de datos. Una buena descripción explica qué hace el agente, qué datos usa y te ayuda a saber cuándo es el agente de datos adecuado con el que chatear, por ejemplo, Ask questions about customer orders and revenue.

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

  7. En la sección Recientes, selecciona las tablas, las vistas o las UDF que quieras usar como fuentes de conocimiento. Las UDF tienen el prefijo "fx" en la consola deGoogle Cloud .

  8. Para ver fuentes de conocimiento adicionales, selecciona Mostrar más.

  9. Opcional: Agrega una fuente de conocimiento que no aparezca en la sección Recientes:

    1. En la sección Buscar, escribe el nombre de la fuente en el campo Buscar tablas y, luego, presiona Intro. El nombre de la fuente no tiene que ser exacto.

    2. En la sección Resultados de la búsqueda, selecciona una o más fuentes.

  10. 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, puedes proporcionar metadatos de tabla adicionales de forma opcional. Solo el agente de datos usa estos metadatos, y no afectan la tabla de origen.

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

  • Usa estas descripciones como guía para comprender cómo el agente de datos interpreta el esquema. Si las descripciones que sugiere el agente son correctas, puedes aceptarlas.

  • Si el agente de datos no muestra una comprensión del esquema después de que configures estas descripciones, ajústalas de forma manual para proporcionar la información correcta.

Sigue estos pasos para configurar las descripciones de tablas y campos:

  1. En la sección Fuentes de conocimiento, haz clic en el vínculo Personalizar de una tabla.

  2. Crea una descripción de la tabla. Puedes escribir una descripción en el campo Descripción de la tabla o aceptar la sugerencia de Gemini.

  3. En la sección Campos, revisa las descripciones de los campos sugeridas por Gemini.

  4. Selecciona las descripciones de campo que quieras aceptar y haz clic en Aceptar sugerencias. Selecciona las descripciones que quieras rechazar y haz clic en Rechazar sugerencias.

  5. Para editar manualmente la descripción de cualquier campo, haz clic en Editar Editar junto al campo. Se abrirá el panel Editar campo.

    1. En el campo Descripción, escribe 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 necesite personalización.

Configura funciones avanzadas

Configura funciones avanzadas opcionales, como instrucciones para el agente, búsquedas verificadas (antes conocidas como búsquedas de referencia) y parámetros de configuración.

Crea instrucciones para el agente

El agente debe comprender el contexto de las preguntas del usuario sin necesidad de instrucciones personalizadas. Crea instrucciones personalizadas para el agente solo si necesitas cambiar su comportamiento o mejorar el contexto de formas que aún no admiten otras funciones de contexto, por ejemplo, metadatos personalizados de tablas y campos, o consultas verificadas.

En la sección Instrucciones, escribe instrucciones para el agente de datos en el campo Instrucciones del agente. Dado que el agente de datos usa estas instrucciones para comprender el contexto de las preguntas de los usuarios y proporcionar respuestas, las instrucciones deben ser lo más claras posible.

Si no obtienes una respuesta satisfactoria del agente, agrega contexto estructurado, como descripciones o ejemplos. Si aún no obtienes una respuesta satisfactoria, agrega instrucciones personalizadas como las de los ejemplos de la siguiente tabla. Para ver aún más ejemplos de instrucciones, haz clic en Mostrar ejemplos.

Tipo de información Descripción Ejemplos
Campos clave Son los campos más importantes para el análisis. "Los campos más importantes de esta tabla son: ID del cliente, ID del producto y fecha del pedido".
Filtros y agrupaciones Campos que el agente debe usar para filtrar y agrupar datos "Cuando una pregunta se refiere a un período o a un "transcurso del tiempo", siempre usa la columna order_created_date". "Cuando alguien dice 'por producto', agrupa los datos por la columna product_category".
Filtrado predeterminado Son los campos por los que se filtrará de forma predeterminada. "A menos que se indique lo contrario, siempre filtra los datos según order_status = 'Complete'".
Sinónimos y términos comerciales Términos alternativos para los campos clave. "Si alguien pregunta sobre los "Ingresos" o las "Ventas", usa la columna total_sale_amount". "Consideramos que los clientes "leales" son aquellos con purchase_count > 5".
Campos excluidos Son los campos que el agente de datos debe evitar usar. "Nunca uses estos campos: Fecha de transacción derivada y Ciudad derivada".
Unir relaciones Cómo se relacionan dos o más tablas entre sí y qué columnas se usan para unirlas El agente debe usar JOINs de SQL estándar en pares de columnas para combinar datos. Consulta la columna de ejemplo. Actividad del cliente
  • order_items.user_id = users.id
    (para vincular las ventas a los clientes)
  • events.user_id = users.id
    (para vincular la actividad del sitio web a los clientes que accedieron a su cuenta)

Crea consultas verificadas

Un agente usa las búsquedas verificadas de dos maneras:

  • Si un agente puede usar una búsqueda verificada para responder una pregunta que le haces, para garantizar una respuesta confiable, el agente invoca la búsqueda exactamente como está escrita.
  • Si el agente no puede usar la búsqueda verificada para responder una pregunta, la usa como referencia para comprender los datos y las prácticas recomendadas para realizar búsquedas.

Puedes seleccionar búsquedas verificadas de una lista generada por el sistema o crear tus propias búsquedas.

Para crear una búsqueda verificada para el agente de datos, antes conocido como búsqueda dorada, haz lo siguiente:

  1. Selecciona una o más búsquedas verificadas sugeridas por Gemini:

    1. En la sección Verified Queries, haz clic en Review suggestions. Se abrirá la página Revisa las consultas verificadas sugeridas.
    2. Revisa las consultas verificadas sugeridas. Selecciona todas las opciones que se apliquen a tu caso de uso.
    3. Haz clic en Agregar. Se volverá a abrir la página del agente nuevo.

  2. Para crear tu propia búsqueda verificada, haz clic en Agregar búsqueda. Se abrirá la página Agregar búsqueda verificada.

    1. En el campo Pregunta, escribe la pregunta del usuario que responde la búsqueda verificada.
    2. Haz clic en Generar SQL para que Gemini genere una consulta verificada que corresponda a la pregunta del usuario que especificaste.
    3. Si lo deseas, modifica la consulta verificada.
    4. Haz clic en Ejecutar y verifica que la consulta devuelva los resultados que esperas.
    5. Haz clic en Agregar. Se volverá a abrir la página del agente nuevo.

  3. Repite estos pasos según sea necesario para crear búsquedas verificadas adicionales.

Establece la configuración

En la sección Configuración, puedes establecer los siguientes parámetros de configuración opcionales:

  1. Crea etiquetas para organizar tus recursos deGoogle 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 sección Configuración, haz clic en Administrar etiquetas.
    2. Haz clic en Agregar etiqueta.
    3. En los campos clave y valor, ingresa tu par clave-valor para la etiqueta.
    4. Si deseas agregar más etiquetas, vuelve a hacer clic en Agregar etiqueta.
    5. Para borrar una etiqueta, haz clic en Borrar.
    6. Cuando termines, haz clic en Agregar. Se volverá a abrir la página del agente nuevo.

  2. Opcional: Establece un límite de tamaño para las consultas que procesa el agente de datos. En la sección Configuración, escribe un valor en el campo Máximo de bytes facturados. Debes establecer este límite en 10485760 o más. De lo contrario, recibirás el siguiente mensaje de error:

Value error. In BigQuery on-demand pricing charges are
rounded up to the nearest MB, with a minimum of 10 MB of data processed
per query. So, max bytes billed must be set to greater or equal to
10485760.

Si no especificas un valor, maximum bytes billed se establece de forma predeterminada en la cuota de uso de consultas por día del proyecto. La cuota de uso por día es ilimitada, a menos que hayas especificado una cuota personalizada.

Continúa con la siguiente sección para poner 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, escribe una pregunta de usuario 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 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. Haz clic en Publicar para publicar el agente de datos y que esté disponible para su uso en el proyecto. Puedes crear conversaciones con el agente de datos en BigQuery Studio y en Looker Studio Pro si tienes una suscripción a Looker Studio. También puedes crear tu propia interfaz para chatear con el agente de datos a través de 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. Inmediatamente después de guardar o publicar tu agente, podrás 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 agentes en borrador.
  • Compartidos por otras personas de tu organización: Son los agentes que otras personas crean y comparten contigo. Si otros usuarios te otorgan permisos, puedes editar estos agentes compartidos.

Edita un agente de datos

Sigue estos pasos para editar un agente de datos:

  1. Ve a la página Agentes de BigQuery.

    Ir a Agentes

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

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

  4. 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.

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

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

  7. 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.

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

    Ícono de atrás para volver a la página Agentes desde la página de edición del agente.

Cómo compartir un agente de datos

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

  1. Ve a la página Agentes de BigQuery.

    Ir a Agentes

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

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

  4. 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.

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

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

  7. En el campo Principales nuevas, ingresa una o más principales.

  8. Haz clic en la lista Seleccionar un rol.

  9. 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.

  10. Haz clic en Guardar.

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

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

    Ícono de atrás para volver a la página Agentes desde la página de edición del agente.

Borra un agente de datos

  1. Ve a la página Agentes de BigQuery.

    Ir a Agentes

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

  3. En la sección Mis agentes o Agentes en borrador de la pestaña Catálogo de agentes, busca la tarjeta del agente de datos que quieres borrar.

  4. Haz clic en Abrir acciones > Borrar.

  5. En el cuadro de diálogo ¿Borrar agente?, haz clic en Borrar.

Ubicaciones

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

¿Qué sigue?