API de Conversational Analytics: Crea agentes de datos y chatea con tus datos

Este producto o función se encuentra sujeto a las "Condiciones de la Oferta de la Fase Previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles "sin modificaciones" y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Importante: La API de Data QnA dejó de estar disponible. Si migras desde la API de Data QnA, consulta la guía de migración para obtener una descripción general de las diferencias clave y los pasos de migración necesarios.

Los desarrolladores pueden usar la API de Conversational Analytics, a la que se accede a través de geminidataanalytics.googleapis.com, para compilar una interfaz de chat o un agente de datos potenciados por inteligencia artificial (IA) que responda preguntas sobre datos estructurados en BigQuery, Looker y Looker Studio con lenguaje natural. Con la API de Conversational Analytics, le proporcionas a tu agente de datos información y datos comerciales ("contexto"), así como acceso a herramientas como SQL, Python y bibliotecas de visualización. Estas respuestas del agente se presentan al usuario y la aplicación cliente puede registrarlas, lo que crea una experiencia de chat de datos fluida y auditable.

Descubre cómo y cuándo Gemini para Google Cloud usa tus datos.

Como tecnología en etapa inicial, los productos de Gemini para Google Cloud pueden generar resultados que parecen posibles, pero que no son correctos. Te recomendamos que valides todos los resultados de Gemini para los productos de Google Cloud antes de usarlos. Para obtener más información, consulta Gemini para Google Cloud y la IA responsable.

Nota: Las ofertas de Versión Preliminar de Fase Previa a la DG (1) están diseñadas para usarse solo en entornos de prueba y no deben utilizarse en un entorno de producción ni para procesar datos personales o cualquier otro dato sujeto a requisitos de cumplimiento legal o reglamentario, y (2) están sujetas a las Condiciones de las Ofertas de Fase Previa a la DG de las Condiciones Específicas del Servicio y al Anexo de Consentimiento para el Programa de Verificadores de confianza de Gemini para Google Cloud .

Comienza a usar la API de Conversational Analytics

Para comenzar a usar la API de Conversational Analytics, primero puedes revisar la documentación sobre la arquitectura y los conceptos clave para comprender cómo los agentes procesan las solicitudes, los flujos de trabajo para los creadores y usuarios de agentes, los modos de conversación y los roles de Identity and Access Management (IAM). Luego, para comenzar a crear agentes de datos, puedes elegir entre una experiencia guiada con los notebooks de Colaboratory o un enfoque autodidacta siguiendo los pasos que se indican en Configuración y requisitos previos.

Notebooks interactivos de Colaboratory

Si quieres obtener una guía interactiva paso a paso para configurar tu entorno, compilar un agente de datos y realizar llamadas a la API, consulta los siguientes notebooks de Colaboratory:

• Notebook de Colaboratory de la API de Conversational Analytics a través de HTTP
• Notebook de Colaboratory del SDK de la API de Conversational Analytics

Configuración y requisitos previos

Antes de usar la API o los ejemplos, completa los siguientes pasos:

• Habilita la API de Conversational Analytics: Describe los requisitos previos para habilitar la API de Conversational Analytics.
• Otorga roles y permisos de IAM de la API de Conversational Analytics: Describe los roles de IAM predefinidos para administrar el acceso a los agentes de datos.
• Autentica y conéctate a una fuente de datos con la API de Conversational Analytics: Proporciona instrucciones para autenticarte en la API y configurar conexiones a tus datos de BigQuery, Looker y Looker Studio.

Crea un agente de datos y usa sus funciones

Después de completar los pasos anteriores, usa la API de Conversational Analytics para compilar un agente de datos y, luego, interactuar con él. Para ello, sigue estos pasos:

• Crea un agente de datos con HTTP: Proporciona un ejemplo completo de cómo crear un agente de datos y cómo interactuar con él usando solicitudes HTTP directas con Python.
• Compila un agente de datos con el SDK de Python: Proporciona un ejemplo completo de cómo compilar un agente de datos y cómo interactuar con él usando el SDK de Python.
• Cómo escribir instrucciones del sistema eficaces: Aprende a estructurar el contenido YAML para el parámetro system_instruction y guiar el comportamiento del agente, así como mejorar la precisión de las respuestas. También puedes ver ejemplos de instrucciones del sistema en Fuentes de datos de BigQuery y en Fuentes de datos de Looker.
• Renderiza una respuesta del agente de la API de Conversational Analytics como una visualización: Proporciona un ejemplo del procesamiento de especificaciones de gráficos a partir de respuestas de la API y su renderización como visualizaciones con el SDK de Python y la biblioteca de Vega-Altair.

Prácticas recomendadas

• Administra los costos de BigQuery para tus agentes: Obtén información para supervisar y administrar los costos de BigQuery para tus agentes de la API de Conversational Analytics estableciendo límites de inversión a nivel del proyecto, del usuario y de la consulta.

Operaciones clave de la API

La API proporciona los siguientes extremos principales para administrar agentes de datos y conversaciones:

Operación	Método HTTP	Extremo	Descripción
Crea un agente	POST	/v1beta/projects/*/locations/*/dataAgents	Crea un agente de datos nuevo.
Obtén un agente	GET	/v1beta/projects/*/locations/*/dataAgents/*	Recupera los detalles de un agente de datos específico.
Obtén la política de Identity and Access Management	POST	/v1beta/projects/*/locations/*/dataAgents/*:getIamPolicy	Obtiene los permisos de Identity and Access Management que se asignan a cada usuario para un agente de datos específico. Los usuarios con el rol de propietario del agente de datos pueden llamar a este endpoint para ver la política de Identity and Access Management del agente de datos antes de usar el endpoint setIAMpolicy para compartir un agente de datos con otros usuarios.
Establece la política de Identity and Access Management	POST	/v1beta/projects/*/locations/*/dataAgents/*:setIamPolicy	Establece la política de Identity and Access Management para un agente de datos específico. Los usuarios con el rol de propietario del agente de datos deben llamar a este endpoint para compartir un agente de datos con otros usuarios, lo que actualiza de manera efectiva los permisos de Identity and Access Management de esos usuarios.
Actualiza un agente	PATCH	/v1beta/projects/*/locations/*/dataAgents/*	Modifica un agente de datos existente.
Mostrar lista de agentes	GET	/v1beta/projects/*/locations/*/dataAgents	Enumera los agentes de datos disponibles en un proyecto.
Borra un agente	DELETE	/v1beta/projects/*/locations/*/dataAgents/*	Quita un agente de datos.
Cómo crear una conversación	POST	/v1beta/projects/*/locations/*/conversations	Inicia una conversación nueva y persistente.
Chatea con una referencia de conversación	POST	/v1beta/projects/*/locations/*:chat	Continúa una conversación con estado enviando un mensaje de chat que hace referencia a una conversación existente y a su contexto del agente asociado. En el caso de las conversaciones de varios turnos, Google Cloud almacena y administra el historial de conversaciones.
Chatea con una referencia de agente de datos	POST	/v1beta/projects/*/locations/*:chat	Envía un mensaje de chat sin estado que hace referencia a un agente de datos guardado para el contexto. En el caso de las conversaciones de varios turnos, tu aplicación debe administrar y proporcionar el historial de conversaciones con cada solicitud.
Chatea con contexto intercalado	POST	/v1beta/projects/*/locations/*:chat	Envía un mensaje de chat sin estado proporcionando todo el contexto directamente en la solicitud, sin usar un agente de datos guardado. En el caso de las conversaciones de varios turnos, tu aplicación debe administrar y proporcionar el historial de conversaciones con cada solicitud.
Obtén una conversación	GET	/v1beta/projects/*/locations/*/conversations/*	Recupera los detalles de una conversación específica.
Mostrar lista de conversaciones	GET	/v1beta/projects/*/locations/*/conversations	Enumera las conversaciones en un proyecto específico.
Cómo enumerar los mensajes de una conversación	GET	/v1beta/projects/*/locations/*/conversations/*/messages	Enumera los mensajes de una conversación específica.

Enviar comentarios

Usa los siguientes vínculos para informar un error o solicitar una función.

• Cómo enviar un informe de errores
• Solicitar una función

Enviar comentarios

Usa los siguientes vínculos para informar un error o solicitar una función.

• Cómo enviar un informe de errores
• Solicitar una función

Recursos adicionales

• Documentación de referencia de la API de Conversational Analytics: Proporciona descripciones detalladas de los métodos, los extremos y las definiciones de tipos para las estructuras de solicitud y respuesta.
• Soluciona problemas de errores de la API de Conversation Analytics: Soluciona problemas comunes de la API de Conversation Analytics.