Crear agentes de datos

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

En BigQuery, puedes mantener conversaciones con agentes de datos para hacer preguntas sobre los datos de BigQuery en lenguaje natural. Los agentes de datos contienen metadatos de tablas e instrucciones de procesamiento de consultas específicas de casos prácticos que definen la mejor forma de responder a las preguntas de los usuarios sobre un conjunto de fuentes de conocimiento, como tablas, vistas o funciones definidas por el usuario (UDFs) que selecciones.

Antes de empezar

1. Comprueba que la facturación esté habilitada en tu Google Cloud proyecto.

2. Habilita las APIs BigQuery, Gemini Data Analytics, Gemini for Google Cloudy Knowledge Catalog.

   Roles necesarios para habilitar las APIs

   Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si has creado el proyecto, es probable que ya tengas este permiso a través del rol Propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol Administrador de uso de servicio (roles/serviceusage.serviceUsageAdmin). Consulta cómo asignar roles.

   Habilita las APIs

Roles obligatorios

Para trabajar con agentes de datos, debes tener permisos de gestión de identidades y accesos (IAM) que se ajusten a tu caso práctico. En las siguientes secciones se indican los roles obligatorios en función de si vas a crear y publicar agentes, aprovisionar agentes en Gemini Enterprise o descubrir y usar agentes en varias superficies. Para obtener más información, consulte Roles de gestión de identidades y accesos de la API Conversational Analytics.

• Crear, editar, publicar, compartir y eliminar agentes:
  • Para crear agentes de datos en un proyecto, debes tener el rol Gemini Data Analytics Creador de agente de datos (roles/geminidataanalytics.dataAgentCreator) en el proyecto. Este rol te asigna automáticamente el rol Propietario del agente de datos de Gemini Data Analytics en los agentes de datos que crees.
  • Para editar, compartir o eliminar un agente de datos, debes tener el rol de propietario del agente de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentOwner) en el agente o en el proyecto.
  • Para editar un agente de datos en un proyecto, ve a Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor) en el proyecto.
  • Para ver los agentes de datos de un proyecto, debes tener el rol Lector de agente de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) en el proyecto.
• Aprovisionar agentes en Gemini Enterprise:
  • Para que un agente publicado esté disponible para los usuarios de Gemini Enterprise, necesitas permisos para registrar y gestionar agentes A2A en la consola de administración de Gemini Enterprise.
• Descubrir y usar agentes:
  • Para chatear con agentes de datos: Usuario de agente de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser).
  • Para ver todos los agentes de datos del proyecto, ve a Datos de Gemini Data Analytics > Visor de agente de datos (roles/geminidataanalytics.dataAgentViewer).
  • Para interactuar con la interfaz de chat basada en Gemini en Data Studio, debes tener el rol Usuario de BigQuery Studio (roles/bigquery.studioUser) o Usuario de Gemini para Google Cloud (roles/cloudaicompanion.user), que proporcionan el permiso cloudaicompanion.topics.create. Concede estos roles a nivel de proyecto. Los usuarios también necesitan el rol Lector de recursos de Data Studio (roles/datastudio.viewer).
• Añadir fuentes de conocimiento a un agente:
  • Lector de Data Catalog (roles/datacatalog.viewer) en el proyecto.

Para mantener conversaciones, consulta los roles necesarios para las conversaciones.

Los agentes actúan en tu nombre y usan tus permisos. Los agentes solo pueden acceder a los datos y recursos a los que tengas permiso para acceder.

Prácticas recomendadas

Análisis conversacional ejecuta automáticamente consultas en tu nombre para responder a tus preguntas. Ten en cuenta los siguientes factores que pueden aumentar el coste de las consultas:

• Tamaños de tabla grandes
• Uso de combinaciones de datos en consultas
• Llamadas frecuentes a funciones de IA en las consultas

Generar estadísticas

También puedes generar estadísticas de datos en Knowledge Catalog para cualquier tabla que quieras usar como fuente de conocimiento.

La información valiosa generada proporciona metadatos de tabla que el agente de datos puede usar para ayudar a generar respuestas a tus preguntas.

Si no generas estadísticas previamente, el sistema las generará automáticamente cuando selecciones una tabla como fuente de conocimiento al crear un agente de datos.

Trabajar con el agente de datos de muestra

Si no sabes cómo configurar agentes para el análisis conversacional, puedes consultar el agente de ejemplo predefinido que se genera para cadaGoogle Cloud proyecto. Puedes chatear con él y ver sus parámetros para saber cómo se creó, pero no puedes modificarlo.

Para ver el agente de muestra, sigue estos pasos:

1. En la Google Cloud consola, 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 Ejemplos de agentes de Google, haz clic en la tarjeta del agente de ejemplo.

Crear un agente de datos

En las siguientes secciones se describe cómo crear un agente de datos.

Una vez que hayas creado un agente, podrás editar su configuración.

Nota: Si estás conversando con una fuente de datos, también puedes crear un agente a partir de esa conversación.

Primeros pasos

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

   Ir a Agentes

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

3. Haz clic en Nuevo agente. Se abre la página Nuevo agente.

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 para chatear. Por ejemplo, Ask questions about customer orders and revenue.

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

7. En la sección Recientes, selecciona las tablas, vistas, gráficos o funciones definidas por el usuario que quieras usar como fuentes de conocimiento. Las funciones definidas por el usuario tienen el prefijo "fx" en la Google Cloud consola.

8. Para ver más fuentes de información, selecciona Mostrar más.

9. Opcional: Añade una fuente de información 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, a continuación, pulsa Intro. No es necesario que el nombre de la fuente sea exacto.

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

10. Haz clic en Añadir. Se vuelve a abrir la página del nuevo agente.

Personalizar las descripciones de tablas y campos

Para mejorar la precisión del agente de datos, puede proporcionar metadatos de tabla adicionales. Solo el agente de datos usa estos metadatos, que no afectan a la tabla de origen.

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

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

• Si el agente de datos no entiende el esquema después de configurar estas descripciones, ajústelas manualmente para proporcionar la información correcta.

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

1. En la sección Fuentes de conocimiento, haz clic en el enlace 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 los campos 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 un campo, haz clic en 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 los cambios en los campos, haz clic en Actualizar. Se vuelve a abrir la página del nuevo agente.

7. Repite estos pasos con cada tabla que necesite personalizarse.

Nota: Si los cambios que has hecho en las descripciones no se reflejan en la consola Google Cloud , puedes usar el método list para verificar o el método patch para actualizar las descripciones.

Crear instrucciones para el agente

El agente debe entender el contexto de las preguntas de los usuarios sin necesidad de instrucciones personalizadas. Crea instrucciones personalizadas para el agente solo si necesitas cambiar su comportamiento o mejorar el contexto de formas que no se admitan con otras funciones de contexto, como metadatos de campos y tablas personalizados o consultas verificadas.

En la sección Instrucciones, escribe las instrucciones para el agente de datos en el campo Instrucciones para el agente. Como el agente de datos usa estas instrucciones para entender 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, añade contexto estructurado, como descripciones, ejemplos o términos del glosario. Si sigues sin obtener una respuesta satisfactoria, añade instrucciones personalizadas como las de la siguiente tabla.

Para ver más ejemplos de instrucciones, haz clic en Mostrar ejemplos.

Tipo de información	Descripción	Ejemplos
Campos clave	Los campos más importantes para el análisis.	"Los campos más importantes de esta tabla son: ID de cliente, ID de producto y Fecha de pedido".
Filtrado y agrupación	Campos que el agente debe usar para filtrar y agrupar datos.	"Cuando una pregunta se refiera a una cronología o a un periodo de tiempo, usa siempre la columna order_created_date". "Cuando alguien diga 'por producto', agrupa los datos por la columna product_category".
Filtrado predeterminado	Campos por los que se filtra de forma predeterminada.	"A menos que se indique lo contrario, siempre se deben filtrar los datos por order_status = 'Complete'".
Sinónimos y términos empresariales	Términos alternativos para los campos clave.	"Si alguien pregunta por los ingresos o las ventas, usa la columna total_sale_amount". "Consideramos que los clientes fieles son aquellos cuyo valor de purchase_count es superior a 5".
Campos excluidos	Campos que el agente de datos debe evitar usar.	"Nunca uses estos campos: Fecha de transacción derivada y Ciudad derivada".
Relaciones de unión	Cómo se relacionan dos o más tablas entre sí y qué columnas se usan para combinarlas. El agente debe usar JOINs de SQL estándar en pares de columnas para combinar datos. Consulta la columna 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 con los clientes que han iniciado sesión)

Crear consultas verificadas

Un agente usa las consultas verificadas de dos formas:

• Si un agente puede usar una consulta verificada para responder a una pregunta que le hagas, para asegurarse de que la respuesta sea fiable, el agente invoca la consulta exactamente como está escrita.
• Si el agente no puede usar la consulta verificada para responder a una pregunta, sigue usando la consulta como referencia para entender los datos y las prácticas recomendadas para consultarlos.

Puedes seleccionar consultas verificadas de una lista generada por el sistema o crear las tuyas propias.

Nota: Para crear una consulta verificada con parámetros, consulta Crear consultas verificadas con parámetros.

Para crear una consulta verificada para el agente de datos, antes conocida como consulta de referencia, haz lo siguiente:

1. Selecciona una o varias consultas verificadas sugeridas por Gemini:

   1. En la sección Consultas verificadas, haga clic en Revisar sugerencias. Se abrirá la página Revisar consultas verificadas sugeridas.
   2. Revisa las consultas verificadas sugeridas. Selecciona las que se apliquen a tu caso de uso.
   3. Haz clic en Añadir. Se vuelve a abrir la página del nuevo agente.

2. Para crear tu propia consulta verificada, haz clic en Añadir consulta. Se abrirá la página Añadir consulta verificada.

   1. En el campo Pregunta, escribe la pregunta del usuario a la que responde la consulta verificada.
   2. Haz clic en Generar SQL para que Gemini genere una consulta verificada que corresponda a la pregunta del usuario que hayas especificado.
   3. Modifica la consulta verificada si quieres.
   4. Haz clic en Ejecutar y comprueba que la consulta devuelve los resultados que esperas.
   5. Haz clic en Añadir. Se vuelve a abrir la página del nuevo agente.

3. Repite estos pasos según sea necesario para crear más consultas verificadas.

Crear consultas verificadas con parámetros

Las consultas verificadas parametrizadas extraen valores de la pregunta de un usuario para el agente de analíticas conversacional y proporcionan resultados personalizados.

Los analistas y los desarrolladores pueden crear plantillas de SQL reutilizables que contengan marcadores de posición para estos valores. Las plantillas sustituyen dinámicamente los parámetros en tiempo de ejecución para responder a una gama más amplia de preguntas de los usuarios que las consultas verificadas normales.

Cuando un usuario hace una pregunta que coincide con el patrón de la plantilla, el agente de analíticas conversacional extrae los valores de los parámetros de la pregunta (por ejemplo, el nombre del producto, la región y la fecha). A continuación, inserta estos valores en la consulta parametrizada. Las respuestas coincidentes de la plantilla de consulta se muestran como verificadas.

Las consultas verificadas con parámetros mejoran significativamente la potencia y la flexibilidad de las consultas verificadas. Aseguran respuestas coherentes y fiables en varias entradas y reducen el número de consultas individuales que se deben mantener.

Cómo funciona

Un experto, como un analista de datos, define una consulta verificada mediante una plantilla de pregunta. Por ejemplo, "¿Cuáles fueron las ventas de @product en @region?". A continuación, el experto crea o modifica la consulta verificada mediante parámetros de SQL, como se muestra en el siguiente ejemplo:

SELECT * FROM sales WHERE region = @region AND product = @product

Una vez que se haya guardado la consulta verificada, el usuario podrá hacerle una pregunta al agente de analíticas conversacionales en lenguaje natural. Por ejemplo, "¿Cuáles fueron las ventas de portátiles en Norteamérica?".

Para responder a la pregunta del usuario, el agente sigue estos pasos:

1. Hace coincidir la pregunta con el patrón asociado a la consulta verificada parametrizada. El agente usa la comprensión del lenguaje natural (CLN) para identificar y extraer los valores de @region (Norteamérica) y @product (portátiles) de la pregunta del usuario.
2. Sustituye los valores extraídos por los marcadores de posición @region y @product de la plantilla SQL.
3. Ejecuta la consulta de SQL completa. Por ejemplo, SELECT * FROM sales WHERE region = 'North America' AND product = 'Laptops'.
4. Devuelve los resultados al usuario. Las coincidencias siempre se marcan como verificadas.

Consejos para crear consultas con parámetros eficaces

• Usa nombres de parámetros claros. Usa nombres descriptivos para los parámetros. Por ejemplo, @start_date en lugar de @d1.
• Crea descripciones detalladas de los parámetros. El modelo de lenguaje extenso (LLM) de la analítica conversacional usa descripciones de parámetros para identificar los parámetros y sus valores a partir de las preguntas de los usuarios. Por ejemplo, num_enrollments es un nombre de parámetro eficaz, pero number of student enrollments from ages 5-14 es una descripción de parámetro que proporciona más contexto sobre la consulta.
• Asegúrate de que los tipos de datos sean coherentes. Asegúrate de que los tipos de datos que espera la consulta de SQL coincidan con los tipos de datos que probablemente se extraerán de la pregunta del usuario.
• Define bien el ámbito. Crea plantillas para patrones de preguntas comunes e importantes en los que la creación de la consulta sea compleja o la lógica no sea intuitiva. De esta forma, el LLM puede ofrecer resultados óptimos.
• Haz pruebas exhaustivas. Prueba con varias formulaciones en lenguaje natural para asegurarte de que los parámetros se extraen correctamente.

Crear una consulta verificada con parámetros

Puedes seleccionar consultas verificadas de una lista generada por el sistema o crear las tuyas propias.

Antes de crear o modificar una consulta, escribe un borrador teniendo en cuenta el patrón del lenguaje natural y tu pregunta. Por ejemplo, si preguntas "¿Sabemos el stock total de plátanos ecológicos en el almacén US-EAST?", puedes reformular la pregunta como una consulta verificada parametrizada: "¿Cuál es el stock total de @product en el almacén @region?". El agente convierte esta pregunta en una consulta de SQL que actualizas con valores predeterminados.

Para crear una consulta verificada parametrizada para un agente de datos, puedes crear una consulta al crear un agente o editar una consulta verificada para un agente nuevo o que ya tengas.

En las siguientes instrucciones se usa una consulta verificada de ejemplo para configurar los parámetros.

Selecciona una consulta verificada sugerida por Gemini

1. En la sección Consultas verificadas de un agente nuevo o actual, haga clic en Revisar sugerencias. Se abrirá la página Revisar consultas verificadas sugeridas.
2. Seleccione la casilla situada junto a una consulta verificada sugerida.
3. En la ventana de consulta, haga clic en Mostrar más para ampliar la descripción de la consulta.
4. Para abrir la consulta, haz clic en Editar.
5. Para terminar de configurar la consulta, consulta Configurar los parámetros de la consulta verificada.

Crear un agente y, a continuación, una consulta verificada

1. Consulta los pasos iniciales y sigue el resto de los pasos de configuración para verificar las consultas.
2. En la Google Cloud consola, en la sección Consultas verificadas del nuevo agente, haz clic en Añadir consulta. Se abrirá la página Añadir consulta verificada.
3. Para terminar de configurar la consulta, consulta Configurar los parámetros de la consulta verificada.

Configurar los parámetros de la consulta verificada

1. En el campo Pregunta, escribe la pregunta del usuario a la que responde la consulta verificada.
2. Para especificar parámetros, usa el símbolo @ seguido del nombre del parámetro. Esta sintaxis identifica un marcador de posición que ingiere un valor de la pregunta del usuario. Usa una pregunta en lenguaje natural que muestre cómo se usarán los parámetros en las preguntas de los usuarios. Por ejemplo: "¿Cuál es el stock total de @product en el almacén de @region?"

3. Haz clic en Generar SQL. El SQL es similar al siguiente ejemplo:

      SELECT
          SUM(stock) AS total_stock
      FROM
          inventory
      WHERE
          product_id = @product
          AND region = @region;
   

4. Para añadir valores predeterminados a los marcadores de posición de la consulta, haga clic en Gestionar parámetros de consulta y, a continuación, en Añadir parámetro de consulta.

5. En el primer parámetro, aparecen cuatro campos: Nombre, Tipo, Valor y Descripción.

   • En Nombre, copia @product de tu pregunta y pégalo en este campo.
   • En Tipo, selecciona STRING.
   • En Valor, introduce organic bananas.
   • En Descripción, escribe una descripción lo más específica posible. Por ejemplo, un producto ubicado en un almacén regional.

6. En el segundo parámetro, haga clic en Añadir parámetro de consulta.

   • En Nombre, copia @region de tu pregunta y pégalo en este campo.
   • En Tipo, selecciona STRING.
   • En Valor, introduce US-EAST.
   • En Descripción, escriba una descripción lo más específica posible. Por ejemplo, a regional warehouse where products are located.

7. Cuando hayas rellenado los campos de ambos parámetros, haz clic en Guardar.

Probar la consulta verificada con parámetros

1. Haz clic en Ejecutar y comprueba que la consulta devuelve los resultados que esperas.
2. Para probar la consulta de los usuarios en una pantalla posterior, copia todo el campo de la pregunta.
3. Haz clic en Guardar para salir de la pantalla Añadir consulta y volver a la página Editar del agente.
4. En la página Editar del agente, pega el campo de pregunta que has copiado anteriormente en la ventana Vista previa.
   1. Sustituye la variable @product por organic bananas.
   2. Sustituye la variable @region por US-EAST.
5. Pulsa Intro. Comprueba el resultado. En este caso, una respuesta válida es el número total de plátanos en stock en la región US-EAST, por ejemplo,1000.
6. Para crear o editar consultas verificadas adicionales, repite estos pasos según sea necesario.

Ahora que has guardado la consulta, un usuario puede hacer la siguiente pregunta: "¿Sabemos el stock total de plátanos ecológicos en el almacén US-EAST?". A continuación, Analíticas conversacionales hace lo siguiente:

1. Asocia esta pregunta con el patrón.
2. Extrae el parámetro @product como @product = "organic bananas" (plátanos ecológicos) y el parámetro @region = "US-EAST" (EE. UU. - Este) de la pregunta.
3. Ejecuta la consulta: SELECT SUM(stock) AS total_stock FROM inventory WHERE product_id = 'organic bananas' AND region = 'US-EAST';
4. Devuelve el valor calculado de total_stock.

Crear o revisar términos de glosario

Puedes crear términos de glosario personalizados de BigQuery locales para un agente o consultar los términos de glosario empresarial importados de Knowledge Catalog que se aplican a las fuentes de conocimiento que has seleccionado para un agente.

• Como los términos del glosario empresarial de Knowledge Catalog se aplican de forma global a los recursos de BigQuery, si usas Knowledge Catalog, crea y gestiona los términos del glosario empresarial en Knowledge Catalog en lugar de hacerlo para agentes concretos.
• Si necesita modificar los términos del glosario empresarial importados de Knowledge Catalog, debe editarlos en Knowledge Catalog y volver a BigQuery para verlos.
• Los términos del glosario personalizado de BigQuery se quedan en BigQuery. No aparecen en Knowledge Catalog.
• Si no usas Knowledge Catalog, puedes crear términos de glosario personalizados de BigQuery para los términos que necesites definir para un agente específico.

Sigue estos pasos para crear términos de glosario personalizados para un agente:

1. En la sección Glosario de la página Editor del agente, haz clic en Añadir término.
2. En la sección Términos personalizados, puede editar o eliminar cualquier término personalizado.
3. Para crear uno o varios términos, haz clic en Crear término.
   1. Introduce un término, una definición y uno o varios sinónimos separados por comas.
   2. Para crear el término, haz clic en Añadir.
   3. Si quieres eliminar el nuevo término, haz clic en Eliminar.
4. Para crear más términos personalizados, repite estos pasos.

Sigue estos pasos para ver los términos del glosario empresarial importados de Knowledge Catalog:

1. En la sección Glosario de la página Editor del agente, haz clic en Añadir término.
2. Ve a la sección de la página llamada Importado de Dataplex.
3. Para modificar los términos importados en Knowledge Catalog, haz clic en Ir a glosarios de Dataplex.
4. Después de modificar los términos en Knowledge Catalog, puede volver a la página Editor del agente para ver los términos modificados.

Configurar los ajustes

En la sección Configuración, puede configurar los siguientes ajustes opcionales:

1. En la sección Modelo, elige los tipos de modelos que pueden usar los usuarios en una conversación con el agente. Los modelos en versión preliminar y con disponibilidad general están disponibles de forma predeterminada. Los modelos que están en versión preliminar pueden usar el endpoint global.

2. 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 Google Cloud recursos.

   1. En la sección Configuración, haz clic en Gestionar etiquetas.
   2. Haz clic en Añadir etiqueta.
   3. En los campos clave y valor, introduzca el par clave-valor de la etiqueta.
   4. Si quieres añadir más etiquetas, vuelve a hacer clic en Añadir etiqueta.
   5. Para eliminar una etiqueta, haz clic en Eliminar.
   6. Cuando hayas terminado, haz clic en Añadir. Se vuelve a abrir la página del nuevo agente.

3. Define un límite de tamaño para las consultas procesadas por el agente de datos. En la sección Configuración, escriba un valor en el campo Máximo de bytes facturados. Debes definir 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 ningún valor, maximum bytes billed se asignará de forma predeterminada a 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.

Ve a la siguiente sección para poner el agente en modo borrador o publicarlo.

Previsualizar y publicar el agente

1. En la sección Vista previa, escribe una pregunta de usuario de ejemplo en el campo Haz una pregunta y, a continuación, pulsa Intro. Para verificar que el agente de datos devuelve los datos que esperas, revisa la respuesta del agente. Si la respuesta no es la que esperas, cambia los ajustes de la sección Editor para perfeccionar la configuración del agente de datos hasta que obtengas respuestas satisfactorias. Puedes seguir probando y modificando tu agente para mejorar sus resultados.

2. Haz clic en Guardar.

3. Para poner el agente de datos en modo borrador, que puedes volver a editar más adelante, haz clic en Volver para volver a la página Catálogo de agentes. Como tu agente está ahora en modo 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 ve al paso siguiente.

4. Haga clic en Publicar para publicar el agente de datos y que se pueda usar en el proyecto. Puedes crear conversaciones con el agente de datos usando BigQuery Studio o Data Studio. También puedes crear tu propia interfaz para chatear con el agente de datos mediante la API de Análisis conversacional. Para obtener información sobre cómo publicar en Data Studio, consulta el artículo Publicar un agente de datos en Data Studio. Para obtener información sobre cómo publicar en Gemini Enterprise, consulta Publicar un agente de datos en Gemini Enterprise.

5. Opcional: En el cuadro de diálogo Tu agente se ha publicado, haz clic en Compartir para compartir el agente de datos con otros usuarios.

   1. En el panel Compartir permisos, haz clic en Añadir principal.

   2. En el campo New principals (Nuevos principales), introduce uno o varios 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): concede permiso para chatear con el agente de datos.
      • Editor de agente de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor): otorga permiso para editar el agente de datos.
      • Visor de agente 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 nuevo agente, haga clic en Cerrar. Inmediatamente después de guardar o publicar tu agente, puedes verlo en el Catálogo de agentes.

Gestionar agentes de datos

Puedes encontrar agentes 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 otros usuarios.
• Mis agentes borrador: agentes que aún no has publicado. No puedes compartir agentes en borrador.
• Compartidos por otros usuarios de tu organización: agentes que otros usuarios crean y comparten contigo. Si otros usuarios te conceden permisos, puedes editar estos agentes compartidos.

Editar 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. Busca la tarjeta del agente de datos que quieras 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 cuadro de diálogo Compartir, puedes compartir el agente con otros usuarios o hacer clic en Cancelar.

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

   

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. Busca la tarjeta del agente de datos que quieras 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 Compartir permisos, haz clic en Añadir principal.

7. En el campo New principals (Nuevos principales), introduce uno o varios principales.

8. Haz clic en la lista Selecciona 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): da permiso para chatear con el agente de datos.
   • Editor de agente de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor): otorga permiso para editar el agente de datos.
   • Visor de agente de datos de Gemini Data Analytics (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 Agentes, haz clic en Volver.

    

Eliminar 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 Mis agentes borrador de la pestaña Catálogo de agentes, busca la tarjeta del agente de datos que quieras eliminar.

4. Haz clic en Abrir acciones > Eliminar.

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

Publicar un agente de datos en Data Studio

Cuando publiques tu agente y lo compartas con los usuarios de Data Studio, el agente aparecerá automáticamente para que esos usuarios puedan chatear con él en la página Chatea con tus datos de Data Studio.

Crear y publicar un agente en Data Studio

Como analista de datos, puedes crear, editar y publicar un agente en Data Studio siguiendo estos pasos:

1. Crea o edita tu agente de datos en BigQuery.
2. Publica el agente. Cuando publiques el agente, selecciona Data Studio como opción de publicación.
3. Sigue las instrucciones para compartir el agente y concede los roles de gestión de identidades y accesos adecuados a tus usuarios de Data Studio.

Compartir tu agente con los usuarios de Data Studio

Puedes compartir agentes directamente con los usuarios de Data Studio copiando un enlace que abra una conversación con el agente en Data Studio o enviando un correo para informar al usuario de que tiene acceso a un agente.

Para compartir un enlace directo al agente, puedes copiar la URL específica del agente de las siguientes formas:

• En el catálogo de agentes, selecciona Abrir acciones > selecciona Copiar enlace > selecciona Data Studio.
• En la vista de detalles del agente, selecciona Copiar enlace del agente > selecciona Data Studio.
• En el menú adicional Compartir, selecciona Copiar enlace al agente en Data Studio.
• Después de hacer clic en Guardar en el panel Permisos para compartir, selecciona Copiar enlace.

Para enviar una notificación por correo que informe a los destinatarios de su acceso a un agente, selecciona Enviar correo en el panel Compartir permisos. Las notificaciones por correo solo se envían a los usuarios o grupos con los que acabas de compartir el agente en esa sesión de edición. Todos los miembros de un grupo reciben la notificación por correo, aunque un usuario concreto ya tenga permiso de nivel de agente para el agente. El correo incluye el nombre del usuario que ha compartido el agente, el nombre del agente y un enlace para abrirlo en Data Studio.

Nota: Si envías un correo a un grupo de Google que tiene la opción Quién puede publicar configurada como Solo los miembros del grupo, un propietario o administrador del grupo debe actualizar los ajustes del grupo a Toda la organización para habilitar el envío.

Publicar un agente de datos en Gemini Enterprise

Vista previa

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

Nota: Para enviar comentarios o solicitar asistencia sobre esta función, envía un correo a [e-mail].

En las siguientes secciones se describe cómo publicar un agente de datos en Gemini Enterprise. Este proceso suele implicar la colaboración entre analistas de datos, administradores de Gemini Enterprise y usuarios empresariales. Para obtener más información sobre los roles necesarios para estos usuarios, consulta Roles necesarios.

Para publicar un agente de datos en Gemini Enterprise, sigue estos pasos:

1. Crea y publica el agente de datos.
2. Configura los detalles de autorización.
3. Aprovisiona el agente.
4. Descubre y usa el agente.

Crear y publicar un agente

Como analista de datos, puedes crear, editar y publicar un agente en Gemini Enterprise siguiendo estos pasos:

1. Crea o edita tu agente de datos en BigQuery.
2. Publica el agente. Cuando publiques el agente, selecciona Gemini Enterprise como opción de publicación.
3. Copia el JSON del endpoint de A2A.
4. Comparte el JSON del endpoint A2A y la lista de usuarios con tu administrador de Gemini Enterprise.
5. Comparte el agente con los usuarios y grupos que necesiten acceso.

Configurar los detalles de la autorización

Para que tu administrador de Gemini Enterprise pueda aprovisionar el agente, tú o el administrador debéis configurar los detalles de autorización para generar credenciales de cliente de OAuth de Google Cloud.

Para crear el ID de cliente y el secreto de cliente de OAuth, sigue los pasos que se indican en Configurar los detalles de autorización.

Aprovisionar un agente

Como administrador de Gemini Enterprise, puedes hacer que un agente publicado esté disponible para los usuarios en la Google Cloud consola.

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

   Gemini Enterprise

2. Haz clic en el nombre de la aplicación en la que quieras registrar el agente.

3. Haz clic en Agentes > Añadir agentes.

4. En la sección Elige un tipo de agente, haz clic en Añadir en Agente personalizado vía A2A.

5. En el campo JSON de la tarjeta del agente, introduce la información de la tarjeta del agente que te haya enviado el analista de datos en formato JSON. Para ver una lista completa de los campos disponibles, consulta la especificación del protocolo Agent2Agent (A2A). En el ejemplo solo se usan los campos obligatorios.

6. Haz clic en Vista previa de los detalles del agente > Siguiente.

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

   1. Introduce el ID de cliente y el secreto de cliente que has generado en la sección Configurar detalles de autorización.

   2. En el campo URI de autorización, introduce 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

      Sustituye client_id por el ID de cliente que has generado en la sección Configurar detalles de autorización.

   3. En el campo URI de token, introduce lo siguiente:

      https://oauth2.googleapis.com/token

   4. En el campo Scopes (Ámbitos), introduce lo siguiente:

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

8. Haz clic en Finalizar.

9. Comparte el agente con los usuarios o grupos que te indique el analista de datos.

Para obtener más información sobre cómo trabajar con agentes de A2A en Gemini Enterprise, consulta Registrar y gestionar agentes de A2A.

Descubrir y usar un agente

Puedes descubrir y usar un agente de datos en Gemini Enterprise con cualquiera de estos métodos:

• Descubrimiento manual: busca un agente de datos en la galería de agentes y úsalo con cualquiera de estos métodos:
  • Explorar la galería: selecciona el agente e inicia una conversación específica.
  • Enlace directo: usa la URL específica del agente para abrir Gemini Enterprise directamente en una sesión con ese agente de datos de BigQuery concreto.
  • Intención dirigida: invoca al agente con @mention (por ejemplo, @sales_pipeline_agent) en la conversación principal de Gemini Enterprise.
  • Orquestación fluida: haz una pregunta analítica general (por ejemplo, "¿Cómo ha evolucionado nuestra cartera de ventas en los últimos tres meses?") y Gemini Enterprise dirigirá automáticamente la consulta al agente de datos pertinente.

Una vez que hayas descubierto el agente, puedes interactuar con él siguiendo estos pasos:

• Autenticar: completa el inicio de sesión único con OAuth para autenticarte de forma segura en BigQuery.
• Chat: haz preguntas al agente en lenguaje natural. El agente procesa las solicitudes y la respuesta se envía a Gemini Enterprise en forma de texto, Markdown, gráficos o tablas.
• Ver el historial de conversaciones: las conversaciones se guardan automáticamente en el panel del historial.

Monitorizar agentes y conversaciones

Vista previa

Esta función está sujeta a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

Nota: Para enviar comentarios o solicitar asistencia sobre esta función, envía un correo a [e-mail].

Puedes monitorizar el rendimiento, la adopción, la latencia y los costes de tus agentes de datos y sus conversaciones mediante Google Cloud Observability en BigQuery. Cuando habilitas la observabilidad de los agentes, puedes ver métricas como las siguientes:

• El número de agentes utilizados en las conversaciones
• Número de usuarios que han hecho preguntas
• Número de conversaciones creadas
• Los agentes que han respondido a más preguntas
• Las fuentes de conocimiento habituales
• Interacción de los usuarios
• Uso de tokens previsto
• Latencia de respuesta por hora

Antes de empezar

Habilita las APIs Cloud Trace, Cloud Monitoring y Cloud Logging.

Roles necesarios para habilitar las APIs

Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si has creado el proyecto, es probable que ya tengas este permiso a través del rol Propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol Administrador de uso de servicio (roles/serviceusage.serviceUsageAdmin). Consulta cómo asignar roles.

Habilita las APIs

Roles y permisos necesarios

Para habilitar la observabilidad del agente, debe tener los siguientes permisos en su proyecto:

• cloudaicompanion.gibqObservabilitySettings.create
• cloudaicompanion.gibqObservabilitySettings.list
• cloudaicompanion.gibqObservabilitySettings.update
• geminidataanalytics.dataAgents.create
• geminidataanalytics.operations.get
• observability.traceScopes.create
• resourcemanager.projects.update
• serviceusage.services.enable
• serviceusage.values.test

Para obtener los permisos que necesitas para monitorizar tus agentes mediante métricas, trazas y registros, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

• Ver datos y configuraciones de monitorización: Lector de Monitoring (roles/monitoring.viewer)
• Ver trazas: Usuario de Cloud Trace (roles/cloudtrace.user)
• Ver registros: Visualizador de registros (roles/logging.viewer)
• Ver conjuntos de datos y su contenido: Lector de datos de BigQuery (roles/bigquery.dataViewer)
• Ver la configuración de administrador: Usuario de Gemini para Google Cloud (roles/cloudaicompanion.user)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Habilitar la observabilidad

La observabilidad del agente está inhabilitada de forma predeterminada. Un administrador puede habilitarlo en tu proyecto u organización. Para habilitar la observabilidad de tus agentes, selecciona una de las siguientes opciones:

Consola

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

   Ir a Agentes

2. Selecciona la pestaña Monitorización.

3. Si la observabilidad está inhabilitada, sigue las indicaciones para habilitarla.

Google Cloud CLI

1. Para crear un ajuste de observabilidad, sigue estos pasos:

   gcloud gemini gibq-observability-settings create SETTING_NAME \
     --conversational-analytics-setting-metrics-enabled \
     --conversational-analytics-setting-traces-enabled \
     --project=PROJECT_ID \
     --location=global

   Haz los cambios siguientes:

   • SETTING_NAME: nombre del ajuste de observabilidad.
   • PROJECT_ID: tu ID de proyecto.

2. Vincula el ajuste de observabilidad a tu proyecto:

   gcloud gemini gibq-observability-settings setting-bindings create BINDING_NAME \
     --gibq-observability-setting=SETTING_NAME \
     --target=projects/PROJECT_ID \
     --location=global \
     --project=PROJECT_ID

   Sustituye BINDING_NAME por el nombre del enlace del ajuste. Te recomendamos que uses binding-PROJECT_ID como nombre de enlace.

API

1. Para crear un ajuste de observabilidad, sigue estos pasos:

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d '{
             "conversational_analytics_setting": {
               "metrics_enabled": true
             }
           }' \
       "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings?gibq_observability_setting_id=SETTING_NAME"

   Haz los cambios siguientes:

   • SETTING_NAME: nombre del ajuste de observabilidad.
   • PROJECT_ID: tu ID de proyecto.

2. Vincula el ajuste de observabilidad a tu proyecto:

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d '{
             "target": "projects/PROJECT_ID",
             "product": "GEMINI_IN_BIGQUERY"
           }' \
       "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings/SETTING_NAME/settingBindings?setting_binding_id=BINDING_NAME"

   Sustituye BINDING_NAME por el nombre del enlace del ajuste. Te recomendamos que uses binding-PROJECT_ID como nombre de enlace.

Ver métricas

Las métricas se recogen después de habilitar la observabilidad. Los datos no se rellenan. Para ver las métricas de los agentes, selecciona una de las siguientes opciones:

BigQuery

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

   Ir a Agentes

2. Selecciona la pestaña Monitorización.

Cloud Monitoring

1. En la Google Cloud consola, ve a la página Paneles de control de Cloud Monitoring.

   Ir a Paneles

2. En el panel Mis paneles de control, busca el panel de control llamado BigQuery Conversational Analytics.

3. Para abrir el panel de control, haz clic en su nombre.

4. Opcional: Crea un panel de control personalizado.

5. Opcional: Para ver las métricas individualmente, ve a la página Explorador de métricas.

   Ir a Explorador de métricas

   Las métricas de los agentes incluyen el uso de los agentes, las llamadas a modelos, el uso de herramientas, el estado, la latencia y el uso de tokens.

Depurar llamadas de modelos

Puedes visualizar la secuencia de operaciones de una conversación, como las llamadas al modelo y a herramientas, para solucionar errores y problemas de latencia.

1. En la Google Cloud consola, ve a la página Explorador de trazas de Cloud Monitoring.

   Ir a Explorador de trazas

2. Haz clic en un intervalo para examinarlo.

3. Revisa la información del panel Detalles.

4. Opcional: Crea un panel de control de seguimiento personalizado.

Conservar trazas

Tus datos de Cloud Trace se almacenan en un conjunto de datos de observabilidad durante 30 días. Para almacenar los datos de seguimiento durante más tiempo, muévelos a un conjunto de datos de BigQuery.

Roles obligatorios

Para obtener los permisos que necesitas para exponer las trazas activas en BigQuery creando un conjunto de datos vinculado, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y accesos en tu proyecto:

• Administrador de Cloud Trace (roles/cloudtrace.admin)
• Editor de observabilidad (roles/observability.editor)
• Usuario de BigQuery (roles/bigquery.user)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Mover datos de trazas a BigQuery

Para conservar los datos de la traza, haz lo siguiente:

1. Abre Cloud Shell.

2. Busca la ubicación de tu _Tracesegmento:

   gcloud beta observability buckets list --location=-

   Anota la ubicación de tu contenedor _Trace para el siguiente paso.

3. Crea un conjunto de datos vinculado en tu proyecto de BigQuery que apunte a tu segmento de _Trace:

   gcloud beta observability buckets datasets links create \
       projects/PROJECT_ID/locations/LOCATION/buckets/_Trace/datasets/Spans/links/LINK_NAME \
       --dataset=Spans \
       --bucket=_Trace \
       --location=LOCATION \
       --project=PROJECT_ID

   Haz los cambios siguientes:

   • PROJECT_ID: tu ID de proyecto
   • LOCATION: la ubicación de tu _Trace del paso anterior
   • LINK_NAME: nombre del conjunto de datos vinculado

4. Crea un conjunto de datos estándar en el que almacenar tu historial de seguimientos. El siguiente comando define la caducidad de la partición predeterminada en 90 días (7.776.000 segundos):

   bq --location=LOCATION mk \
       --dataset \
       --default_partition_expiration=7776000 \
       --description="Archive storage for historical traces" \
       PROJECT_ID:STORAGE_DATASET

   Sustituye STORAGE_DATASET por el nombre del conjunto de datos.

5. Crea una tabla con particiones vacía en tu conjunto de datos de almacenamiento con el mismo esquema que el conjunto de datos vinculado. La partición por fecha te ayuda a gestionar la conservación de datos y los costes de las consultas. Para crear la tabla, ejecuta la siguiente consulta en el editor de SQL:

   CREATE TABLE `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
   PARTITION BY DATE(start_time)
   AS
   SELECT *
   FROM `PROJECT_ID.LINK_NAME._AllSpans`
   WHERE FALSE;

   Sustituye TABLE_NAME por el nombre de la tabla.

6. Crea una consulta programada para copiar diariamente los datos de la traza del conjunto de datos vinculado en tu tabla de archivo. La siguiente consulta copia los datos del día anterior:

   INSERT INTO `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
   SELECT *
   FROM `PROJECT_ID.LINK_NAME._AllSpans`
   WHERE start_time >=
     TIMESTAMP_SUB(TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY), INTERVAL 1 DAY)
     AND start_time < TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY);

Para obtener más información, consulta cómo buscar y explorar trazas.

Desactivar la observabilidad

Para desactivar la observabilidad de tus agentes de datos, actualiza el ajuste de observabilidad:

gcloud gemini gibq-observability-settings update SETTING_NAME \
    --no-conversational-analytics-setting-metrics-enabled \
    --no-conversational-analytics-setting-traces-enabled \
    --project=PROJECT_ID \
    --location=global

Haz los cambios siguientes:

• SETTING_NAME: Nombre del ajuste de observabilidad que has creado para habilitar la observabilidad. Si has habilitado la observabilidad mediante la consola Google Cloud , el nombre del ajuste es default.
• PROJECT_ID: tu ID de proyecto.

Siguientes pasos

• Más información sobre las analíticas conversacionales en BigQuery
• Consulta más información sobre la API Conversational Analytics.
• Analizar datos con conversaciones
• Consulta más información sobre cómo el rol Lector del agente de datos de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentViewer) permite ver el agente de datos.