Patrones de integración para agentes de datos

En esta página, se describen los patrones de integración para incorporar experiencias de agentes de datos en tus aplicaciones. La complejidad de estos patrones varía desde un componente de chat incorporado hasta un sistema multiagente coordinado.

Esta guía está dirigida a arquitectos de la nube y a ingenieros de datos que diseñan aplicaciones de IA generativa. Debes tener un conocimiento básico de los conceptos de Google Cloud , Identity and Access Management (IAM) y las APIs de REST. También debes conocer la arquitectura de la fuente de datos que usa tu aplicación.

Descripción general de los patrones de integración

Esta guía se organiza en las siguientes pistas principales, cada una de las cuales se basa en tu punto de partida:

  • Ruta de Looker: Selecciona esta ruta si quieres proporcionar la funcionalidad de chat a través de la incorporación de Looker, la API de Looker o la API de Conversational Analytics.
  • Seguimiento de BigQuery y bases de datos: Selecciona este seguimiento si estás creando una aplicación personalizada que use BigQuery, Data Studio o una base de datos operativa compatible.

En la siguiente tabla, se resumen los patrones de integración disponibles:

Patrón de integración Descripción Fuente de datos
Incorporación de iframe de Looker Agrega la interfaz de chat estándar a una aplicación que requiere un código mínimo. Looker
API y SDK de Looker Crea una interfaz de chat personalizada que use la API de Looker para la autenticación. Looker
API de Conversational Analytics (fuente de Looker) Administra los agentes de datos de Looker como recursos de Google Cloud que funcionan en múltiples plataformas y sistemas multiagente. Looker
API directa (un solo agente) Usa una integración directa de la API para los flujos de texto a respuesta. BigQuery, bases de datos y Looker
API directa (orquestador) Enruta las consultas entre la API y otras herramientas con la llamada a funciones. BigQuery, bases de datos y Looker
ADK (basado en esquemas) con BigQueryToolset Genera estadísticas rápidas a partir de referencias a tablas con la herramienta ask_data_insights. BigQuery
ADK (administrado) con DataAgentToolset Consulta agentes de datos preconfigurados que usan la herramienta ask_data_agent para garantizar un comportamiento coherente. BigQuery, bases de datos y Looker
ADK (transmisión personalizada) Admite la transmisión en tiempo real de gráficos y SQL con una clase de agente personalizada. BigQuery, bases de datos y Looker
MCP con McpToolset o ToolboxToolset Conecta aplicaciones a herramientas de datos que usan el Protocolo de contexto del modelo (MCP). BigQuery y Looker
Servidor de MCP remoto de la API de Conversational Analytics Proporciona una puerta de enlace unificada y segura que permite que los agentes raíz en plataformas de IA de terceros y plataformas administradas por Google (como Gemini Enterprise) descubran agentes de datos especializados y se comuniquen con ellos en Google Cloud. BigQuery, bases de datos y Looker
Protocolo A2A Permite la colaboración segura entre agentes especializados que operan en diferentes sistemas. Dependiente del framework

Opciones de integración para Looker

Si usas Looker, puedes proporcionar Conversational Analytics de Looker a tus usuarios a través de los siguientes patrones:

Resumen de los patrones de integración de Looker

En la siguiente tabla, se resumen los patrones de integración principales para Looker:

Patrón Ideal para Ventajas Consideraciones
Incorporación con iframes: Es un método de poco código para agregar rápidamente la experiencia de chat estándar de Looker a una aplicación. Equipos que requieren una experiencia de Conversational Analytics lista para producción con un desarrollo personalizado mínimo
  • Requiere un código mínimo para implementarse.
  • Aplica de manera forzosa automáticamente el modelo de seguridad existente de Looker.
  • No requiere autenticación Google Cloud independiente.
  • Admite el SDK de incorporación de Looker, que acelera el desarrollo administrando los ciclos de vida de los iframes y el paso de eventos.
  • Ofrece una personalización limitada de la IU y depende de la interfaz de usuario de chat estándar de Looker.
  • Tu instancia de Looker debe estar alojada en Looker.
Compila con la API y los SDK de Looker: Es un enfoque flexible para compilar una interfaz de chat personalizada, a la vez que se mantiene la autenticación y la administración de agentes dentro de Looker. Equipos que requieren una experiencia del usuario de chat personalizada, pero que quieren mantener la autenticación de usuarios y la administración de agentes dentro del ecosistema de Looker. Este patrón es ideal para las aplicaciones que ya usan la incorporación de Looker o la API.
  • Proporciona una sola capa de autenticación y control total sobre la interfaz de usuario.
  • Simplifica la arquitectura para los clientes existentes de Looker.
  • Usa la capa semántica de Looker para mejorar la exactitud de las consultas.
  • No requiere autenticación Google Cloud independiente.
  • Requiere experiencia en el desarrollo de la API de Looker.
  • Se limita a las fuentes de datos de Looker.
  • Los agentes se administran en Looker y no se pueden transferir a otros servicios de Google Cloud .
Usa la API de Conversational Analytics: Integración directa con la API para administrar agentes como recursos a nivel de la nube. Clientes de Looker que requieren portabilidad multiplataforma para sus agentes de datos
  • Garantiza que el agente de datos sea portátil en todas las plataformas de Google Cloud .
  • Se rige de forma centralizada por IAM.
  • Te permite integrar agentes de datos en flujos de trabajo de ADK o MCP.
  • Requiere que administres toda la pila de integración, incluida la autenticación de Google Cloud y Looker.
  • Los agentes de datos se administran de forma independiente de la interfaz de usuario de Looker.

Incorpora con iframes

Puedes incorporar Conversational Analytics como un iframe para ofrecer la experiencia de chat fuera de la IU de Looker. Este patrón es una forma directa de proporcionar Conversational Analytics que no requiere desarrollo de IU personalizado, organización de backend ni administración de estado de la API. Para usar este patrón, agrega una URL con formato previo a tu aplicación.

El SDK de incorporación de Looker proporciona herramientas que administran tareas como la generación de URLs seguras, la administración del ciclo de vida de los iframes y el paso de eventos de JavaScript entre la aplicación alojada y el iframe. Puedes incorporar la página Agentes, la página Conversaciones o una conversación específica agregando una URL con formato previo a tu aplicación.

Puedes usar los siguientes métodos de autenticación para el contenido incorporado:

  • Incorporación privada: Autentica a los usuarios con sus credenciales de Looker existentes. Cuando configuras la URL de incorporación como la fuente del iframe, los usuarios acceden con sus cuentas de Looker. Este método aplica de manera forzosa automáticamente los roles, el acceso al contenido y los permisos a nivel de los datos existentes, como los filtros de acceso o los otorgamientos de acceso, sin necesidad de configurar IAM ni asignar tokens adicionales.
  • Incorporación firmada: Autentica a los usuarios a través de tu aplicación con el inicio de sesión único (SSO). Debes crear una URL firmada que incluya la ruta de acceso al contenido de Conversational Analytics, lo que te permite especificar de forma dinámica exactamente qué permisos otorgar.

Compila con la API y los SDK de Looker

Para obtener más flexibilidad en la experiencia de chat, puedes usar los métodos ConversationalAnalytics en la API de Looker o un SDK de Looker para compilar una aplicación personalizada. Este enfoque te permite crear un frontend personalizado que se comunique directamente con los extremos de Looker.

La integración con la API de Looker proporciona los siguientes beneficios:

  • Solo administras la autenticación con Looker. No es necesario autenticarse por separado con la API de Conversational Analytics.
  • En el caso de las aplicaciones que ya usan la incorporación o la API de Looker, este patrón simplifica la arquitectura del proyecto, ya que evita los mecanismos de autenticación secundarios y elimina la necesidad de administrar agentes de datos externos.
  • Tienes el control total de la interfaz de chat, el flujo de conversación y la forma en que la aplicación renderiza los resultados (como gráficos y tablas).

Para ver una implementación de referencia, consulta la guía de la API de Looker que usa métodos ConversationalAnalytics en GitHub.

Usa la API de Conversational Analytics con datos de Looker

Puedes integrarte directamente con la API de Conversational Analytics en geminidataanalytics.googleapis.com si necesitas realizar alguna de las siguientes tareas:

  • Comparte el mismo agente de datos en varias plataformas de Google Cloud , como aplicaciones web personalizadas, Google Chat y Gemini Enterprise.
  • Combina fuentes de datos de Looker con BigQuery o fuentes de bases de datos operativas en un solo sistema multiagente.
  • Administra tu agente de datos como un recurso a nivel de la nube que se rige por IAM en lugar del modelo de permisos de Looker.

Para obtener más información sobre los patrones de arquitectura comunes de la API de Conversational Analytics, consulta Opciones de integración para BigQuery y bases de datos.

Opciones de integración para BigQuery, Data Studio y bases de datos

En esta sección, se describen los patrones de arquitectura para las aplicaciones que usan BigQuery, Data Studio o las bases de datos operativas de Google Cloud compatibles para crear experiencias personalizadas con la API de Conversational Analytics.

Si usas la API de Conversational Analytics con una fuente de datos de Looker, los patrones que se describen en esta sección también se aplican a tu integración.

La API de Conversational Analytics proporciona los siguientes métodos principales para interactuar con los datos:

  • Método chat: Admite BigQuery, Looker, Data Studio y bases de datos operativas.
  • Método queryData: Admite bases de datos operativas, como AlloyDB, GoogleSQL para Spanner, Cloud SQL para MySQL y Cloud SQL para PostgreSQL.

Cuando compilas una aplicación personalizada, puedes usar uno o más de los siguientes patrones de integración:

  • Integración directa de la API: Es un enfoque personalizado que proporciona la mayor flexibilidad, pero requiere que compiles la infraestructura para la autenticación, la administración de conversaciones y el análisis de respuestas.
  • Organización basada en frameworks (ADK): Es un enfoque que usa el Kit de desarrollo de agentes (ADK) para el enrutamiento de varios agentes, la ejecución de herramientas y la administración de estados.
  • Integración vertical (MCP): Es un enfoque que usa el Protocolo de contexto del modelo (MCP) para proporcionar una forma uniforme de conectar aplicaciones de IA a herramientas y fuentes de datos en diferentes entornos.
  • Organización horizontal (A2A): Es un enfoque que usa el protocolo Agent-to-Agent (A2A) para permitir que los agentes especializados en diferentes sistemas colaboren de forma segura sin necesidad de un código de integración personalizado.

Resumen de los patrones de integración de bases de datos y BigQuery

En la siguiente tabla, se resumen los patrones de implementación específicos para BigQuery y las bases de datos operativas:

Patrón Ideal para Ventajas Consideraciones
Integración de un solo agente (API directa): Es un patrón en el que tu aplicación llama a la API directamente para devolver estadísticas de tus fuentes de datos. Aplicaciones, prototipos o microservicios de un solo agente que requieren control directo sobre cada llamada a la API.
  • Proporciona un control detallado sin dependencias del framework.
  • Proporciona la arquitectura más sencilla para los casos de uso de un solo agente.
  • Admite los modos con y sin estado.
  • Requiere que compiles toda la infraestructura para la autenticación, la administración de estados, el análisis de respuestas, el manejo de errores, la transmisión y la implementación.
  • No se escala bien para situaciones de varios agentes.
Organizador personalizado (API directa): Es un patrón que usa un agente raíz y una llamada a función para enrutar las consultas entre la API de Conversational Analytics y otras herramientas o servicios. Son aplicaciones que combinan consultas de datos con otras tareas, como correos electrónicos o documentos, en un solo flujo conversacional.
  • Proporciona el máximo control de organización sin dependencias de framework.
  • Te permite definir exactamente cómo el modelo enruta entre las herramientas.
  • Funciona con cualquier modelo de Gemini.
  • Requiere que administres de forma manual las definiciones de herramientas, los bucles de conversación, el estado de varios turnos, el manejo de errores y la implementación.
  • La sobrecarga de desarrollo puede volverse pesada en comparación con el uso de un framework como el ADK.
Integración basada en esquemas con BigQueryToolset (ADK): Es un patrón que usa referencias de tablas para devolver estadísticas de datos con rapidez. Creación rápida de prototipos, herramientas internas en las que la administración de datos es menos crítica o situaciones en las que las estadísticas de datos son una de varias capacidades de un agente de ADK.
  • Proporciona la ruta de integración más rápida dentro del framework del ADK.
  • No requiere una configuración previa del agente de datos.
  • Trabaja directamente con los nombres de las tablas de la base de datos.
  • Carece de gobernanza semántica y genera SQL solo a partir de la inferencia de esquemas.
  • Opera en un modo sin estado a nivel de API.
  • Proporciona respuestas solo de texto y no admite gráficos.
Integración administrada con DataAgentToolset (ADK): Es un patrón que consulta un agente de datos preconfigurado haciendo referencia al ID del agente. Aplicaciones de producción que requieren acceso coherente a los datos o sistemas multiagente en los que el agente de datos es un componente confiable y reutilizable.
  • Proporciona un control semántico y un comportamiento coherente en todos los consumidores.
  • Mejora la precisión con consultas verificadas y un glosario empresarial.
  • Garantiza que los agentes de datos se puedan reutilizar en las integraciones de ADK, MCP y APIs directas.
  • Requiere que configures previamente los recursos del agente de datos.
  • Opera en un modo sin estado a nivel de API.
  • Devuelve respuestas solo de texto y no admite gráficos.
Agentes secundarios personalizados (ADK): Es un patrón que usa una clase de agente personalizada para conectarse directamente a la API y transmitir fragmentos de datos al usuario. Aplicaciones para el usuario en las que la baja latencia de respuesta es una prioridad o canalizaciones de varios agentes en las que la recuperación de datos alimenta a los agentes downstream.
  • Proporciona comentarios de transmisión en tiempo real.
  • Accede a todos los tipos de respuestas, como gráficos, tablas y SQL.
  • Se puede componer con otros agentes del ADK a través del estado de la sesión.
  • Requiere más esfuerzo de desarrollo para compilar una clase de agente de ADK personalizada.
  • Requiere que administres la conexión de transmisión y el análisis de respuestas directamente.
Protocolo de contexto del modelo (MCP): Es un patrón que usa un estándar abierto para conectar aplicaciones de IA a fuentes de datos y herramientas en diferentes entornos. Organizaciones que requieren interoperabilidad de herramientas en varios clientes de IA y entornos de desarrollo integrado (IDE), o equipos que necesitan que se pueda acceder a las mismas herramientas de datos desde el framework de ADK, los IDE y las aplicaciones personalizadas.
  • Usa un estándar de herramientas universal que funciona con cualquier cliente que cumpla con el MCP.
  • Desvincula la implementación de herramientas de las aplicaciones de consumidores.
  • Ofrece opciones de servidores administrados, como el servidor de MCP de Google Cloud .
  • Requiere una capa de infraestructura adicional para el servidor de la caja de herramientas.
  • Proporciona una integración más flexible que los conjuntos de herramientas del ADK.
  • Depende del ecosistema en evolución de la caja de herramientas de MCP.
  • Funciona en un modo sin estado que requiere que administres el estado de varios turnos de forma externa.
De agente a agente (A2A): Es un patrón que usa el protocolo A2A, un estándar abierto que permite que los agentes especializados en diferentes sistemas colaboren de forma segura sin necesidad de un código de integración personalizado. Entornos empresariales altamente distribuidos en los que un agente de enrutamiento central debe delegar tareas a agentes de datos que operan en diferentes sistemas o redes.
  • Reduce la necesidad de código de integración personalizado entre frameworks dispares.
  • Garantiza una interoperabilidad multiplataforma fluida.
  • Proporciona un descubrimiento de capacidades seguro y estandarizado.
  • Introduce una latencia de red menor en comparación con los agentes secundarios internos.
  • Requiere que establezcas la configuración del servidor de A2A.

Integración directa con la API

La integración directa de la API proporciona un control detallado sobre la lógica y la arquitectura de tu aplicación, pero requiere que compiles la infraestructura de respaldo. Con este enfoque, eres responsable de tareas como la autenticación, la administración de conversaciones, el análisis de respuestas y la implementación.

En esta sección, se abordan los siguientes temas:

Integración de un solo agente

Con una integración de un solo agente, tu backend llama directamente a la API de Conversational Analytics con REST o una biblioteca cliente y pasa la consulta y el contexto del usuario. Este patrón es adecuado para aplicaciones de baja complejidad, como apps web, herramientas de chat internas o microservicios, que usan un flujo directo de texto a respuesta. También puedes usar este enfoque para crear prototipos y realizar pruebas de concepto.

Este patrón admite tanto el chat con estado, en el que Google administra el historial de conversaciones, como el chat sin estado, en el que tu aplicación administra el historial.

Para ver implementaciones de referencia, consulta la guía de inicio rápido de la API de Conversational Analytics o la demostración de oro de la API de Conversational Analytics en GitHub.

Integración de un organizador personalizado

Con este enfoque, creas un agente raíz que actúa como el punto de entrada principal y el coordinador de tu aplicación. El agente raíz usa un modelo de Gemini estándar que está equipado con herramientas a través de la llamada a funciones. Cuando un usuario hace una pregunta relacionada con los datos, el agente raíz emite una llamada a la herramienta a la API de Conversational Analytics, recibe el resultado y, luego, puede continuar con el razonamiento o llamar a otras herramientas downstream.

La llamada a funciones implica las siguientes etapas:

  1. Declaración: Define los esquemas de herramientas como objetos FunctionDeclaration que incluyen definiciones de parámetros.
  2. Invocar: El modelo devuelve un mensaje functionCall estructurado que contiene el nombre y los argumentos de la función.
  3. Ejecución: Tu aplicación realiza la llamada a la API y devuelve el resultado en un mensaje FunctionResponse.
  4. Sintetizar: El modelo de Gemini usa el resultado para generar una respuesta final o determinar la siguiente acción.

Este enfoque es adecuado para aplicaciones en las que los usuarios pueden solicitar estadísticas de datos junto con otras tareas. Por ejemplo, un usuario podría pedirle al agente que "muestre las ventas y, luego, redacte un correo electrónico para el equipo de ventas". El agente raíz puede enrutar la pregunta de datos a la API de Conversational Analytics y usar otras herramientas para tareas que no sean de datos.

Para obtener una implementación de referencia, consulta las páginas orchestrate o multimodal en la demostración de oro de la API de Conversational Analytics en GitHub.

Organización basada en frameworks (ADK)

El Kit de desarrollo de agentes (ADK) es un framework centrado en el código para crear agentes de IA que administra la complejidad del enrutamiento de varios agentes, la ejecución de herramientas y la administración de estados. El framework de ADK es el mismo que impulsa Gemini Enterprise.

Con el ADK, puedes encadenar la API de Conversational Analytics con otras herramientas y agentes para realizar acciones complejas.

En esta sección, se abordan los siguientes temas:

Integración basada en esquemas con BigQueryToolset

El conjunto de herramientas BigQueryToolset del framework del ADK incluye una herramienta ask_data_insights compilada previamente. Para usar esta herramienta, debes pasarle los nombres de las tablas y la pregunta del usuario, que, luego, llama a la API de Conversational Analytics con el contexto intercalado.

Cuando llamas a la herramienta, esta envía una solicitud sin estado que incluye las referencias de la tabla de BigQuery especificadas a la API de Conversational Analytics. La API infiere el esquema de la base de datos, genera y ejecuta la consulta en SQL, y devuelve una respuesta de texto. Luego, el resultado se devuelve al agente del ADK como una respuesta de la herramienta.

Este patrón es una forma eficaz de agregar Conversational Analytics a un agente con rapidez. Sin embargo, debido a que la llamada a la API no tiene estado y carece de administración, la API genera SQL que se basa por completo en el esquema de la tabla sin protecciones semánticas. Este patrón es más rápido de implementar, pero más riesgoso para la lógica empresarial de producción en la que se aplican convenciones de nombres, lógica empresarial o controles de acceso.

Integración controlada con DataAgentToolset

El conjunto de herramientas DataAgentToolset del framework del ADK proporciona una integración prediseñada que hace referencia a un agente de datos preconfigurado por su ID. El agente de ADK pasa la pregunta del usuario a la herramienta ask_data_agent, que llama a la API de Conversational Analytics con el contexto del agente de datos especificado.

Puedes crear un agente de datos de forma programática con la API de Conversational Analytics o a través del Catálogo de agentes en la consola de Google Cloud . Un agente de datos incluye los siguientes componentes:

  • Fuentes de conocimiento: Tablas, vistas o funciones definidas por el usuario (UDF) que el agente puede consultar
  • Contexto estructurado: Descripciones de tablas y columnas que ayudan al agente a comprender los datos subyacentes
  • Instrucciones: Orientación adicional para que el agente interprete y consulte las fuentes de datos
  • Consultas verificadas: Son consultas en SQL previamente validadas que sirven como ejemplos para preguntas comunes.
  • Glosario: Definiciones de términos empresariales que ayudan al agente a comprender el lenguaje específico del dominio

Para obtener una guía detallada sobre cómo crear agentes a través del catálogo de agentes, consulta el codelab de Conversational Analytics en BigQuery.

Como el agente se define como una unidad gobernada, usa la misma lógica, el mismo contexto y las mismas protecciones de confianza, independientemente de la aplicación o el subagente que lo llame.

Integración avanzada de UX con agentes secundarios personalizados

Los conjuntos de herramientas BigQueryToolset y DataAgentToolset no devuelven resultados al usuario hasta que se termina de procesar la solicitud a la API. Debido a que el framework de ADK trata a la API como una herramienta que bloquea las respuestas hasta que se completan, las consultas de mayor duración podrían dejar a los usuarios sin comentarios.

Como alternativa para las aplicaciones en las que la baja latencia de respuesta es una prioridad o en las que la recuperación de datos alimenta a los agentes downstream, puedes compilar una clase de agente de ADK personalizada que se conecte directamente a la API de Conversational Analytics y transmita datos de forma asíncrona en fragmentos al usuario. Este patrón admite los siguientes tipos de respuesta a medida que se producen:

  • Mensajes de pensamiento: El proceso de razonamiento del agente de datos a medida que interpreta la pregunta.
  • Mensajes de progreso: Son actualizaciones de estado durante la recuperación de datos para las fuentes de datos.
  • Generación de consultas: Es la consulta en SQL o Looker generada, que se transmite a medida que se produce.
  • Datos: Son los resultados de los datos en formato JSON.
  • Visualización: Especificaciones del gráfico de Vega-Lite.
  • Resumen: Es la respuesta final basada en texto.

Para obtener una lista completa de los tipos de datos que se devuelven, consulta el tipo SystemMessage en la documentación de referencia de la API.

Este enfoque asíncrono garantiza que los usuarios no tengan que esperar a que finalice por completo un proceso complejo de recuperación de datos. A medida que el agente de datos avanza por el proceso de consulta, comparte continuamente actualizaciones incrementales, como resúmenes de texto, datos sin procesar o configuraciones de gráficos, en un espacio de trabajo compartido temporal. Luego, estos datos se pueden renderizar para el usuario en tiempo real y compartir con agentes secundarios especializados para realizar tareas adicionales.

Para obtener una implementación de referencia que incluya un agente raíz, un agente secundario de datos y un agente de visualización, consulta la demostración de transmisión del ADK en GitHub.

Integración vertical (MCP)

El Protocolo de contexto del modelo (MCP) es un estándar abierto que proporciona una forma uniforme para que las aplicaciones de IA se conecten a herramientas y fuentes de datos externas. El MCP estandariza la interfaz entre los modelos de IA y las herramientas que usan.

En esta sección, se abordan los siguientes temas:

Servidor de MCP remoto de la API de Conversational Analytics

La API de Conversational Analytics proporciona un servidor de MCP remoto en https://geminidataanalytics.googleapis.com/mcp, con la tecnología del servidor de MCP administrado de Google. Esta puerta de enlace proporciona una interfaz unificada y segura de HTTP y eventos enviados por el servidor (SSE) que permite que los agentes raíz en plataformas de IA de terceros y plataformas administradas por Google (como Gemini Enterprise) descubran agentes de datos especializados y se comuniquen con ellos en Google Cloud.

Descripción general de la comunicación del agente raíz

La comunicación entre un agente raíz externo o administrado por Google y la API de Conversational Analytics involucra tres roles distintos:

  1. Los operadores de datos crean y configuran agentes de datos con alcance en las plataformas de Conversational Analytics, escriben descripciones claras de las fuentes de datos a las que puede acceder cada agente y las preguntas que puede responder, y comparten esos agentes con los usuarios empresariales.
  2. Los administradores de la plataforma registran una conexión de MCP personalizada en su plataforma de agentes que apunta al extremo de https://geminidataanalytics.googleapis.com/mcp. Los administradores configuran las credenciales de cliente de OAuth 2.0 (ID de cliente y secreto del cliente) con el extremo de autorización de Google (https://accounts.google.com/o/oauth2/v2/auth), el extremo de token (https://oauth2.googleapis.com/token) y los permisos de autorización necesarios (https://www.googleapis.com/auth/geminidataanalytics y https://www.googleapis.com/auth/bigquery.readonly).
  3. Los usuarios empresariales hacen preguntas en lenguaje natural en la plataforma de agentes. En lugar de consultar directamente las bases de datos sin procesar, el agente raíz (el LLM de organización) de la plataforma se comunica con el servidor de MCP remoto de la API de Conversational Analytics para descubrir agentes de datos pertinentes, enrutar la pregunta del usuario al agente de datos con el alcance adecuado y devolver la respuesta sintetizada.
Propagación de identidad

Para mantener la administración de datos empresariales cuando las solicitudes se originan en agentes raíz externos o de terceros, el servidor de MCP remoto aplica la propagación de identidad de extremo a extremo:

  • Autenticación delegada por el usuario: Cuando un usuario empresarial interactúa con el agente raíz, la plataforma de agentes autentica al usuario a través de un flujo de OAuth 2.0 de 3 segmentos y, además, incluye el token de acceso de OAuth delegado por el usuario en los encabezados HTTP de las solicitudes enviadas a la puerta de enlace de MCP.
  • Reenvío de credenciales de usuario final (EUC): El servidor de MCP remoto valida el token y propaga las credenciales de usuario final a través de la capa de la API de Conversational Analytics a los motores de datos subyacentes, como BigQuery, Spanner, AlloyDB y Cloud SQL.
  • Acceso a datos gobernados: Debido a que las consultas se ejecutan con la identidad del usuario autenticado, en lugar de una cuenta de servicio compartida, las fuentes de datos subyacentes aplican de forma automática los permisos de IAM existentes, las políticas de seguridad a nivel de fila y de columna, y los límites de acceso a datos gobernados. Los usuarios solo pueden descubrir agentes de datos y consultar conjuntos de datos a los que ya tienen permiso para acceder.
  • Modelo de dos identidades de Looker: Para BigQuery y las bases de datos operativas, las consultas se ejecutan con las credenciales de OAuth de Google reenviadas del usuario individual. En el caso de los agentes de datos respaldados por Looker, la autenticación usa un modelo de dos identidades: el token de OAuth de Google del usuario autoriza el acceso al agente de datos en IAM de Google, pero la consulta se ejecuta en Looker con las credenciales proporcionadas para un usuario de la API de Looker (que se pasan en el bloque de credenciales de la herramienta de chat). El acceso al modelo de Looker, los permisos y las reglas a nivel de fila reflejan ese usuario de la API configurado, en lugar de la identidad de Looker del usuario final individual.
Cómo acceden los agentes raíz a los métodos de la API

Cuando un cliente de MCP se conecta a https://geminidataanalytics.googleapis.com/mcp, llama al método estándar de MCP tools/list para importar de forma dinámica los esquemas de herramientas expuestos por la API de Conversational Analytics. Luego, el agente raíz interactúa con la API de Conversational Analytics invocando estas herramientas y recursos de MCP, que se asignan directamente a los métodos de la API de REST subyacentes:

Herramienta o recurso de MCP Método de la API de Conversational Analytics asignado Cómo lo usa el agente raíz
list_data_agents projects.locations.dataAgents.list

Descubre los agentes de datos disponibles. El agente raíz pasa el PROJECT_ID (y el LOCATION) de destino y recibe una lista de agentes de datos activos a los que el usuario tiene autorización para acceder, incluidos el ID y la descripción de cada agente. El agente raíz evalúa estas descripciones para determinar qué agente de datos puede responder la pregunta del usuario.

Sugerencia: Incluye el PROJECT_ID de destino en las instrucciones del sistema personalizadas del agente raíz para que este no les solicite a los usuarios empresariales que proporcionen un ID del proyecto.

get_data_agent

(o el recurso de MCP gda://agents/AGENT_ID)

 projects.locations.dataAgents.get

Inspecciona los metadatos y el contexto de un agente de datos específico. El agente raíz pasa el AGENT_ID de destino para recuperar detalles de configuración, como tablas de BigQuery conectadas, instrucciones del sistema, glosarios o consultas verificadas, cuando las descripciones de los agentes por sí solas no son suficientes para enrutar una instrucción compleja.
chat projects.locations.chat

Actúa como el proxy de ejecución para las consultas conversacionales. Para consultar un agente de datos descubierto, el agente raíz pasa data_agent_context que contiene el nombre completo del recurso del agente (projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID) y el mensaje en lenguaje natural del usuario en messages. Para las consultas ad hoc sin estado, el agente raíz puede pasar inline_context en su lugar. La herramienta devuelve respuestas en lenguaje natural, consultas en SQL generadas, filas de resultados, especificaciones de gráficos de Vega-Lite y razonamiento del agente.

MCP Toolbox para bases de datos

También puedes acceder a la API de Conversational Analytics a través del servidor de código abierto MCP Toolbox para bases de datos. Este servidor proporciona herramientas prediseñadas y compatibles con MCP que exponen el método chat en la API de Conversational Analytics:

El MCP es una capa de interoperabilidad que expone las capacidades de análisis como herramientas para los clientes compatibles con el MCP, en lugar de un modelo de ejecución independiente de la API de Conversational Analytics.

Patrones de implementación de MCP para arquitecturas independientes y de ADK

Puedes implementar MCP con los siguientes patrones:

Patrón Detalles
MCP independiente (sin ADK)

Usar el servidor de MCP Toolbox para bases de datos como un servidor independiente para conectarse a cualquier cliente compatible con MCP Este patrón se usa comúnmente para las siguientes tareas:

  • Integración de IDE: Conecta un IDE, como Antigravity, Cursor o VS Code, al servidor para consultar datos de forma conversacional desde un editor.
  • Cliente de MCP personalizado: Crea una aplicación que use el servidor para proporcionar una interfaz de herramientas uniforme en varios proveedores de IA.
  • Gemini CLI: Usa la CLI como un cliente de MCP para conversaciones de datos basadas en terminales.
MCP en el ADK

El framework del ADK proporciona los siguientes mecanismos para integrar servidores de MCP en los flujos de trabajo de los agentes:

  • ToolboxToolset: Es una variante especializada para el servidor de MCP Toolbox para bases de datos que admite varios métodos de autenticación.
  • McpToolset: Conecta un agente del ADK a cualquier servidor de MCP a través de conexiones de servidor de MCP locales o remotas. Descubre automáticamente las herramientas del servidor y las expone al agente.

También puedes crear servidores de MCP con el framework de FastMCP para exponer herramientas que se crearon con el framework del ADK a cualquier cliente que cumpla con el MCP. Este enfoque hace que tus agentes del ADK estén disponibles como herramientas en otros ecosistemas.

Elige un patrón de integración que cumpla con los requisitos de arquitectura específicos de tu aplicación:

  • El uso de conjuntos de herramientas integrados del Kit de desarrollo de agentes (ADK), como BigQueryToolset o DataAgentToolset, proporciona una integración más estrecha sin dependencias de servidores externos. Este enfoque es ideal para los sistemas que existen por completo dentro del framework del ADK.
  • El uso de las herramientas de MCP Toolbox proporciona interoperabilidad entre los clientes compatibles con MCP. Este enfoque es ideal para las herramientas de datos que deben entregar varias aplicaciones de consumidor o IDE de terceros.

Organización horizontal (A2A)

El protocolo Agent-to-Agent (A2A) es un estándar abierto que permite que los agentes especializados de diferentes sistemas se comuniquen y colaboren de forma segura sin necesidad de código de integración personalizado.

A medida que los sistemas escalan, las organizaciones suelen implementar varios agentes especializados que se crean en diferentes frameworks o infraestructuras de nube. A2A establece un nivel de mensajería universal para estos agentes autónomos. En lugar de usar APIs personalizadas, cada agente publica una tarjeta de agente, que es un perfil detectable que detalla las capacidades del agente, los formatos de datos admitidos y los requisitos de seguridad.

Cuando un agente central de organización o un agente par requiere datos analíticos, delega la tarea de forma segura a un agente de datos a través de mensajes estructurados de A2A. El agente de datos procesa la solicitud de forma autónoma y devuelve los hallazgos, lo que desvincula la lógica de ejecución del solicitante.

Para aprender a descubrir tarjetas de agentes, enviar mensajes y transmitir artefactos estructurados con el protocolo A2A, consulta Organiza agentes de datos con A2A.

Elige un patrón de integración

Usa la siguiente tabla para comparar la complejidad, la administración y las capacidades de cada patrón de integración.

Los niveles de complejidad se definen de la siguiente manera:

  • Bajo: Patrones que requieren un código personalizado mínimo y dependen de interfaces de usuario o herramientas prediseñadas.
  • Medio: Patrones que requieren desarrollo de frontend personalizado y la integración de APIs o SDKs, pero evitan una infraestructura de organización de backend compleja.
  • Alto: Patrones que requieren el desarrollo de aplicaciones de pila completa, la administración del estado de la conversación, varias capas de autenticación o una infraestructura de organización intermedia.
  • Varía: Son patrones en los que la complejidad depende del método de integración subyacente que elijas.
Patrón de integración Complejidad Personalización Administración de agentes Control de acceso Multiagente Transmisión Portabilidad
Incorporación de iframe de Looker Baja Baja Administración a través de Looker Looker No Integrado Solo Looker
API y SDK de Looker Media Alta Administración a través de Looker Looker No Integrado Solo Looker
API de Conversational Analytics con fuente de Looker Varía Alta Se administran a través de la API Looker y la IAM Sí Sí Cualquier Google Cloud plataforma
Agente único (API directa) Media Alta Se administran a través de la API IAM No Sí (compatible) Cualquier Google Cloud plataforma
Organizador personalizado Alta Muy alta Se administran a través de la API IAM Manual Manual Cualquier Google Cloud plataforma
Basado en esquemas con BigQueryToolset (ADK) Baja Media Ninguno (inferencia de esquema) IAM Sí (ADK) No (bloqueo) Ecosistema del ADK
Se rige por DataAgentToolset (ADK) Baja Media Se administran a través de la API IAM Sí (ADK) No (bloqueo) Ecosistema del ADK
Agente secundario de transmisión personalizado (ADK) Alta Muy alta Se administran a través de la API IAM Sí (ADK) Sí (personalizado) Ecosistema del ADK
MCP independiente Media Media Ninguno (inferencia de esquema) IAM No No Cualquier cliente de MCP
MCP en el ADK Media Alta Ninguno (inferencia de esquema) IAM Sí (ADK) No Clientes de ADK y MCP
Protocolo A2A Alta Alta Dependiente del framework IAM Sí Sí Multiplataforma

¿Qué sigue?