Crea 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, además, instrucciones de procesamiento de consultas específicas de casos 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. Verifica que la facturación esté habilitada para tu proyecto de Google Cloud .

2. Habilita las APIs de BigQuery, Gemini Data Analytics, Gemini para Google Cloudy Knowledge Catalog, si aún no están habilitadas.

   Roles necesarios para habilitar las APIs

   Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

   Habilitar las API

Roles obligatorios

Para trabajar con agentes de datos, debes tener permisos de Identity and Access Management (IAM) que coincidan con tu caso de uso. En las siguientes secciones, se enumeran los roles necesarios según si creas y publicas agentes, aprovisionas agentes en Gemini Enterprise o descubres y usas agentes en varias plataformas. Para obtener más información, consulta Roles de IAM de la API de Conversational Analytics.

• Crea, edita, publica, comparte y borra agentes:
  • Para crear agentes de datos en un proyecto: Creador de agentes de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentCreator) en el proyecto. Este rol te otorga automáticamente el rol de propietario de agentes de datos de Gemini Data Analytics en los agentes de datos que crees.
  • Para editar, compartir o borrar un agente de datos, se requiere el rol de propietario de agentes de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentOwner) en el agente o proyecto.
  • Para editar un agente de datos en un proyecto: Editor de agentes de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentEditor) en el proyecto.
  • Para ver los agentes de datos en un proyecto: Visualizador de agentes de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) en el proyecto.
• 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 personalizados y configurar un Agent Gateway en la Consola del administrador de Gemini Enterprise.
• Descubre y usa agentes:
  • Para chatear con agentes de datos: Usuario de agente de datos de Análisis de datos de Gemini (roles/geminidataanalytics.dataAgentUser).
  • Para ver todos los agentes de datos del proyecto: Visualizador de agentes de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer).
  • Para interactuar con la interfaz de chat potenciada por Gemini en Data Studio: Usuario de BigQuery Studio (roles/bigquery.studioUser) o Usuario de Gemini para Google Cloud (roles/cloudaicompanion.user), cada uno de los cuales proporciona el permiso cloudaicompanion.topics.create. Otorga estos roles a nivel del proyecto. Los usuarios también necesitan el rol de Visualizador de recursos de Data Studio (roles/datastudio.viewer).
• Agrega fuentes de conocimiento a un agente:
  • Visualizador de Data Catalog (roles/datacatalog.viewer) en el proyecto.
• Configura y visualiza los registros de conversaciones:
  • Para crear el conjunto de datos de registro y otorgar acceso en el proyecto del agente: bigquery.datasets.create y propietario de datos de BigQuery (roles/bigquery.dataOwner) o administrador de BigQuery (roles/bigquery.admin) en el conjunto de datos de registro.
  • Para cambiar la configuración de registro de conversaciones de un agente, usa geminidataanalytics.dataAgents.update, que se incluye en el rol de editor de agentes de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor).
  • Para que el agente de servicio de la API de Conversational Analytics ([e-mail]) cree la tabla de registros y escriba filas: Editor de datos de BigQuery (roles/bigquery.dataEditor) en el conjunto de datos de registros. Si el conjunto de datos de registro usa claves de Cloud KMS administradas por el cliente (CMEK), otorga a la cuenta de servicio de encriptación de BigQuery ([e-mail]) el rol de encriptador/desencriptador de CryptoKey de Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter) en la clave de Cloud KMS.
  • Para los analistas que consultan registros de conversaciones: Visualizador de datos de BigQuery (roles/bigquery.dataViewer) en el conjunto de datos de registro y Usuario de trabajo de BigQuery (roles/bigquery.jobUser) en un proyecto para ejecutar consultas.

Para tener 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 tienes permiso para acceder.

Prácticas recomendadas

Las estadísticas conversacionales ejecutan consultas automáticamente en tu nombre para responder tus preguntas. Ten en cuenta los siguientes factores que podrían aumentar el costo de las consultas:

• Tamaños de tablas grandes
• Uso de uniones de datos en consultas
• Llamadas frecuentes a funciones de IA dentro de las consultas

Generar estadísticas

De forma opcional, puedes generar estadísticas de datos en Knowledge Catalog para cualquier tabla que quieras usar como fuente de conocimiento.

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

Si no generas estadísticas de antemano, el sistema las genera automáticamente cuando seleccionas una tabla como fuente de conocimiento mientras creas un agente de datos.

Trabaja con el agente de datos de muestra

Si no estás familiarizado con la configuración de agentes para el análisis conversacional, puedes ver el agente de muestra predefinido que se genera para cada proyecto de Google Cloud . Puedes chatear con él y ver sus parámetros para saber cómo se creó, pero no puedes modificarlo.

Para ver el agente de ejemplo, haz lo siguiente:

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

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

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

Primeros pasos

1. En la consola de Google Cloud , ve a la página Agentes 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 lo que 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 Agregar fuente. Se abrirá la página Agregar fuente de conocimiento.

7. En la sección Recientes, selecciona las tablas, vistas, gráficos o UDF que desees usar como fuentes de conocimiento. Las UDF tienen el prefijo "fx" en la consola de Google 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. No es necesario que el nombre de la fuente sea 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 afecta 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 entiende el esquema. Si las descripciones sugeridas por el agente son correctas, puedes aceptarlas.

• Si el agente de datos no muestra una comprensión del esquema después de configurar estas descripciones, ajusta manualmente las descripciones 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 sugeridos 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 cualquier 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 las actualizaciones de la descripción y 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.

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

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 las instrucciones para el agente de datos en el campo Instrucciones del agente. Debido a que el agente de datos usa estas instrucciones para comprender el contexto de las preguntas de los usuarios y proporcionar respuestas, haz que las instrucciones sean lo más claras posible.

Si no obtienes una respuesta satisfactoria del agente, agrega contexto estructurado, como descripciones, ejemplos o términos del glosario. Si aún no obtienes una respuesta satisfactoria, agrega instrucciones personalizadas como 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	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 refiera a un cronograma o a 'a lo largo del tiempo', usa siempre la columna order_created_date". "Cuando alguien diga 'por producto', agrupa 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, filtra siempre los datos por order_status = 'Complete'".
Sinónimos y términos comerciales	Términos alternativos para los campos clave	"Si alguien pregunta sobre 'Ingresos' o 'Ventas', usa la columna total_sale_amount". "Consideramos que los clientes 'leales' son aquellos con purchase_count > 5".
Campos excluidos	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 con los clientes) events.user_id = users.id (para vincular la actividad del sitio web con los clientes que accedieron a su cuenta)

Crea consultas verificadas

Un agente usa consultas verificadas de dos maneras:

• Si un agente puede usar una consulta verificada para responder una pregunta que le hagas, para garantizar una respuesta confiable, el agente invoca la consulta exactamente como está escrita.
• Si el agente no puede usar la consulta verificada para responder una pregunta, igual la usa como referencia para comprender los datos y las prácticas recomendadas para consultarlos.

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

Nota: Para crear una consulta verificada parametrizada, consulta Crea consultas verificadas parametrizadas.

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

1. Selecciona una o más consultas verificadas sugeridas por Gemini:

   1. En la sección Consultas verificadas, haz clic en Revisar sugerencias. Se abrirá la página Revisa las consultas verificadas sugeridas.
   2. Revisa las consultas verificadas sugeridas. Selecciona las 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 consulta verificada, haz clic en Agregar consulta. Se abrirá la página Agregar consulta verificada.

   1. En el campo Pregunta, escribe la pregunta del usuario 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 especificaste.
   3. Modifica la consulta verificada si lo deseas.
   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 consultas verificadas adicionales.

Crea consultas verificadas con parámetros

Las consultas verificadas parametrizadas extraen valores de la pregunta de un usuario para el agente de estadísticas conversacionales y proporcionan resultados personalizados.

Los analistas y creadores pueden crear plantillas de SQL reutilizables que contengan marcadores de posición para estos valores. Las plantillas sustituyen de forma dinámica los parámetros en el entorno de ejecución para responder a una variedad más amplia de preguntas de los usuarios que las consultas verificadas habituales.

Cuando un usuario hace una pregunta que coincide con el patrón de la plantilla, el agente de estadísticas conversacionales extrae los valores de los parámetros de la pregunta, por ejemplo, el nombre del producto, la región y la fecha. Luego, inserta estos valores en la consulta parametrizada. Las respuestas coincidentes de la plantilla de consulta aparecen como verificadas.

Las consultas verificadas con parámetros mejoran significativamente la potencia y la flexibilidad de las consultas verificadas. Garantizan respuestas coherentes y confiables en varias entradas y reducen la cantidad de consultas individuales que se deben mantener.

Cómo funciona

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

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

Después de que se guarda la consulta verificada, un usuario puede hacerle una pregunta al agente de estadísticas conversacionales en lenguaje natural, por ejemplo, "¿Cuáles fueron las ventas de laptops en Norteamérica?".

Para responder la pregunta del usuario, el agente realiza los siguientes 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 (NLU) para identificar y extraer los valores de @region (América del Norte) y @product (laptops) de la pregunta del usuario.
2. Sustituye los valores extraídos en los marcadores de posición @region y @product en la plantilla de SQL.
3. Ejecuta la consulta en 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.

Sugerencias 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 grande (LLM) para el análisis 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.
• Garantiza una escritura de datos coherente. Asegúrate de que los tipos de datos que espera la consulta en SQL coincidan con los tipos de datos que probablemente se extraerán de la pregunta del usuario.
• Proporciona un alcance bien definido. Crea plantillas para patrones de preguntas comunes e importantes en los que la construcción de la consulta sea compleja o la lógica no sea intuitiva. Esto ayuda a que el LLM devuelva resultados óptimos.
• Realiza pruebas exhaustivas. Realiza pruebas con varias frases en lenguaje natural para asegurarte de que los parámetros se extraigan correctamente.

Crea una consulta verificada parametrizada

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

Antes de crear o modificar una consulta, redacta la consulta teniendo en cuenta el patrón de lenguaje natural y tu pregunta. Por ejemplo, si preguntas "¿Sabemos el stock total de bananas orgánicas en el almacén US-EAST?", puedes reescribir la pregunta como la consulta verificada parametrizada como "¿Cuál es el stock total de @product en el almacén @region?" El agente convierte esta pregunta en una consulta en SQL que actualizas con valores predeterminados.

Para crear una consulta verificada parametrizada para un agente de datos, puedes crear una consulta nueva cuando creas un agente nuevo o puedes editar una consulta verificada existente para un agente nuevo o existente.

En las siguientes instrucciones, se usa una consulta verificada de muestra para configurar con parámetros.

Selecciona una consulta verificada existente sugerida por Gemini

1. En la sección Consultas verificadas de un agente nuevo o existente, haz clic en Revisar sugerencias. Se abrirá la página Revisa las consultas verificadas sugeridas.
2. Selecciona la casilla de verificación junto a una búsqueda verificada sugerida.
3. En la ventana de consulta, haz clic en Mostrar más para expandir la descripción de la consulta.
4. Para abrir la consulta existente, haz clic en Editar.
5. Para terminar de configurar la consulta, consulta Configura los parámetros de la consulta verificada.

Crea un agente y, luego, una consulta verificada

1. Consulta Pasos iniciales y continúa con el resto de los pasos de configuración para Consultas verificadas.
2. En la consola de Google Cloud , en la sección Consultas verificadas del agente nuevo, haz clic en Agregar consulta. Se abrirá la página Agregar consulta verificada.
3. Para terminar de configurar la consulta, consulta Configura los parámetros de la consulta verificada.

Configura los parámetros para la consulta verificada

1. En el campo Pregunta, escribe la pregunta del usuario que responde la consulta verificada.
2. Para especificar parámetros, usa el símbolo @ seguido de un nombre de parámetro. Esta sintaxis identifica un marcador de posición que transfiere 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 se ve como en el siguiente ejemplo:

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

4. Para agregar valores predeterminados a los marcadores de posición de la consulta, haz clic en Administrar parámetros de consulta y, luego, en Agregar parámetro de consulta.

5. Para 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, ingresa organic bananas.
   • En Descripción, ingresa una descripción lo más específica posible. Por ejemplo, un producto ubicado en un almacén regional.

6. Para el segundo parámetro, haz clic en Agregar parámetro de consulta.

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

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

Prueba la consulta verificada parametrizada

1. Haz clic en Ejecutar y verifica que la consulta devuelva los resultados que esperas.
2. Para probar la consulta para los usuarios en una pantalla posterior, copia todo el campo de la pregunta.
3. Haz clic en Guardar para salir de la pantalla Agregar consulta y volver a la página Editar del agente.
4. En la página Editar del agente, pega el campo de la pregunta que copiaste anteriormente en la ventana Vista previa.
   1. Reemplaza la variable @product por organic bananas.
   2. Reemplaza la variable @region por US-EAST.
5. Presiona Intro. Verifica el resultado. En este caso, una respuesta válida es la cantidad total de bananas en stock en la región US-EAST, por ejemplo, 1,000.
6. Para crear o editar más consultas verificadas, repite estos pasos según sea necesario.

Ahora que guardaste la consulta, un usuario puede hacer la pregunta "¿Sabemos cuál es el stock total de bananas orgánicas en el almacén US-EAST?" Luego, Conversational Analytics hace lo siguiente:

1. Hace coincidir esta pregunta con el patrón.
2. Extrae el parámetro @product como @product = "organic bananas" y el parámetro @region = "US-EAST" 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 total_stock calculado.

Crea o revisa términos del glosario

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

• Debido a que 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 administra los términos del glosario empresarial en Knowledge Catalog en lugar de para agentes individuales.
• Si necesitas modificar los términos del glosario empresarial importados de Knowledge Catalog, debes editarlos en Knowledge Catalog y volver a BigQuery para verlos.
• Los términos del glosario personalizado de BigQuery permanecen en BigQuery. No aparecen en Knowledge Catalog.
• Si no usas Knowledge Catalog, puedes crear términos del glosario personalizados de BigQuery para los términos que necesitas 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 Agregar término.
2. En la sección Términos personalizados, puedes editar o borrar cualquier término personalizado existente.
3. Para crear uno o más términos nuevos, haz clic en Crear término.
   1. Ingresa un Término, una Definición y uno o más Sinónimos separados por una coma.
   2. Para crear el término, haz clic en Agregar.
   3. Si quieres borrar el término nuevo, haz clic en Borrar.
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 Agregar término.
2. Navega 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 los glosarios de Dataplex.
4. Después de modificar los términos en Knowledge Catalog, puedes volver a la página Editor del agente para ver los términos modificados.

Establece la configuración

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

1. En la sección Modelo, elige qué tipos de modelos están disponibles para 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 extremo global.

2. Crea 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 sección Configuración, haz clic en Administrar etiquetas.
   2. Haz clic en Agregar etiqueta.
   3. En los campos clave y valor, ingresa el par clave-valor de 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.

3. Para escribir los eventos de conversación del agente en una tabla de BigQuery en el proyecto del agente para la supervisión y el análisis, en la sección Registro de conversaciones, activa Habilitar el registro de conversaciones:

   1. Si la configuración de registro de conversaciones no está disponible cuando editas un agente existente, cambia el selector de vista a Borrador y asegúrate de que se seleccionen tablas de BigQuery específicas como fuentes de conocimiento.

   2. En Establece un destino para almacenar los registros, selecciona un conjunto de datos de destino existente en el proyecto del agente en ID del conjunto de datos. En ID de tabla, selecciona una tabla existente o haz clic en Seleccionar o crear una tabla > + Tabla nueva, ingresa un nombre de tabla en Especificar tabla nueva (por ejemplo, agent_events) y haz clic en Guardar.

   3. Revisa el Aviso de divulgación para el usuario y registro de datos.

   4. Espera a que se valide la configuración. Si el conjunto de datos no existe, primero créalo en BigQuery. Si el agente de servicio de la API de Conversational Analytics ([e-mail]) no tiene acceso al conjunto de datos, haz clic en Otorgar acceso para otorgar roles/bigquery.dataEditor en el conjunto de datos o pídele a tu administrador que lo otorgue.

   Después de publicar el agente, haz una pregunta de prueba desde la pantalla de chat principal del agente publicado (la sección Vista previa no se registra) y actualiza el conjunto de datos de destino en BigQuery Studio para confirmar que aparezca la tabla de registro. Para actualizar el destino o desactivar el registro más adelante, edita el agente y publica los cambios (las filas existentes no se borran). Para obtener más información, consulta Descripción general del registro de conversaciones.

4. 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 un valor superior. 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 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, 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 la respuesta del agente. 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 perfeccionar 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 Atrás para volver a la página 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 de agentes y continúa con el siguiente paso.

4. Haz clic en Publicar para abrir el panel Canales de publicación y publicar el agente de datos, lo que lo pondrá a disposición para su uso en el proyecto.

5. Opcional: En el cuadro de 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 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 de 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.

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, puedes verlo en el Catálogo de agentes.

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 usando la API de Conversational Analytics. Para obtener información sobre cómo publicar en Data Studio, consulta Publica un agente de datos en Data Studio. Para obtener información sobre cómo publicar en Gemini Enterprise, consulta Publica un agente de datos en Gemini Enterprise.

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 agentes en borrador.
• 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.

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

   

Comparte 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 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 Compartir permisos, 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 de 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 Agentes, haz clic en Volver.

    

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

4. Haz clic en Abrir acciones > Borrar.

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

Publica un agente de datos en Data Studio

Cuando publicas tu agente y lo compartes con los usuarios de Data Studio, el agente aparece automáticamente para que esos usuarios chateen con él en la página Chatea con tus datos de Data Studio.

Crea y publica tu agente en Data Studio

Como analista de datos, puedes crear, editar y publicar un agente en Data Studio completando los siguientes pasos:

1. Crea o edita tu agente de datos en BigQuery.
2. Publica el agente. Cuando publiques el agente, selecciona Data Studio como la opción de publicación.
3. Sigue las instrucciones para compartir el agente y otorgar los roles de Identity and Access Management adecuados a tus usuarios de Data Studio.

Comparte tu agente con los usuarios de Data Studio

Puedes compartir agentes con los usuarios de Data Studio directamente copiando un vínculo que abre una conversación con el agente en Data Studio o puedes enviar un correo electrónico para informar al usuario que tiene acceso a un agente.

Para compartir un vínculo directo al agente, puedes copiar su URL dedicada de las siguientes maneras:

• En el catálogo de agentes, selecciona Abrir acciones > selecciona Copiar vínculo > selecciona Data Studio.
• En la vista de detalles del agente, selecciona Copiar vínculo del agente > selecciona Data Studio.
• En el menú ampliado Compartir, selecciona Copiar vínculo al agente en Data Studio.
• Después de hacer clic en Guardar en el panel Permisos de uso compartido, selecciona Copiar vínculo.

Para enviar una notificación por correo electrónico que informe a los destinatarios sobre su acceso a un agente, selecciona Enviar correo electrónico en el panel Compartir permisos. Las notificaciones por correo electrónico 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 electrónico, incluso si un usuario determinado ya tiene permiso a nivel de agente para el agente. El correo electrónico incluye el nombre del usuario que compartió el agente, el nombre del agente y un vínculo para abrirlo en Data Studio.

Nota: Si envías un correo electrónico a un Grupo de Google que tiene el parámetro de configuración Quiénes pueden publicar establecido en Solo miembros del grupo, un propietario o administrador del grupo debe actualizar el parámetro de configuración del grupo a Toda la organización para habilitar las entregas.

Publica un agente de datos en Gemini Enterprise

Puedes publicar un agente de datos de BigQuery en Gemini Enterprise para que los usuarios empresariales puedan consultar y analizar datos con lenguaje natural directamente en Gemini Enterprise. Por lo general, este proceso implica 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 requeridos.

Para publicar un agente de datos en Gemini Enterprise, completa los siguientes pasos:

1. Revisa los requisitos previos.
2. Crea y publica el agente de datos en BigQuery.
3. Aprovisiona el agente en Gemini Enterprise.
4. Descubre al agente y chatea con él.

Revisa los prerrequisitos

La forma recomendada de publicar agentes de Conversational Analytics de BigQuery es con el Registro de agentes. Sigue los requisitos previos de esta sección para asegurarte de que el agente se pueda descubrir en Gemini Enterprise.

Como alternativa, puedes publicar el agente con el JSON de la tarjeta de A2A. Si usas este método, consulta Crea y publica el agente de datos en BigQuery.

Para usar el Registro de agentes, primero debes configurar la puerta de enlace de agentes con la asignación de regiones adecuada. La región de almacenamiento del agente de datos de BigQuery y la vinculación del registro de Agent Gateway en Gemini Enterprise deben coincidir.

Configura la región de almacenamiento del agente en la sección Región del editor de agentes en la IU web de BigQuery. No puedes cambiar la región después de guardar el agente.

En la siguiente imagen, se muestran las opciones de región disponibles en Agent Gateway:

Como administrador de Gemini Enterprise, configura un Agent Gateway para tu aplicación de Gemini Enterprise completando los siguientes pasos:

1. Configura una Agent Gateway que incluya la vinculación de Agent Registry que coincida con la región de tu agente de datos. Las opciones incluyen EE.UU., UE o Global.
2. En Gemini Enterprise, abre tu aplicación, ve a Seguridad > Configuración y, luego, ingresa el nombre del recurso de la puerta de enlace en la sección Configuración de Agent Gateway. Para obtener instrucciones detalladas, consulta Enruta el tráfico de Gemini Enterprise a través de Agent Gateway.

Crea y publica el agente de datos en BigQuery

Como analista de datos, puedes crear, configurar y publicar un agente en BigQuery completando los siguientes pasos:

1. En BigQuery, crea o edita tu agente de datos.
2. En la sección Región, verifica que la región de almacenamiento coincida con tus fuentes de datos y la configuración de Agent Gateway. Las opciones incluyen EE.UU., UE o Global.
3. Haz clic en Publicar o Publicar actualizaciones si el agente se publicó anteriormente.
4. En el panel Canales de publicación, en Canales adicionales, elige tu método de publicación:
   • Si BigQuery y Gemini Enterprise están en el mismo proyecto, en la sección Registro de agentes, selecciona la casilla de verificación Registrar este agente.
     • Si quieres quitar el agente del registro, haz clic en Cancelar registro.
   • Si BigQuery y Gemini Enterprise están en proyectos diferentes, en la sección Integrar a través de A2A (Agent2Agent), haz clic en Copiar JSON para copiar los datos JSON del extremo de A2A y, luego, comparte los datos JSON con tu administrador de Gemini Enterprise. Estos datos JSON se usan cuando aprovisionas el agente en la sección Gemini Enterprise.
5. Haz clic en Publicar o Publicar actualizaciones.
6. Comparte el agente con los usuarios y grupos que necesitan acceso y otórgales el rol de usuario del agente de datos de Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser).

Aprovisiona el agente en Gemini Enterprise

Como administrador de Gemini Enterprise, pon el agente de datos a disposición de los usuarios de tu aplicación con uno de los siguientes métodos:

Opción 1: Importa desde Agent Registry

Sigue estos pasos para importar el agente registrado:

1. Si Gemini Enterprise está en un proyecto diferente del proyecto de BigQuery, completa los siguientes pasos para registrar manualmente el agente en Agent Registry. De lo contrario, omite este paso:
   1. En la consola de Google Cloud , ve a Registro de agentes en el mismo proyecto que Gemini Enterprise, selecciona la pestaña Agentes y, luego, haz clic en Agregar agente.
   2. En el panel Detalles del agente, en Tipo, selecciona A2A.
   3. En Región, selecciona la región que coincida con la configuración de tu agente de datos y Agent Gateway.
   4. Selecciona Pegar JSON, pega los datos JSON del extremo de A2A de BigQuery y, luego, haz clic en Guardar.
2. En Gemini Enterprise, haz clic en el nombre de la app a la que deseas agregar el agente.
3. En el menú de navegación, haz clic en Agentes > haz clic en Agregar agente.
4. En el panel Elige un tipo de agente, busca Agentes del registro de agentes y haz clic en Agregar.
5. En el panel Agregar agente, busca el agente por nombre, ID del registro de agentes, tipo, productor o caso de uso, o busca la tarjeta del agente en la lista.
6. En la tarjeta del agente, haz clic en Agregar agente.
7. En el paso Revisar los detalles del agente, revisa los metadatos del agente propagados desde la tarjeta de A2A del agente, incluidos el nombre, la descripción, la URL del agente, las capacidades y las habilidades, y, luego, haz clic en Siguiente.
8. En el paso Autenticar agente, selecciona cómo se autentica Gemini Enterprise con el proveedor del agente:
   • Credenciales predeterminadas administradas por Google: Google administra las credenciales de OAuth de forma automática. No es necesario que configures o ingreses las credenciales del cliente de forma manual.
   • OAuth personalizado: Selecciona esta opción solo si tu organización requiere credenciales de cliente de OAuth personalizadas y, luego, ingresa el ID de cliente, el secreto del cliente, la URL de autorización y la URL del token.
9. Haz clic en Finalizar.
10. El agente aparece en la tabla Agentes con el estado Habilitado y el tipo de agente A2A (personalizado).
11. Comparte el agente con los usuarios o grupos que necesitan acceso.

Opción 2: Importa con el JSON de la tarjeta de A2A

Vista previa

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Si BigQuery y Gemini Enterprise están en proyectos diferentes, sigue estos pasos para importar el agente con el JSON de la tarjeta A2A:

1. En Gemini Enterprise, haz clic en el nombre de la app a la que deseas agregar el agente.
2. En el menú de navegación, haz clic en Agentes > haz clic en Agregar agente.
3. En el panel Elige un tipo de agente, busca Agente personalizado con A2A y haz clic en Agregar.
4. En el campo JSON de la tarjeta del agente, ingresa el JSON de la tarjeta del agente que recibiste del analista de datos.
5. Haz clic en Obtener vista previa de los detalles del agente > haz clic en Siguiente.
6. En el paso Autorización del agente, selecciona tu método de autenticación:
   • Credenciales predeterminadas administradas por Google: Google administra las credenciales de OAuth automáticamente sin que tengas que ingresar o generar un ID de cliente y un secreto del cliente de forma manual.
   • OAuth personalizado: Selecciona esta opción si quieres proporcionar credenciales de OAuth personalizadas de forma manual, siguiendo los pasos que se indican en Registra y administra agentes A2A.
7. En el paso Autorizaciones de herramientas, haz clic en Finalizar.
8. El agente aparece en la tabla Agentes con el estado Habilitado y el tipo de agente A2A (personalizado).
9. Comparte el agente con los usuarios o grupos que necesitan acceso.

Descubre y usa un agente

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

• Descubrimiento manual: Ubica un agente de datos en la Galería de agentes y úsalo con cualquiera de estos métodos:
  • Explora la galería: Selecciona el agente y comienza un chat exclusivo.
  • Vínculo directo: Usa la URL dedicada del agente para abrir Gemini Enterprise directamente en una sesión con ese agente de datos de BigQuery específico.
  • Intención dirigida: Invoca al agente con @mention (por ejemplo, @sales_pipeline_agent) en el chat principal de Gemini Enterprise.
  • Organización fluida: Haz una pregunta analítica general (por ejemplo, "¿Cómo está evolucionando nuestra canalización de ventas en los últimos 3 meses?") y Gemini Enterprise enruta automáticamente la consulta al agente de datos pertinente.

Después de descubrir el agente, puedes interactuar con él siguiendo estos pasos:

• Autenticar: Completa el acceso único de OAuth para autenticarte de forma segura en BigQuery.
• Chat: Haz preguntas en lenguaje natural al agente. El agente procesa las solicitudes y la respuesta se transmite de vuelta a Gemini Enterprise como texto, Markdown, gráficos o tablas.
• Ver el historial de conversaciones: Las conversaciones se guardan automáticamente en el panel del historial.

Supervisa agentes y conversaciones

Vista previa

Esta función está sujeta a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “sin modificaciones” y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

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

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

• La cantidad de agentes que se usan en las conversaciones
• La cantidad de usuarios que hicieron preguntas
• La cantidad de conversaciones creadas
• Los agentes que respondieron la mayor cantidad de preguntas
• Las fuentes de conocimiento de uso frecuente
• Participación del usuario
• Uso de tokens proyectado
• Latencia de respuesta por hora

Antes de comenzar

Habilita las APIs de Cloud Trace, Cloud Monitoring y Cloud Logging, si aún no están habilitadas.

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén información para otorgar roles.

Habilitar las API

Roles y permisos requeridos

Para habilitar la observabilidad de agentes, debes tener los siguientes permisos en tu proyecto:

• cloudaicompanion.gibqObservabilitySettings.create
• cloudaicompanion.gibqObservabilitySettings.list
• cloudaicompanion.gibqObservabilitySettings.update
• cloudaicompanion.settingBindings.gibqObservabilitySettingsCreate
• cloudaicompanion.settingBindings.gibqObservabilitySettingsList
• cloudaicompanion.settingBindings.gibqObservabilitySettingsUse
• 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 supervisar tus agentes con métricas, seguimientos y registros, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

• Visualiza los datos y las configuraciones de supervisión: Visualizador de Monitoring (roles/monitoring.viewer)
• Visualiza seguimientos: Usuario de Cloud Trace (roles/cloudtrace.user)
• Visualiza los registros: Visor de registros (roles/logging.viewer)
• Visualiza conjuntos de datos y su contenido: Lector de datos de BigQuery (roles/bigquery.dataViewer)
• Consulta la configuración de administrador: Usuario de Gemini para Google Cloud (roles/cloudaicompanion.user)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Habilita la observabilidad

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

Console

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

   Ir a Agentes

2. Selecciona la pestaña Supervisión.

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

Google Cloud CLI

1. Crea un parámetro de configuración de observabilidad:

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

   Reemplaza lo siguiente:

   • SETTING_NAME: Es un nombre para el parámetro de configuración de observabilidad.
   • PROJECT_ID: ID del proyecto

2. Vincula el parámetro de configuración 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

   Reemplaza BINDING_NAME por un nombre para la vinculación de la configuración. Te recomendamos que uses binding-PROJECT_ID para el nombre de la vinculación.

API

1. Crea un parámetro de configuración de observabilidad:

   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"

   Reemplaza lo siguiente:

   • SETTING_NAME: Es un nombre para el parámetro de configuración de observabilidad.
   • PROJECT_ID: ID del proyecto

2. Vincula el parámetro de configuración 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"

   Reemplaza BINDING_NAME por un nombre para la vinculación de la configuración. Te recomendamos que uses binding-PROJECT_ID para el nombre de la vinculación.

Ver métricas

Las métricas se recopilan después de que habilitas la observabilidad. Los datos no se reabastecen. Para ver las métricas del agente, selecciona una de las siguientes opciones:

BigQuery

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

   Ir a Agentes

2. Selecciona la pestaña Supervisión.

Cloud Monitoring

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

   Ir a Paneles

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

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

4. Opcional: Crea un panel personalizado.

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

   Ir al Explorador de métricas

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

Depura las llamadas al modelo

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

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

   Ir al Explorador de seguimiento

2. Haz clic en un intervalo para examinarlo.

3. Revisa la información en el panel Detalles.

4. Opcional: Crea un panel de seguimiento personalizado.

Conserva los seguimientos

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

Roles obligatorios

Para obtener los permisos que necesitas para exponer seguimientos en vivo a BigQuery creando un conjunto de datos vinculado, pídele a tu administrador que te otorgue los siguientes roles de IAM 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 otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Mueve los datos de seguimiento a BigQuery

Para conservar tus datos de seguimiento, haz lo siguiente:

1. Abre Cloud Shell.

2. Busca la ubicación de tu bucket de _Trace:

   gcloud beta observability buckets list --location=-

   Toma nota de la ubicación de tu bucket de _Trace para el siguiente paso.

3. Crea un conjunto de datos vinculado en tu proyecto de BigQuery que apunte a tu bucket 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

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID del proyecto.
   • LOCATION: Es la ubicación de tu bucket de _Trace del paso anterior.
   • LINK_NAME: Es un nombre para el conjunto de datos vinculado.

4. Crea un conjunto de datos estándar en el que almacenarás tus seguimientos históricos. Con el siguiente comando, se establece el vencimiento predeterminado de la partición 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

   Reemplaza STORAGE_DATASET por un nombre para el conjunto de datos.

5. Crea una tabla particionada 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 administrar la retención de datos y los costos 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;

   Reemplaza TABLE_NAME por un nombre para la tabla.

6. Crea una consulta programada para copiar los datos de seguimiento diarios del conjunto de datos vinculado a 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 seguimientos.

Desactiva la observabilidad

Para desactivar la observabilidad de tus agentes de datos, actualiza el parámetro de configuración 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

Reemplaza lo siguiente:

• SETTING_NAME: Es el nombre de la configuración de observabilidad que creaste para habilitar la observabilidad. Si habilitaste la observabilidad con la consola de Google Cloud , el nombre de la configuración es default.
• PROJECT_ID: ID del proyecto

Analiza los registros de conversaciones en BigQuery

Además de las métricas de observabilidad a nivel del proyecto en Cloud Monitoring y los intervalos en Cloud Trace, puedes habilitar el registro de conversaciones por agente en BigQuery Studio para escribir cada turno de conversación, incluida la pregunta del usuario, la respuesta del agente, la latencia y el uso de tokens del modelo, en una tabla de BigQuery en el proyecto de tu agente. Luego, puedes consultar y evaluar los eventos registrados con GoogleSQL, notebooks de Colab interactivos o el SDK de Python de análisis de agentes de BigQuery. Para obtener más información, consulta Descripción general del registro de conversaciones.

¿Qué sigue?

• Obtén más información sobre las estadísticas conversacionales en BigQuery.
• Obtén más información sobre la API de Conversational Analytics.
• Analiza datos con conversaciones.
• Obtén más información sobre cómo el rol de Visualizador de agentes de análisis de datos de Gemini (roles/geminidataanalytics.dataAgentViewer) otorga permiso para ver el agente de datos.