Crea agentes de datos y chatea con tus datos

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 o extremos regionales, para compilar una interfaz de chat potenciada por inteligencia artificial (IA) o un agente de datos. La API usa lenguaje natural para responder preguntas sobre datos estructurados en BigQuery, Looker, Data Studio y fuentes de datos de bases de datos (AlloyDB, GoogleSQL para Spanner, Cloud SQL para MySQL y Cloud SQL para PostgreSQL en versión preliminar en v1beta). Además del chat de varios turnos, puedes usar el método QueryData para ejecutar consultas de un solo turno.

Con la API de Conversational Analytics, proporcionas 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.

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.

Comienza a usar la API de Conversational Analytics

Para comenzar a usar la API de Conversational Analytics, revisa la siguiente documentación para comprender los enfoques de integración disponibles y los conceptos básicos:

• Arquitectura y conceptos clave: Comprende cómo los agentes de datos 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) necesarios.
• Patrones de integración para agentes de datos: Compara los enfoques de arquitectura para determinar el mejor método de conexión para tu aplicación.
• Administración de estados: Obtén información sobre los modos de conversación con y sin estado, cómo la API administra el historial de conversaciones y los permisos de estado de la sesión del ADK.
• Seguridad, privacidad, riesgo y cumplimiento: Comprende las opciones de seguridad y cumplimiento de la API de Conversational Analytics.
• Ubicaciones de la API de Conversational Analytics: Proporciona una descripción general de los extremos de la API regionales o multirregionales que te permiten controlar la ubicación geográfica de los recursos, la configuración y los datos de tu agente.

Para comenzar a crear agentes de datos, completa los pasos que se indican en la documentación de configuración y requisitos previos. Para obtener guías paso a paso, aplicaciones de ejemplo, SDKs y otras herramientas para desarrolladores, consulta Instructivos, demostraciones y herramientas 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.
• Control de acceso con IAM: Se describe cómo usar Identity and Access Management para compartir y administrar el acceso a los agentes de datos.
• Autentica y conéctate a una fuente de datos: Proporciona instrucciones para autenticarte en la API y configurar conexiones a tus fuentes de datos de BigQuery, Lakehouse, Looker, Data Studio y bases de datos (AlloyDB, GoogleSQL para Spanner, Cloud SQL para MySQL y Cloud SQL para PostgreSQL).
• Conéctate a BigQuery: Describe los roles necesarios y cómo conectar un agente de datos a tablas y grafos de BigQuery.
• Conéctate a Looker: Describe cómo conectar un agente de datos a las exploraciones de Looker y autenticarte en tu instancia de Looker.
• Claves de encriptación administradas por el cliente (CMEK): Describe cómo usar tus propias claves de encriptación en Cloud Key Management Service para proteger los agentes de datos y las conversaciones.
• Restricciones de las políticas de la organización: Describe cómo usar las restricciones predefinidas de las políticas de la organización para controlar los recursos a nivel de la organización, la carpeta o el proyecto.

Compila un agente de datos y, luego, interactúa con él

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, luego, interactuar con él a través de 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 con el SDK de Python.
• Organiza agentes de datos con A2A: Aprende a descubrir las capacidades de los agentes, delegar consultas analíticas y transmitir consultas en SQL y visualizaciones de gráficos en sistemas multiagente.
• Guía el comportamiento del agente con contexto creado: Obtén información para proporcionar contexto creado que guíe el comportamiento del agente y mejore la exactitud de las respuestas. También puedes ver ejemplos de contexto creado con fuentes de datos de BigQuery y con fuentes de datos de Looker.

• Renderiza una respuesta del agente de la API de Conversational Analytics como una visualización: Proporciona un ejemplo de 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.

  Nota: No se admite la renderización de visualizaciones para fuentes de datos de bases de datos (AlloyDB, GoogleSQL para Spanner, Cloud SQL para MySQL y Cloud SQL para PostgreSQL).

Prácticas recomendadas

Revisa las siguientes guías para conocer las prácticas recomendadas para usar la API de Conversational Analytics:

• Administra los costos de BigQuery para tus agentes: Obtén información para supervisar y administrar los costos de BigQuery de tus agentes de la API de Conversational Analytics estableciendo límites de inversión a nivel de proyecto, usuario y consulta.
• Haz preguntas eficaces: Aprende a crear preguntas eficaces para que tus agentes aprovechen al máximo la API de Conversational Analytics.
• Retención y eliminación de datos: Obtén información sobre la retención y eliminación de datos para los agentes de datos y las conversaciones de la API de Conversational Analytics.
• Cuotas y límites: Obtén información sobre las cuotas y los límites de la API de Conversational Analytics.
• Solucionar problemas de la API de Conversational Analytics: Solucionar problemas comunes de la API de Conversational Analytics.
• Limitaciones conocidas: Proporciona información detallada sobre las limitaciones conocidas de la API de Conversational Analytics, incluidas las limitaciones de consultas, datos, visualizaciones y preguntas.
• Renderiza las respuestas del agente para las fuentes de datos de Looker: Conoce las prácticas recomendadas para renderizar las respuestas de la API de Conversational Analytics en una interfaz de usuario cuando usas fuentes de datos de Looker.

Bibliotecas cliente y referencia de la API

• Referencia de REST de Gemini Data Analytics: Proporciona descripciones detalladas de las versiones, los métodos, los extremos y las definiciones de tipos de la API.
• SDK y herramientas para desarrolladores: Enumera las bibliotecas cliente específicas de cada lenguaje.

Operaciones clave de la API

La API proporciona los siguientes extremos principales para administrar agentes de datos y conversaciones. Los extremos v1 de la siguiente tabla admiten las fuentes de datos de BigQuery, Looker y Data Studio. Debido a que las fuentes de datos de la base de datos están en versión preliminar en v1beta, especifica las rutas de acceso /v1beta/ correspondientes para las fuentes de la base de datos.

Cuando construyas estas rutas (o sus nombres de recursos del SDK correspondientes), reemplaza los comodines (*) por el ID del proyecto, el identificador de ubicación (como global o us) y el ID del recurso (como el ID del agente o el ID de la conversación), según corresponda.

Importante: La ubicación en la ruta de acceso de la solicitud debe coincidir con la ubicación del extremo al que llamas. Por ejemplo, si llamas al extremo geminidataanalytics.us.rep.googleapis.com, especifica us en la ruta de acceso de la solicitud (como /locations/us). Para obtener detalles sobre la residencia de datos y la configuración de extremos, consulta Residencia de datos.

Operación	Método HTTP	Extremo	Descripción
Crea un agente	POST	/v1/projects/*/locations/*/dataAgents	Crea un agente de datos nuevo.
Crea un agente de forma síncrona	POST	/v1/projects/*/locations/*/dataAgents:createSync	Crea un nuevo agente de datos de forma síncrona.
Obtén un agente	GET	/v1/projects/*/locations/*/dataAgents/*	Recupera los detalles de un agente de datos específico.
Obtén la política de Identity and Access Management	POST	/v1/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 un rol de propietario de agentes de datos pueden llamar a este extremo para ver la política de Identity and Access Management del agente de datos antes de usar el extremo setIAMpolicy para compartir un agente de datos con otros usuarios.
Establece la política de Identity and Access Management	POST	/v1/projects/*/locations/*/dataAgents/*:setIamPolicy	Establece la política de Identity and Access Management para un agente de datos específico. Los usuarios con un rol de propietario de agentes de datos deben llamar a este extremo para compartir un agente de datos con otros usuarios, lo que actualiza de forma eficaz los permisos de Identity and Access Management de esos usuarios.
Actualiza un agente	PATCH	/v1/projects/*/locations/*/dataAgents/*	Modifica un agente de datos existente.
Actualiza un agente de forma síncrona	PATCH	/v1/projects/*/locations/*/dataAgents/*:updateSync	Modifica un agente de datos existente de forma síncrona.
Mostrar lista de agentes	GET	/v1/projects/*/locations/*/dataAgents	Enumera los agentes de datos disponibles en un proyecto.
Enumera los agentes accesibles	GET	/v1/projects/*/locations/*/dataAgents:listaccessible	Enumera los agentes de datos accesibles en 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 administrar qué agentes devuelve este método: NONE (predeterminado): Devuelve todos los agentes de datos a los que puede acceder el usuario, independientemente de quién los haya creado. CREATOR_ONLY: Muestra solo los agentes de datos a los que puede acceder el usuario y que creó ese usuario. NOT_CREATOR_ONLY: Devuelve solo los agentes de datos a los que el usuario puede acceder y que crearon otros usuarios.
Borra un agente	DELETE	/v1/projects/*/locations/*/dataAgents/*	Quita un agente de datos.
Borra un agente de forma síncrona	DELETE	/v1/projects/*/locations/*/dataAgents/*:deleteSync	Quita un agente de datos de forma síncrona.
Cómo crear una conversación	POST	/v1/projects/*/locations/*/conversations	Inicia una conversación nueva y persistente.
Chatea con una referencia de conversación	POST	/v1/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 de 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	/v1/projects/*/locations/*:chat	Envía un mensaje de chat sin estado que hace referencia a un agente de datos guardado para obtener 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 el contexto intercalado	POST	/v1/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	/v1/projects/*/locations/*/conversations/*	Recupera los detalles de una conversación específica.
Mostrar lista de conversaciones	GET	/v1/projects/*/locations/*/conversations	Enumera las conversaciones de un proyecto específico.
Enumera los mensajes de una conversación	GET	/v1/projects/*/locations/*/conversations/*/messages	Enumera los mensajes de una conversación específica.
Borrar una conversación	DELETE	/v1/projects/*/locations/*/conversations/*	Borra una conversación específica. Se requiere el rol de Identity and Access Management de Administrador de temas o, al menos, el permiso de Identity and Access Management de cloudaicompanion.topics.delete para llamar a este extremo.
Consulta los datos	POST	/v1beta/projects/*/locations/*/conversations:queryData	Consulta datos de las bases de datos de AlloyDB, GoogleSQL para Spanner, Cloud SQL para MySQL y Cloud SQL para PostgreSQL con lenguaje natural.
Obtener tarjeta de agente (A2A)	GET	/v1/a2a/projects/*/locations/*/agents/*/v1/card	Recupera las capacidades, las habilidades y las extensiones compatibles de un agente de datos integrado o personalizado con el protocolo A2A.
Enviar mensaje (A2A)	POST	/v1/a2a/projects/*/locations/*/agents/*/v1/message:send	Envía un mensaje a un agente de datos con el protocolo A2A.
Envía un mensaje de transmisión (A2A)	POST	/v1/a2a/projects/*/locations/*/agents/*/v1/message:stream	Envía un mensaje de transmisión a un agente de datos con el protocolo A2A, que devuelve el progreso del razonamiento en tiempo real y artefactos estructurados (como consultas en SQL y visualizaciones de gráficos).

Asistencia y comentarios

Para obtener ayuda o informar un problema, comunícate con el equipo de Atención al cliente. Sigue las instrucciones que se indican en Crea y administra casos de asistencia para abrir tu caso de asistencia. Sigue estos lineamientos cuando crees tu caso:

• Para obtener asistencia para la API de Conversational Analytics con BigQuery, en la lista Selecciona un producto, elige BigQuery y, en el campo Función, selecciona IA y aprendizaje automático::API de Conversational Analytics en BigQuery.
• Para obtener asistencia para la API de Conversational Analytics con Looker, en la lista Selecciona un producto, selecciona Looker (original) y, en el campo Función, selecciona Gemini en Looker::API de Conversational Analytics.

Nota: La asistencia para la API de Conversational Analytics abarca problemas técnicos relacionados con el uso del servicio de la API. La depuración de código general y personalizado está fuera del alcance. Los clientes son responsables de depurar su propio código personalizado.

Si tienes comentarios o preguntas generales sobre la API de Conversational Analytics, envía un correo electrónico a [e-mail]. No garantizamos una respuesta a las comunicaciones por correo electrónico, pero sí leemos los correos electrónicos y consultamos estos comentarios durante la planificación de la hoja de ruta.

También puedes enviar una solicitud de función para obtener una nueva funcionalidad de la API de Conversational Analytics.