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

Este producto o función está sujeto 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. Los productos y las funciones previos 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.

Importante: La API Data QnA está obsoleta. Si vas a migrar desde la API Data QnA, consulta la guía de migración para ver un resumen de las principales diferencias y los pasos de migración necesarios.

Los desarrolladores pueden usar la API Conversational Analytics, a la que se accede a través de geminidataanalytics.googleapis.com, para crear una interfaz de chat basada en inteligencia artificial (IA) o un agente de datos que use el lenguaje natural para responder a preguntas sobre datos estructurados en BigQuery, Looker y Looker Studio. Con la API Conversational Analytics, puedes proporcionar a tu agente de datos información y datos empresariales (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.

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

Dado que la tecnología de Gemini está en una fase inicial, puede que genere resultados que sean incorrectos aunque parezcan plausibles. Google CloudTe recomendamos que valides todos los resultados de Gemini para los productos Google Cloud antes de usarlos. Para obtener más información, consulta el artículo sobre Gemini para Google Cloud y la IA responsable.

Nota: Las ofertas de Acceso Previo a la Disponibilidad General (1) están pensadas para usarse únicamente en entornos de prueba y no deben utilizarse en un entorno de producción ni para tratar datos personales u otros datos sujetos a requisitos de cumplimiento legal o normativo, y (2) están sujetas a los Términos de las Ofertas de Acceso Previo a la Disponibilidad General de los Términos Específicos de los Servicios y al Anexo de Consentimiento del Programa de Google Cloud Probadores de Confianza de Gemini.

Empezar a usar la API Conversational Analytics

Para empezar a usar la API Conversational Analytics, primero puedes consultar la documentación sobre la arquitectura y los conceptos clave para saber cómo procesan las solicitudes los agentes, los flujos de trabajo para los creadores y usuarios de agentes, los modos de conversación y los roles de gestión de identidades y accesos (IAM). Después, para empezar a crear agentes de datos, puedes elegir entre una experiencia guiada con guías de inicio rápido, codelabs y cuadernos, o un enfoque autónomo siguiendo los pasos de Configuración y requisitos previos.

Guías de inicio rápido, codelabs y cuadernos

Los siguientes recursos ofrecen experiencias guiadas para ayudarte a empezar a usar la API Conversational Analytics:

• Aplicación de inicio rápido: usa esta aplicación de inicio rápido de Streamlit para integrar la API Conversational Analytics en un entorno de prueba local.
• Codelab de la API Conversational Analytics: sigue un tutorial paso a paso para aprender a usar el SDK de Python con datos de BigQuery.
• Notebooks de Colaboratory de la API Conversational Analytics:
  • Notebook de Colaboratory HTTP: ofrece una guía interactiva paso a paso para configurar tu entorno, crear un agente de datos y hacer llamadas a la API mediante solicitudes HTTP.
  • Notebook de Colaboratory del SDK de Python: ofrece una guía interactiva paso a paso para configurar tu entorno, crear un agente de datos y hacer llamadas a la API mediante el SDK de Python.

Configuración y requisitos previos

Antes de usar la API o los ejemplos, sigue estos pasos:

• Habilitar la API Conversational Analytics: se describen los requisitos previos para habilitar la API Conversational Analytics.
• Control de acceso a la API Conversational Analytics con IAM: describe cómo usar Gestión de Identidades y Accesos para compartir y gestionar el acceso a agentes de datos.
• Autenticar y conectar con una fuente de datos mediante la API Conversational Analytics: se proporcionan instrucciones para autenticar la API y configurar conexiones con los datos de BigQuery, Looker y Looker Studio.

Crear e interactuar con un agente de datos

Después de completar los pasos anteriores, use la API Conversational Analytics para crear un agente de datos e interactuar con él siguiendo estos pasos:

• Crear un agente de datos mediante HTTP: proporciona un ejemplo completo de cómo crear e interactuar con un agente de datos mediante solicitudes HTTP directas con Python.
• Crear un agente de datos con el SDK de Python: proporciona un ejemplo completo de cómo crear un agente de datos e interactuar con él mediante el SDK de Python.
• Dirigir el comportamiento de los agentes con contexto creado: consulta cómo proporcionar contexto creado para dirigir el comportamiento de los agentes y mejorar la precisión de las respuestas. También puedes ver ejemplos de contexto creado con fuentes de datos de BigQuery y con fuentes de datos de Looker.
• Representar como visualización la respuesta de un agente de la API Conversational Analytics: proporciona un ejemplo de cómo procesar especificaciones de gráficos a partir de respuestas de la API y representarlas como visualizaciones mediante el SDK de Python y la biblioteca Vega-Altair.

Prácticas recomendadas

Consulta las siguientes guías para obtener información sobre las prácticas recomendadas para usar la API Conversational Analytics:

• Gestionar los costes de BigQuery de tus agentes: consulta cómo monitorizar y gestionar los costes de BigQuery de tus agentes de la API Conversational Analytics definiendo límites de gasto a nivel de proyecto, de usuario y de consulta.
• Hacer preguntas eficaces: descubre cómo formular preguntas eficaces para que tus agentes saquen el máximo partido a la API Conversational Analytics.
• Solucionar problemas de la API Conversational Analytics: soluciona problemas habituales de la API Conversational Analytics.
• Limitaciones conocidas: proporciona información detallada sobre las limitaciones conocidas de la API Conversational Analytics, incluidas las limitaciones de las consultas, los datos, las visualizaciones y las preguntas.

Operaciones de API clave

La API proporciona los siguientes endpoints principales para gestionar agentes de datos y conversaciones:

Operación	Método HTTP	Endpoint	Descripción
Crear un agente	POST	/v1beta/projects/*/locations/*/dataAgents	Crea un agente de datos.
Obtener un agente	GET	/v1beta/projects/*/locations/*/dataAgents/*	Obtiene los detalles de un agente de datos específico.
Obtener política de gestión de identidades y accesos	POST	/v1beta/projects/*/locations/*/dataAgents/*:getIamPolicy	Obtiene los permisos de gestión de identidades y accesos asignados a cada usuario para un agente de datos específico. Los usuarios con el rol de propietario de agente de datos pueden llamar a este endpoint para ver la política de gestión de identidades y accesos del agente de datos antes de usar el endpoint setIAMpolicy para compartir un agente de datos con otros usuarios.
Definir la política de gestión de identidades y accesos	POST	/v1beta/projects/*/locations/*/dataAgents/*:setIamPolicy	Define la política de Gestión de Identidades y Accesos de un agente de datos específico. Los usuarios con el rol de propietario de agente de datos deben llamar a este endpoint para compartir un agente de datos con otros usuarios, lo que actualiza de forma eficaz los permisos de gestión de identidades y accesos de esos usuarios.
Actualizar un agente	PATCH	/v1beta/projects/*/locations/*/dataAgents/*	Modifica un agente de datos.
Mostrar agentes	GET	/v1beta/projects/*/locations/*/dataAgents	Muestra los agentes de datos disponibles en un proyecto.
Mostrar agentes accesibles	GET	/v1beta/projects/*/locations/*/dataAgents:listaccessible	Muestra los agentes de datos accesibles de un proyecto. Se considera que un agente de datos es accesible si el usuario que invoca esta API tiene el permiso get en el agente. Puedes usar el campo creator_filter para gestionar qué agentes devuelve este método: NONE (valor predeterminado): devuelve todos los agentes de datos a los que puede acceder el usuario, independientemente de quién los haya creado. CREATOR_ONLY: devuelve solo los agentes de datos a los que puede acceder el usuario y que ha creado ese usuario. NOT_CREATOR_ONLY: devuelve solo los agentes de datos a los que puede acceder el usuario y que han creado otros usuarios.
Eliminar un agente	DELETE	/v1beta/projects/*/locations/*/dataAgents/*	Elimina un agente de datos.
Crear una conversación	POST	/v1beta/projects/*/locations/*/conversations	Inicia una conversación nueva y persistente.
Chatear usando 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 y al contexto del agente asociado. En las conversaciones de varios turnos, Google Cloud almacena y gestiona el historial de la conversación.
Chatear usando 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 obtener contexto. En las conversaciones de varios turnos, tu aplicación debe gestionar y proporcionar el historial de la conversación con cada solicitud.
Chatear usando el contexto insertado	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 guardados. En las conversaciones de varios turnos, tu aplicación debe gestionar y proporcionar el historial de la conversación con cada solicitud.
Obtener una conversación	GET	/v1beta/projects/*/locations/*/conversations/*	Obtiene los detalles de una conversación específica.
Mostrar conversaciones	GET	/v1beta/projects/*/locations/*/conversations	Muestra las conversaciones de un proyecto específico.
Listar los mensajes de una conversación	GET	/v1beta/projects/*/locations/*/conversations/*/messages	Lista los mensajes de una conversación específica.

Enviar comentarios

Usa los siguientes enlaces para informar de un error o solicitar una función.

• Enviar un informe de errores
• Enviar una solicitud de función

Recursos adicionales

Los siguientes recursos proporcionan documentación de referencia, ejemplos y herramientas para ayudarte a crear aplicaciones con la API Conversational Analytics:

• Referencia de la API REST de Conversational Analytics: proporciona descripciones detalladas de los métodos, los endpoints y las definiciones de tipo de las estructuras de solicitud y respuesta.
• Demos y herramientas de analíticas conversacionales: consulta demos y herramientas que muestran las funciones de la API y proporcionan patrones de integración prácticos.
• Agent Development Kit (ADK): consulta cómo usar la función ask_data_insights del ADK para responder a preguntas sobre tus datos en lenguaje natural.