Schémas d'intégration pour les agents de données

Cette page décrit les modèles d'intégration permettant d'intégrer des expériences d'agent de données dans vos applications. La complexité de ces modèles varie d'un composant de chat intégré à un système multi-agent orchestré.

Ce guide s'adresse aux architectes cloud et aux ingénieurs de données qui conçoivent des applications d'IA générative. Vous devez posséder des connaissances de base sur les concepts Google Cloud , Identity and Access Management (IAM) et les API REST. Vous devez également connaître l'architecture de la source de données utilisée par votre application.

Présentation des schémas d'intégration

Ce guide est organisé en fonction des principaux parcours suivants, chacun d'eux étant basé sur votre point de départ :

  • Parcours Looker : sélectionnez ce parcours si vous souhaitez fournir des fonctionnalités de chat via l'intégration de Looker, l'API Looker ou l'API Conversational Analytics.
  • Parcours BigQuery et base de données : sélectionnez ce parcours si vous créez une application personnalisée qui utilise BigQuery, Data Studio ou une base de données opérationnelle compatible.

Le tableau suivant récapitule les modèles d'intégration disponibles :

Schéma d'intégration Description Source de données
Intégration d'un iFrame Looker Ajoute l'interface de discussion standard à une application qui nécessite un minimum de code. Looker
API et SDK Looker Crée une interface de chat personnalisée qui utilise l'API Looker pour l'authentification. Looker
API Conversational Analytics (source Looker) Gère les agents de données Looker en tant que ressources Google Cloud qui fonctionnent sur plusieurs surfaces et systèmes multi-agents. Looker
API directe (agent unique) Utilise une intégration d'API directe pour les flux de questions-réponses textuels. BigQuery, bases de données, Looker
API directe (orchestrateur) Achemine les requêtes entre l'API et d'autres outils à l'aide de l'appel de fonction. BigQuery, bases de données, Looker
ADK (basé sur un schéma) avec BigQueryToolset Génère des insights rapides à partir de références de table à l'aide de l'outil ask_data_insights. BigQuery
ADK (gouverné) avec DataAgentToolset Interroge des agents de données préconfigurés qui utilisent l'outil ask_data_agent pour garantir un comportement cohérent. BigQuery, bases de données, Looker
ADK (streaming personnalisé) Permet de diffuser des graphiques et du code SQL en temps réel à l'aide d'une classe d'agent personnalisée. BigQuery, bases de données, Looker
MCP avec McpToolset ou ToolboxToolset Connecte les applications aux outils de données qui utilisent le protocole MCP (Model Context Protocol). BigQuery, Looker
Serveur MCP distant de l'API Conversational Analytics Fournit une passerelle unifiée et sécurisée qui permet aux agents racine des plates-formes d'IA tierces et des plates-formes gérées par Google (comme Gemini Enterprise) de découvrir des agents de données spécialisés et de communiquer avec eux dans Google Cloud. BigQuery, bases de données, Looker
Protocole A2A Permet une collaboration sécurisée entre des agents spécialisés qui fonctionnent sur différents systèmes. Dépendant du framework

Options d'intégration pour Looker

Si vous utilisez Looker, vous pouvez fournir Looker Conversational Analytics à vos utilisateurs via les modèles suivants :

Résumé des modèles d'intégration Looker

Le tableau suivant récapitule les principaux modèles d'intégration pour Looker :

Modèle Application idéale Avantages Remarques
Intégration avec des iFrames : méthode low-code permettant d'ajouter rapidement l'expérience de chat Looker standard à une application. Équipes qui ont besoin d'une expérience Conversational Analytics prête pour la production avec un minimum de développement personnalisé.
  • Nécessite un minimum de code pour l'implémentation.
  • Applique automatiquement le modèle de sécurité Looker existant.
  • Ne nécessite pas d'authentification Google Cloud distincte.
  • Il est compatible avec le SDK Looker Embed, qui accélère le développement en gérant les cycles de vie des iFrames et la transmission des événements.
  • Il offre une personnalisation limitée de l'interface utilisateur et dépend de l'interface utilisateur de chat Looker standard.
  • Votre instance Looker doit être hébergée par Looker.
Créer avec l'API et les SDK Looker : une approche flexible pour créer une interface de chat personnalisée tout en conservant l'authentification et la gestion des agents dans Looker. Les équipes qui ont besoin d'une expérience utilisateur de chat personnalisée, mais qui souhaitent conserver l'authentification des utilisateurs et la gestion des agents dans l'écosystème Looker. Ce modèle est idéal pour les applications qui utilisent déjà l'intégration ou l'API Looker.
  • Fournit une couche d'authentification unique et un contrôle total sur l'interface utilisateur.
  • Simplifie l'architecture pour les clients Looker existants.
  • Utilise la couche sémantique Looker pour améliorer la précision des requêtes.
  • Ne nécessite pas d'authentification Google Cloud distincte.
  • Nécessite une expertise en développement d'API Looker.
  • Limité aux sources de données Looker.
  • Les agents sont gérés dans Looker et ne sont pas transférables vers d'autres services Google Cloud .
Utiliser l'API Conversational Analytics : intégration directe à l'API pour gérer les agents en tant que ressources au niveau du cloud. Clients Looker qui ont besoin d'une portabilité multiplateforme pour leurs agents de données.
  • S'assure que l'agent de données est portable sur toutes les surfaces Google Cloud .
  • Géré de manière centralisée par IAM.
  • Permet d'intégrer des agents de données dans des workflows ADK ou MCP.
  • Vous devez gérer l'intégralité de la pile d'intégration, y compris l'authentification Google Cloud et Looker.
  • Les agents de données sont gérés indépendamment de l'interface utilisateur de Looker.

Intégrer avec des iFrames

Vous pouvez intégrer Conversational Analytics en tant qu'iframe pour proposer l'expérience de chat en dehors de l'UI Looker. Ce modèle est un moyen direct de fournir Conversational Analytics qui ne nécessite aucun développement d'UI personnalisée, d'orchestration de backend ni de gestion de l'état de l'API. Pour utiliser ce modèle, vous devez ajouter une URL préformatée à votre application.

Le SDK Looker Embed fournit des outils qui gèrent des tâches telles que la génération d'URL sécurisées, la gestion du cycle de vie des iFrames et la transmission d'événements JavaScript entre l'application hôte et l'iFrame. Vous pouvez intégrer la page Agents, la page Conversations ou une conversation spécifique en ajoutant une URL préformatée à votre application.

Vous pouvez utiliser les méthodes d'authentification suivantes pour le contenu intégré :

  • Intégration privée : authentifie les utilisateurs avec leurs identifiants Looker existants. Lorsque vous définissez l'URL d'intégration comme source de l'iframe, les utilisateurs se connectent avec leur compte Looker. Cette méthode applique automatiquement les rôles, l'accès au contenu et les autorisations au niveau des données existants, tels que les filtres d'accès ou les octrois d'accès, sans nécessiter de configuration IAM ni de mappage de jetons supplémentaires.
  • Intégration signée : authentifie les utilisateurs via votre application à l'aide de l'authentification unique (SSO). Vous créez une URL signée qui inclut le chemin d'accès au contenu de Conversational Analytics, ce qui vous permet de spécifier de manière dynamique les autorisations exactes à accorder.

Créer avec l'API et les SDK Looker

Pour plus de flexibilité dans l'expérience de chat, vous pouvez utiliser les méthodes ConversationalAnalytics de l'API Looker ou un SDK Looker pour créer une application personnalisée. Cette approche vous permet de créer une interface personnalisée qui communique directement avec les points de terminaison Looker.

L'intégration à l'API Looker offre les avantages suivants :

  • Vous ne gérez l'authentification qu'avec Looker. Il n'est pas nécessaire de s'authentifier séparément auprès de l'API Conversational Analytics.
  • Pour les applications qui utilisent déjà l'intégration Looker ou l'API, ce modèle simplifie l'architecture du projet en évitant les mécanismes d'authentification secondaires et en éliminant la nécessité de gérer des agents de données externes.
  • Vous contrôlez entièrement l'interface de chat, le flux de conversation et la manière dont l'application affiche les résultats (par exemple, des graphiques et des tableaux).

Pour obtenir un exemple d'implémentation, consultez le guide de l'API Looker qui utilise les méthodes ConversationalAnalytics sur GitHub.

Utiliser l'API Conversational Analytics avec des données Looker

Vous pouvez intégrer directement l'API Conversational Analytics à geminidataanalytics.googleapis.com si vous devez effectuer l'une des tâches suivantes :

  • Partagez le même agent de données sur plusieurs surfaces Google Cloud , telles que des applications Web personnalisées, Google Chat et Gemini Enterprise.
  • Combinez des sources de données Looker avec des sources de données BigQuery ou de bases de données opérationnelles dans un seul système multi-agent.
  • Gérez votre agent de données en tant que ressource au niveau du cloud régie par IAM plutôt que par le modèle d'autorisations Looker.

Pour en savoir plus sur les modèles d'architecture courants pour l'API Conversational Analytics, consultez Options d'intégration pour BigQuery et les bases de données.

Options d'intégration pour BigQuery, Data Studio et les bases de données

Cette section décrit les modèles d'architecture pour les applications qui utilisent BigQuery, Data Studio ou des bases de données opérationnelles Google Cloud compatibles pour créer des expériences client personnalisées avec l'API Conversational Analytics.

Si vous utilisez l'API Conversational Analytics avec une source de données Looker, les modèles décrits dans cette section s'appliquent également à votre intégration.

L'API Conversational Analytics fournit les principales méthodes suivantes pour interagir avec les données :

  • Méthode chat : compatible avec BigQuery, Looker, Data Studio et les bases de données opérationnelles.
  • Méthode queryData : compatible avec les bases de données opérationnelles telles qu'AlloyDB, GoogleSQL pour Spanner, Cloud SQL pour MySQL et Cloud SQL pour PostgreSQL.

Lorsque vous créez une application personnalisée, vous pouvez utiliser un ou plusieurs des modèles d'intégration suivants :

  • Intégration directe de l'API : approche personnalisée qui offre une flexibilité maximale, mais qui nécessite de créer l'infrastructure pour l'authentification, la gestion des conversations et l'analyse des réponses.
  • Orchestration basée sur un framework (ADK) : approche qui utilise l'Agent Development Kit (ADK) pour le routage multi-agent, l'exécution des outils et la gestion de l'état.
  • Intégration verticale (MCP) : approche qui utilise le protocole MCP (Model Context Protocol) pour fournir un moyen uniforme de connecter des applications d'IA à des outils et des sources de données dans différents environnements.
  • Orchestration horizontale (A2A) : approche qui utilise le protocole Agent-to-Agent (A2A) pour permettre à des agents spécialisés sur différents systèmes de collaborer de manière sécurisée sans nécessiter de code d'intégration personnalisé.

Récapitulatif des modèles d'intégration de BigQuery et des bases de données

Le tableau suivant récapitule les modèles d'implémentation spécifiques pour BigQuery et les bases de données opérationnelles :

Modèle Application idéale Avantages Remarques
Intégration à agent unique (API directe) : modèle dans lequel votre application appelle directement l'API pour renvoyer des insights à partir de vos sources de données. Applications à agent unique, prototypes ou microservices nécessitant un contrôle direct sur chaque appel d'API.
  • Permet un contrôle précis sans dépendances de framework.
  • Fournit l'architecture la plus simple pour les cas d'utilisation à agent unique.
  • Prise en charge des modes avec et sans état.
  • Vous devez créer toute l'infrastructure pour l'authentification, la gestion de l'état, l'analyse des réponses, la gestion des exceptions, le streaming et le déploiement.
  • Ne s'adapte pas bien aux scénarios multi-agents.
Orchestrateur personnalisé (API directe) : modèle qui utilise un agent racine et l'appel de fonction pour acheminer les requêtes entre l'API Conversational Analytics et d'autres outils ou services. Applications qui combinent des requêtes de données avec d'autres tâches, telles que des e-mails ou des documents, dans un seul flux de conversation.
  • Offre un contrôle d'orchestration maximal sans dépendances de framework.
  • Vous permet de définir exactement comment le modèle effectue le routage entre les outils.
  • Fonctionne avec n'importe quel modèle Gemini.
  • Vous devez gérer manuellement les définitions d'outils, les boucles de conversation, l'état multitour, la gestion des exceptions et le déploiement.
  • La charge de travail liée au développement peut devenir fastidieuse par rapport à l'utilisation d'un framework tel que l'ADK.
Intégration basée sur un schéma avec BigQueryToolset (ADK) : un modèle qui utilise des références de table pour renvoyer rapidement des insights sur les données. Prototypage rapide, outils internes où la gouvernance des données est moins critique, ou scénarios où les insights sur les données sont l'une des nombreuses fonctionnalités d'un agent ADK.
  • Fournit le chemin d'intégration le plus rapide dans le framework ADK.
  • Aucune préconfiguration de l'agent de données n'est requise.
  • Fonctionne directement avec les noms des tables de base de données.
  • Il ne dispose pas de gouvernance sémantique et génère du code SQL uniquement à partir de l'inférence de schéma.
  • Fonctionne en mode sans état au niveau de l'API.
  • Fournit des réponses textuelles uniquement et n'accepte pas les graphiques.
Intégration gérée avec DataAgentToolset (ADK) : modèle qui interroge un agent de données préconfiguré en référençant l'ID de l'agent. Applications de production nécessitant un accès cohérent aux données ou systèmes multi-agents dans lesquels l'agent de données est un composant fiable et réutilisable.
  • Fournit une gouvernance sémantique et un comportement cohérent pour tous les consommateurs.
  • Améliore la précision à l'aide de requêtes validées et d'un glossaire d'entreprise.
  • Garantit que les agents de données sont réutilisables dans ADK, MCP et les intégrations d'API directes.
  • Nécessite de préconfigurer les ressources de l'agent de données.
  • Fonctionne en mode sans état au niveau de l'API.
  • Renvoie des réponses textuelles uniquement et n'est pas compatible avec les graphiques.
Sous-agents personnalisés (ADK) : modèle qui utilise une classe d'agent personnalisée pour se connecter directement à l'API et renvoyer des fragments de données à l'utilisateur. Applications visibles par l'utilisateur pour lesquelles une faible latence de réponse est une priorité, ou pipelines multi-agents où la récupération de données alimente les agents en aval.
  • Fournit des commentaires en temps réel.
  • Accède à tous les types de réponses, tels que les graphiques, les tableaux et le code SQL.
  • Composables avec d'autres agents ADK via l'état de la session.
  • Nécessite plus d'efforts de développement pour créer une classe d'agent ADK personnalisée.
  • Vous devez gérer directement la connexion de streaming et l'analyse des réponses.
Model Context Protocol (MCP) : un modèle qui utilise une norme ouverte pour connecter des applications d'IA à des sources de données et à des outils dans différents environnements. Les organisations qui ont besoin d'une interopérabilité des outils entre plusieurs clients d'IA et IDE, ou les équipes qui ont besoin que les mêmes outils de données soient accessibles depuis le framework ADK, les IDE et les applications personnalisées.
  • Utilise une norme d'outil universelle qui fonctionne avec n'importe quel client compatible avec MCP.
  • Dissocie l'implémentation des outils des applications grand public.
  • Propose des options de serveur géré, comme le serveur MCP Google Cloud .
  • Nécessite une couche d'infrastructure supplémentaire pour le serveur de boîte à outils.
  • Fournit une intégration moins étroite que les ensembles d'outils ADK.
  • Dépend de l'évolution de l'écosystème de la boîte à outils MCP.
  • Il fonctionne en mode sans état, ce qui nécessite de gérer l'état multitour en externe.
Agent-to-Agent (A2A) : modèle qui utilise le protocole A2A, une norme ouverte qui permet à des agents spécialisés sur différents systèmes de collaborer de manière sécurisée sans nécessiter de code d'intégration personnalisé. Environnements d'entreprise hautement distribués dans lesquels un agent de routage central doit déléguer des tâches à des agents de données qui opèrent sur différents systèmes ou réseaux.
  • Réduit le besoin de code d'intégration personnalisé entre des frameworks disparates.
  • Assure une interopérabilité multiplate-forme fluide.
  • Fournit une découverte sécurisée et standardisée des fonctionnalités.
  • Introduit une latence réseau mineure par rapport aux sous-agents internes.
  • Vous devez configurer les paramètres du serveur A2A.

Intégration directe de l'API

L'intégration directe de l'API offre un contrôle précis sur la logique et l'architecture de votre application, mais vous oblige à créer l'infrastructure compatible. Avec cette approche, vous êtes responsable de tâches telles que l'authentification, la gestion des conversations, l'analyse des réponses et le déploiement.

Cette section aborde les sujets suivants :

  • Intégration d'un seul agent : modèle dans lequel votre application appelle directement l'API Conversational Analytics pour renvoyer des insights à partir de vos sources de données.
  • Intégration d'un orchestrateur personnalisé : modèle avancé qui utilise un agent racine et l'appel de fonction pour acheminer les requêtes entre l'API Conversational Analytics.

Intégration d'un seul agent

Avec une intégration à agent unique, votre backend appelle directement l'API Conversational Analytics à l'aide de REST ou d'une bibliothèque cliente, et transmet la requête et le contexte de l'utilisateur. Ce modèle convient aux applications peu complexes, telles que les applications Web, les outils de chat internes ou les microservices, qui utilisent un flux de questions-réponses textuel simple. Vous pouvez également utiliser cette approche pour le prototypage et les démonstrations de faisabilité.

Ce modèle est compatible avec le chat avec état, où Google gère l'historique des conversations, et le chat sans état, où votre application gère l'historique.

Pour obtenir des implémentations de référence, consultez le guide de démarrage rapide de l'API Conversational Analytics ou la démo Golden de l'API Conversational Analytics sur GitHub.

Intégration d'un outil d'orchestration personnalisé

Avec cette approche, vous créez un agent racine qui sert de point d'entrée principal et de coordinateur pour votre application. L'agent racine utilise un modèle Gemini standard équipé d'outils via l'appel de fonction. Lorsqu'un utilisateur pose une question liée aux données, l'agent racine émet un appel d'outil vers l'API Conversational Analytics, reçoit le résultat, puis peut continuer à raisonner ou appeler d'autres outils en aval.

L'appel de fonction comprend les étapes suivantes :

  1. Déclarer : définissez les schémas d'outils en tant qu'objets FunctionDeclaration incluant des définitions de paramètres.
  2. Appel : le modèle renvoie un message functionCall structuré contenant le nom de la fonction et les arguments.
  3. Exécuter : votre application effectue l'appel d'API et renvoie le résultat dans un message FunctionResponse.
  4. Synthèse : le modèle Gemini utilise le résultat pour générer une réponse finale ou déterminer l'action suivante.

Cette approche est adaptée aux applications dans lesquelles les utilisateurs peuvent demander des insights sur les données en plus d'autres tâches. Par exemple, un utilisateur peut demander à l'agent de "montrer les ventes, puis de rédiger un e-mail pour l'équipe commerciale". L'agent racine peut acheminer la question sur les données vers l'API Conversational Analytics et utiliser d'autres outils pour les tâches non liées aux données.

Pour obtenir une implémentation de référence, consultez les pages orchestrate ou multimodal de la démo Golden de l'API Conversational Analytics sur GitHub.

Orchestration basée sur un framework (ADK)

Agent Development Kit (ADK) est un framework axé sur le code permettant de créer des agents IA qui gèrent la complexité du routage multi-agents, de l'exécution des outils et de la gestion des états. Le framework ADK est le même que celui qui alimente Gemini Enterprise.

En utilisant l'ADK, vous pouvez associer l'API Conversational Analytics à d'autres outils et agents pour effectuer des actions complexes.

Cette section aborde les sujets suivants :

Intégration basée sur un schéma avec BigQueryToolset

L'ensemble d'outils BigQueryToolset du framework ADK inclut un outil ask_data_insights prédéfini. Pour utiliser cet outil, vous lui transmettez les noms des tables et la question de l'utilisateur. Il appelle ensuite l'API Conversational Analytics en utilisant le contexte intégré.

Lorsque vous appelez l'outil, il envoie une requête sans état incluant les références de table BigQuery spécifiées à l'API Conversational Analytics. L'API déduit le schéma de la base de données, génère et exécute la requête SQL, puis renvoie une réponse textuelle. Le résultat est ensuite renvoyé à l'agent ADK en tant que réponse de l'outil.

Ce modèle est un moyen efficace d'ajouter rapidement l'analyse conversationnelle à un agent. Toutefois, comme l'appel à l'API est sans état et ne dispose pas de gouvernance, l'API génère du code SQL entièrement basé sur le schéma de la table, sans garde-fous sémantiques. Ce modèle est plus rapide à déployer, mais plus risqué pour la logique métier de production où s'appliquent des conventions d'attribution de noms, une logique métier ou des contrôles d'accès.

Intégration gérée avec DataAgentToolset

L'ensemble d'outils DataAgentToolset du framework ADK fournit une intégration prédéfinie qui référence un agent de données préconfiguré par son ID. L'agent ADK transmet la question de l'utilisateur à l'outil ask_data_agent, qui appelle l'API Conversational Analytics avec le contexte de l'agent de données spécifié.

Vous pouvez créer un agent de données de manière programmatique à l'aide de l'API Conversational Analytics ou via le catalogue d'agents dans la console Google Cloud . Un agent de données est équipé des composants suivants :

  • Sources de connaissances : tables, vues ou fonctions définies par l'utilisateur (UDF) que l'agent peut interroger
  • Contexte structuré : descriptions des tables et des colonnes qui aident l'agent à comprendre les données sous-jacentes
  • Instructions : conseils supplémentaires pour que l'agent interprète et interroge les sources de données
  • Requêtes validées : requêtes SQL prévalidées qui servent d'exemples pour les questions courantes
  • Glossaire : définitions de termes commerciaux qui aident l'agent à comprendre le langage spécifique à un domaine

Pour obtenir un guide détaillé sur la création d'agents via le catalogue d'agents, consultez l'atelier de programmation Analyse conversationnelle dans BigQuery.

Comme l'agent est défini comme une unité gouvernée, il utilise la même logique, le même contexte et les mêmes garde-fous de confiance, quelle que soit l'application ou le sous-agent qui l'appelle.

Intégration d'UX avancée avec des sous-agents personnalisés

Les ensembles d'outils BigQueryToolset et DataAgentToolset ne renvoient pas de résultats à l'utilisateur tant que le traitement de la requête API n'est pas terminé. Étant donné que le framework ADK traite l'API comme un outil qui bloque les réponses jusqu'à la fin de l'exécution, les requêtes plus longues peuvent laisser les utilisateurs sans réponse.

Pour les applications où une faible latence de réponse est une priorité ou où la récupération des données alimente des agents en aval, vous pouvez créer une classe d'agent ADK personnalisée qui se connecte directement à l'API Conversational Analytics et renvoie les données à l'utilisateur de manière asynchrone par fragments. Ce modèle accepte les types de réponses suivants au fur et à mesure qu'ils sont produits :

  • Messages de réflexion : processus de raisonnement de l'agent de données lorsqu'il interprète la question.
  • Messages de progression : mises à jour de l'état pendant la récupération des données pour les sources de données.
  • Génération de requêtes : requête SQL ou Looker générée, qui est diffusée en flux continu au fur et à mesure de sa production.
  • Data : résultats des données au format JSON.
  • Visualisation : spécifications du graphique Vega-Lite.
  • Résumé : réponse textuelle finale.

Pour obtenir la liste complète des types de données renvoyés, consultez le type SystemMessage dans la documentation de référence de l'API.

Cette approche asynchrone évite aux utilisateurs d'avoir à attendre la fin d'un processus complexe de récupération des données. Au fur et à mesure que l'agent de données progresse dans le processus de requête, il partage en continu des mises à jour incrémentielles (comme des résumés textuels, des données brutes ou des configurations de graphiques) dans un espace de travail partagé temporaire. Ces données peuvent ensuite être affichées pour l'utilisateur en temps réel et partagées avec des sous-agents spécialisés pour effectuer des tâches supplémentaires.

Pour obtenir une implémentation de référence comprenant un agent racine, un sous-agent de données et un agent de visualisation, consultez la démo de streaming ADK sur GitHub.

Intégration verticale (MCP)

Le Model Context Protocol (MCP) est une norme ouverte qui permet aux applications d'IA de se connecter de manière uniforme à des outils et des sources de données externes. MCP standardise l'interface entre les modèles d'IA et les outils qu'ils utilisent.

Cette section aborde les sujets suivants :

Serveur MCP distant de l'API Conversational Analytics

L'API Conversational Analytics fournit un serveur MCP distant à l'adresse https://geminidataanalytics.googleapis.com/mcp, optimisé par le serveur MCP géré de Google. Cette passerelle fournit une interface HTTP et SSE (Server-Sent Events) unifiée et sécurisée qui permet aux agents racine des plates-formes d'IA tierces et des plates-formes gérées par Google (comme Gemini Enterprise) de découvrir des agents de données spécialisés et de communiquer avec eux dans Google Cloud.

Présentation de la communication de l'agent racine

La communication entre un agent racine externe ou géré par Google et l'API Conversational Analytics implique trois rôles distincts :

  1. Les opérateurs de données créent et configurent des agents de données limités sur les surfaces de Conversational Analytics, rédigent des descriptions claires des sources de données auxquelles chaque agent peut accéder et des questions auxquelles il peut répondre, et partagent ces agents avec les utilisateurs professionnels.
  2. Les administrateurs de la plate-forme enregistrent une connexion MCP personnalisée dans leur plate-forme d'agents pointant vers le point de terminaison https://geminidataanalytics.googleapis.com/mcp. Les administrateurs configurent les identifiants client OAuth 2.0 (ID client et code secret du client) à l'aide du point de terminaison d'autorisation Google (https://accounts.google.com/o/oauth2/v2/auth), du point de terminaison du jeton (https://oauth2.googleapis.com/token) et des champs d'application d'autorisation requis (https://www.googleapis.com/auth/geminidataanalytics et https://www.googleapis.com/auth/bigquery.readonly).
  3. Les utilisateurs professionnels posent des questions en langage naturel dans la plate-forme d'agents. Plutôt que d'interroger directement les bases de données brutes, l'agent racine de la plate-forme (le LLM de l'orchestrateur) communique avec le serveur MCP distant de l'API Conversational Analytics pour découvrir les agents de données pertinents, acheminer la question de l'utilisateur vers l'agent de données approprié et renvoyer la réponse synthétisée.
Propagation des identités

Pour maintenir la gouvernance des données d'entreprise lorsque les requêtes proviennent d'agents racine tiers ou externes, le serveur MCP distant applique la propagation d'identité de bout en bout :

  • Authentification déléguée par l'utilisateur : lorsqu'un utilisateur professionnel interagit avec l'agent racine, la plate-forme d'agents authentifie l'utilisateur via un flux OAuth 2.0 à trois étapes et inclut le jeton d'accès OAuth délégué par l'utilisateur dans les en-têtes HTTP des requêtes envoyées à la passerelle MCP.
  • Transfert des identifiants de l'utilisateur final (EUC) : le serveur MCP distant valide le jeton et propage les identifiants de l'utilisateur final via la couche de l'API Conversational Analytics vers les moteurs de données sous-jacents, tels que BigQuery, Spanner, AlloyDB et Cloud SQL.
  • Accès aux données gouverné : étant donné que les requêtes sont exécutées à l'aide de l'identité de l'utilisateur authentifié plutôt que d'un compte de service partagé, les sources de données sous-jacentes appliquent automatiquement les autorisations IAM existantes, les règles de sécurité au niveau des lignes et des colonnes, et les limites d'accès aux données gouvernées. Les utilisateurs ne peuvent découvrir que les agents de données et interroger que les ensembles de données auxquels ils sont déjà autorisés à accéder.
  • Modèle à deux identités Looker : pour BigQuery et les bases de données opérationnelles, les requêtes s'exécutent sous les identifiants Google OAuth transférés de l'utilisateur individuel. Pour les agents de données basés sur Looker, l'authentification utilise un modèle à deux identités : le jeton OAuth Google de l'utilisateur autorise l'accès à l'agent de données dans Google IAM, mais la requête s'exécute dans Looker à l'aide des identifiants fournis pour un utilisateur de l'API Looker (transmis dans le bloc d'identifiants de l'outil de chat). L'accès au modèle Looker, les autorisations et les règles au niveau des lignes reflètent cet utilisateur de l'API configuré, plutôt que l'identité Looker de l'utilisateur final individuel.
Comment les agents racine accèdent aux méthodes d'API

Lorsqu'un client MCP se connecte à https://geminidataanalytics.googleapis.com/mcp, il appelle la méthode MCP tools/list standard pour importer dynamiquement les schémas d'outils exposés par l'API Conversational Analytics. L'agent racine interagit ensuite avec l'API Conversational Analytics en appelant ces outils et ressources MCP, qui correspondent directement aux méthodes de l'API REST sous-jacentes :

Outil ou ressource MCP Méthode de l'API Conversational Analytics mappée Comment l'agent racine l'utilise
list_data_agents projects.locations.dataAgents.list

Découvre les agents de données disponibles. L'agent racine transmet le PROJECT_ID (et le LOCATION) cible et reçoit une liste des agents de données actifs auxquels l'utilisateur est autorisé à accéder, y compris l'ID et la description de chaque agent. L'agent racine évalue ces descriptions pour déterminer quel agent de données peut répondre à la question de l'utilisateur.

Conseil : Incluez l'ID du projet cible (PROJECT_ID) dans les instructions système personnalisées de l'agent racine afin qu'il ne demande pas aux utilisateurs professionnels de fournir un ID de projet.

get_data_agent

(ou la ressource MCP gda://agents/AGENT_ID)

 projects.locations.dataAgents.get

Inspecte les métadonnées et le contexte d'un agent de données spécifique. L'agent racine transmet la cible AGENT_ID pour récupérer les détails de configuration (tables BigQuery connectées, instructions système, glossaires ou requêtes validées, par exemple) lorsque les descriptions des agents ne suffisent pas à acheminer un prompt complexe.
chat projects.locations.chat

Sert de proxy d'exécution pour les requêtes conversationnelles. Pour interroger un agent de données découvert, l'agent racine transmet data_agent_context contenant le nom complet de la ressource de l'agent (projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID) et le message en langage naturel de l'utilisateur dans messages. Pour les requêtes ad hoc sans état, l'agent racine peut transmettre inline_context à la place. L'outil renvoie des réponses en langage naturel, des requêtes SQL générées, des lignes de résultats, des spécifications de graphique Vega-Lite et le raisonnement de l'agent.

MCP Toolbox for Databases

Vous pouvez également accéder à l'API Conversational Analytics via le serveur Open Source MCP Toolbox for Databases. Ce serveur fournit des outils prédéfinis compatibles avec MCP qui exposent la méthode chat dans l'API Conversational Analytics :

MCP est une couche d'interopérabilité qui expose les fonctionnalités d'analyse en tant qu'outils aux clients compatibles MCP, plutôt qu'un modèle d'exécution distinct de l'API Conversational Analytics.

Modèles d'implémentation du protocole MCP pour les architectures autonomes et ADK

Vous pouvez implémenter MCP via les modèles suivants :

Modèle Détails
MCP autonome (sans ADK)

Utiliser le serveur MCP Toolbox for Databases en tant que serveur autonome pour se connecter à n'importe quel client compatible avec MCP Ce modèle est couramment utilisé pour les tâches suivantes :

  • Intégration d'IDE : connectez un IDE (comme Antigravity, Cursor ou VS Code) au serveur pour interroger les données de manière conversationnelle à partir d'un éditeur.
  • Client MCP personnalisé : créez une application qui utilise le serveur pour fournir une interface d'outil uniforme entre plusieurs fournisseurs d'IA.
  • Gemini CLI : utilisez la CLI comme client MCP pour les conversations de données basées sur un terminal.
MCP dans ADK

Le framework ADK fournit les mécanismes suivants pour intégrer des serveurs MCP aux workflows d'agent :

  • ToolboxToolset : variante spécialisée pour le serveur MCP Toolbox for Databases qui accepte plusieurs méthodes d'authentification.
  • McpToolset : connecte un agent ADK à n'importe quel serveur MCP à l'aide de connexions de serveur MCP locales ou distantes. Détecte automatiquement les outils du serveur et les expose à l'agent.

Vous pouvez également créer des serveurs MCP à l'aide du framework FastMCP pour exposer les outils créés avec le framework ADK à n'importe quel client compatible MCP. Cette approche permet de rendre vos agents ADK disponibles en tant qu'outils dans d'autres écosystèmes.

Choisissez un modèle d'intégration qui répond aux exigences architecturales spécifiques de votre application :

  • L'utilisation d'ensembles d'outils ADK (Agent Development Kit) intégrés, tels que BigQueryToolset ou DataAgentToolset, permet une intégration plus étroite sans dépendance à un serveur externe. Cette approche est idéale pour les systèmes qui existent entièrement dans le framework ADK.
  • L'utilisation des outils de MCP Toolbox assure l'interopérabilité entre les clients conformes à MCP. Cette approche est idéale pour les outils de données qui doivent diffuser plusieurs applications clientes ou IDE tiers.

Orchestration horizontale (A2A)

Le protocole A2A (Agent-to-Agent) est une norme ouverte qui permet à des agents spécialisés sur différents systèmes de communiquer et de collaborer de manière sécurisée, sans nécessiter de code d'intégration personnalisé.

À mesure que les systèmes évoluent, les entreprises déploient souvent plusieurs agents spécialisés, conçus sur des frameworks ou des infrastructures cloud différents. A2A établit un niveau de messagerie universel pour ces agents autonomes. Au lieu d'utiliser des API personnalisées, chaque agent publie une fiche d'agent, qui est un profil visible détaillant les capacités de l'agent, les formats de données compatibles et les exigences de sécurité.

Lorsqu'un orchestrateur central ou un agent pair a besoin de données analytiques, il délègue la tâche de manière sécurisée à un agent de données via une messagerie A2A structurée. L'agent de données traite la requête de manière autonome et renvoie les résultats, ce qui dissocie la logique d'exécution du demandeur.

Pour découvrir comment détecter des fiches d'agent, envoyer des messages et diffuser des artefacts structurés à l'aide du protocole A2A, consultez Orchestrer des agents de données avec A2A.

Choisir un modèle d'intégration

Utilisez le tableau suivant pour comparer la complexité, la gouvernance et les fonctionnalités de chaque modèle d'intégration.

Les niveaux de complexité sont définis comme suit :

  • Faible : modèles qui nécessitent un minimum de code personnalisé et s'appuient sur des interfaces utilisateur ou des outils prédéfinis.
  • Moyen : modèles nécessitant un développement d'interface personnalisé et une intégration d'API ou de SDK, mais évitant une infrastructure d'orchestration de backend complexe.
  • Élevée : modèles nécessitant un développement d'applications full stack, une gestion de l'état des conversations, plusieurs couches d'authentification ou une infrastructure d'orchestrateur intermédiaire.
  • Variable : modèles dont la complexité dépend de la méthode d'intégration sous-jacente que vous choisissez.
Schéma d'intégration Complexité Personnalisation Gouvernance des agents Contrôle des accès Plusieurs agents Streaming Portabilité
Intégration d'un iFrame Looker Faible Faible Géré via Looker Looker Non Intégré Looker uniquement
API et SDK Looker Moyenne Élevée Géré via Looker Looker Non Intégré Looker uniquement
API Conversational Analytics avec une source Looker Variable Élevée Géré via l'API Looker et IAM Oui Oui Toutes Google Cloud les surfaces
Agent unique (API directe) Moyenne Élevée Géré via l'API IAM Non Oui (compatible) Toutes Google Cloud les surfaces
Orchestrateur personnalisé Élevée Très élevée Géré via l'API IAM Manuel Manuel Toutes Google Cloud les surfaces
Basé sur un schéma avec BigQueryToolset (ADK) Faible Moyenne Aucun (inférence de schéma) IAM Oui (ADK) Non (bloquant) Écosystème ADK
Géré avec DataAgentToolset (ADK) Faible Moyenne Géré via l'API IAM Oui (ADK) Non (bloquant) Écosystème ADK
Sous-agent de streaming personnalisé (ADK) Élevée Très élevée Géré via l'API IAM Oui (ADK) Oui (personnalisé) Écosystème ADK
MCP autonome Moyenne Moyenne Aucun (inférence de schéma) IAM Non Non N'importe quel client MCP
MCP dans ADK Moyenne Élevée Aucun (inférence de schéma) IAM Oui (ADK) Non Clients ADK et MCP
Protocole A2A Élevée Élevée Dépendant du framework IAM Oui Oui Multiplate-forme

Étapes suivantes