Padrões de integração para agentes de dados

Nesta página, descrevemos padrões de integração para incorporar experiências de agentes de dados aos seus aplicativos. Esses padrões variam em complexidade, desde um componente de chat incorporado até um sistema multiagente orquestrado.

Este guia é destinado a arquitetos de nuvem e engenheiros de dados que projetam aplicativos de IA generativa. É preciso ter uma compreensão básica dos conceitos do Google Cloud , do Identity and Access Management (IAM) e das APIs REST. Também é preciso conhecer a arquitetura da fonte de dados que seu aplicativo usa.

Visão geral dos padrões de integração

Este guia está organizado nas seguintes etapas principais, cada uma baseada no seu ponto de partida:

  • Faixa do Looker: selecione essa faixa se quiser oferecer a funcionalidade de chat por meio da incorporação do Looker, da API Looker ou da API Conversational Analytics.
  • Faixa do BigQuery e do banco de dados: selecione essa faixa se você estiver criando um aplicativo personalizado que usa o BigQuery, o Data Studio ou um banco de dados operacional compatível.

A tabela a seguir resume os padrões de integração disponíveis:

Padrão de integração Descrição Fonte de dados
Incorporação de iframe do Looker Adiciona a interface de chat convencional a um aplicativo que requer código mínimo. Looker
API Looker e SDKs Cria uma interface de chat personalizada que usa a API Looker para autenticação. Looker
API de Análise conversacional (fonte do Looker) Gerencia os agentes de dados do Looker como recursos do Google Cloud que funcionam em várias plataformas e sistemas multiagente. Looker
API direta (agente único) Usa uma integração direta de API para fluxos de texto para resposta. BigQuery, bancos de dados, Looker
API direta (orquestrador) Encaminha consultas entre a API e outras ferramentas usando chamadas de função. BigQuery, bancos de dados, Looker
ADK (orientado por esquema) com BigQueryToolset Gera insights rápidos de referências de tabela usando a ferramenta ask_data_insights. BigQuery
ADK (controlado) com DataAgentToolset Consulta agentes de dados pré-configurados que usam a ferramenta ask_data_agent para garantir um comportamento consistente. BigQuery, bancos de dados, Looker
ADK (streaming personalizado) Oferece suporte ao streaming em tempo real de gráficos e SQL usando uma classe de agente personalizada. BigQuery, bancos de dados, Looker
MCP com McpToolset ou ToolboxToolset Conecta aplicativos a ferramentas de dados que usam o Protocolo de Contexto de Modelo (MCP). BigQuery, Looker
Servidor MCP remoto da API Análise conversacional Oferece um gateway seguro unificado que permite que agentes raiz em plataformas de IA de terceiros e plataformas gerenciadas pelo Google (como o Gemini Enterprise) descubram e se comuniquem com agentes de dados especializados no Google Cloud. BigQuery, bancos de dados, Looker
Protocolo A2A Permite a colaboração segura entre agentes especializados que operam em sistemas diferentes. Dependente do framework

Opções de integração para o Looker

Se você usa o Looker, pode fornecer a Análise Conversacional do Looker aos usuários pelos seguintes padrões:

Resumo dos padrões de integração do Looker

A tabela a seguir resume os principais padrões de integração do Looker:

Padrão Ideal para Vantagens Considerações
Incorporação com iframes: um método de pouco código para adicionar rapidamente a experiência de chat padrão do Looker a um aplicativo. Equipes que precisam de uma experiência de Análise Conversacional pronta para produção com o mínimo de desenvolvimento personalizado.
  • Requer um código mínimo para implementação.
  • Aplica automaticamente o modelo de segurança atual do Looker.
  • Não exige autenticação Google Cloud separada.
  • Oferece suporte ao SDK de incorporação do Looker, que acelera o desenvolvimento ao gerenciar os ciclos de vida do iframe e a transmissão de eventos.
  • Oferece personalização limitada da UI e depende da interface do usuário de chat padrão do Looker.
  • Sua instância do Looker precisa ser hospedada pelo Looker.
Criar com a API e os SDKs do Looker: uma abordagem flexível para criar uma interface de chat personalizada, mantendo a autenticação e o gerenciamento de agentes no Looker. Equipes que precisam de uma experiência do usuário de chat personalizada, mas querem manter a autenticação do usuário e o gerenciamento de agentes no ecossistema do Looker. Esse padrão é ideal para aplicativos que já usam a incorporação ou a API do Looker.
  • Oferece uma única camada de autenticação e controle total sobre a interface do usuário.
  • Simplifica a arquitetura para os clientes atuais do Looker.
  • Usa a camada semântica do Looker para melhorar a precisão das consultas.
  • Não exige autenticação Google Cloud separada.
  • Requer experiência em desenvolvimento de API Looker.
  • Limitado às fontes de dados do Looker.
  • Os agentes são gerenciados no Looker e não podem ser transferidos para outros serviços do Google Cloud .
Usar a API de Análise conversacional: integração direta com a API para gerenciar agentes como recursos no nível da nuvem. Clientes do Looker que precisam de portabilidade multiplataforma para os agentes de dados.
  • Garante que o agente de dados seja portátil em todas as plataformas do Google Cloud .
  • Controladas de forma centralizada pelo IAM.
  • Permite integrar agentes de dados aos fluxos de trabalho do ADK ou do MCP.
  • Exige que você gerencie toda a pilha de integração, incluindo a autenticação do Google Cloud e do Looker.
  • Os agentes de dados são gerenciados de forma independente da interface do usuário do Looker.

Incorporar com iframes

É possível incorporar a Análise conversacional como um iframe para oferecer a experiência de chat fora da interface do Looker. Esse padrão é uma maneira direta de fornecer a Análise Conversacional que não requer desenvolvimento UI personalizada, orquestração de back-end ou gerenciamento de estado de API. Para usar esse padrão, adicione um URL pré-formatado ao aplicativo.

O SDK de incorporação do Looker oferece ferramentas que gerenciam tarefas como geração de URL segura, gerenciamento do ciclo de vida do iframe e transmissão de eventos JavaScript entre o aplicativo hospedado e o iframe. É possível incorporar a página Agentes, a página Conversas ou uma conversa específica adicionando um URL pré-formatado ao seu aplicativo.

É possível usar os seguintes métodos de autenticação para conteúdo incorporado:

  • Incorporação particular: autentica os usuários com as credenciais do Looker. Quando você define o URL de incorporação como a origem do iframe, os usuários fazem login com as contas do Looker. Esse método aplica automaticamente os papéis, o acesso ao conteúdo e as permissões no nível dos dados, como filtros de acesso ou concessões de acesso, sem exigir configuração extra do IAM ou mapeamento de tokens.
  • Incorporação assinada: autentica os usuários no aplicativo usando o Logon único (SSO). Você cria um URL assinado que inclui o caminho do conteúdo da Análise conversacional, o que permite especificar dinamicamente quais permissões conceder.

Criar com a API Looker e os SDKs

Para mais flexibilidade na experiência de chat, use os métodos ConversationalAnalytics na API Looker ou um SDK do Looker para criar um aplicativo personalizado. Essa abordagem permite criar um front-end personalizado que se comunica diretamente com os endpoints do Looker.

A integração com a API Looker oferece os seguintes benefícios:

  • Você só gerencia a autenticação com o Looker. Não é necessário fazer uma autenticação separada com a API Análise conversacional.
  • Para aplicativos que já usam a incorporação ou a API do Looker, esse padrão simplifica a arquitetura do projeto, evitando mecanismos de autenticação secundários e eliminando a necessidade de gerenciar agentes de dados externos.
  • Você tem controle total sobre a interface do chat, o fluxo da conversa e como o aplicativo renderiza os resultados (como gráficos e tabelas).

Para uma implementação de referência, consulte o guia da API Looker que usa métodos ConversationalAnalytics no GitHub.

Usar a API Análise conversacional com dados do Looker

É possível fazer a integração direta com a API Análise conversacional em geminidataanalytics.googleapis.com se você precisar realizar uma das seguintes tarefas:

  • Compartilhe o mesmo agente de dados em várias Google Cloud plataformas, como aplicativos da Web personalizados, Google Chat e Gemini Enterprise.
  • Combine fontes de dados do Looker com fontes do BigQuery ou de bancos de dados operacionais em um único sistema multiagente.
  • Gerencie seu agente de dados como um recurso no nível da nuvem, regido pelo IAM em vez do modelo de permissão do Looker.

Para mais informações sobre padrões de arquitetura comuns para a API Análise conversacional, consulte Opções de integração para o BigQuery e bancos de dados.

Opções de integração para o BigQuery, o Data Studio e bancos de dados

Nesta seção, descrevemos padrões de arquitetura para aplicativos que usam o BigQuery, o Data Studio ou bancos de dados operacionais compatíveis com o Google Cloud para criar experiências personalizadas com a API Conversational Analytics.

Se você usa a API Análise conversacional com uma fonte de dados do Looker, os padrões descritos nesta seção também se aplicam à sua integração.

A API de Análise conversacional oferece os seguintes métodos principais para interagir com dados:

  • Método chat: compatível com o BigQuery, o Looker, o Data Studio e bancos de dados operacionais.
  • Método queryData: é compatível com bancos de dados operacionais, como AlloyDB, GoogleSQL para Spanner, Cloud SQL para MySQL e Cloud SQL para PostgreSQL.

Ao criar um aplicativo personalizado, é possível usar um ou mais dos seguintes padrões de integração:

  • Integração direta com a API: uma abordagem personalizada que oferece a maior flexibilidade, mas exige que você crie a infraestrutura para autenticação, gerenciamento de conversas e análise de respostas.
  • Orquestração baseada em framework (ADK): uma abordagem que usa o Kit de Desenvolvimento de Agente (ADK) para roteamento multiagente, execução de ferramentas e gerenciamento de estado.
  • Integração vertical (MCP): uma abordagem que usa o Protocolo de Contexto de Modelo (MCP) para fornecer uma maneira uniforme de conectar aplicativos de IA a ferramentas e fontes de dados em diferentes ambientes.
  • Orquestração horizontal (A2A): uma abordagem que usa o protocolo Agent-to-Agent (A2A) para permitir que agentes especializados em diferentes sistemas colaborem de forma segura sem precisar de código de integração personalizado.

Resumo dos padrões de integração do BigQuery e do banco de dados

A tabela a seguir resume os padrões de implementação específicos para o BigQuery e os bancos de dados operacionais:

Padrão Ideal para Vantagens Considerações
Integração de agente único (API direta): um padrão em que seu aplicativo chama a API diretamente para retornar insights das suas fontes de dados. Aplicativos, protótipos ou microsserviços de agente único que exigem controle direto sobre cada chamada de API.
  • Oferece controle granular sem dependências de framework.
  • Oferece a arquitetura mais simples para casos de uso de agente único.
  • Suporte aos modos com e sem estado.
  • Exige que você crie toda a infraestrutura para autenticação, gerenciamento de estado, análise de respostas, tratamento de erros, streaming e implantação.
  • Não é escalonável para cenários com vários agentes.
Orquestrador personalizado (API direta): um padrão que usa um agente raiz e uma chamada de função para encaminhar consultas entre a API de Análise conversacional e outras ferramentas ou serviços. Aplicativos que combinam consultas de dados com outras tarefas, como e-mail ou documentos, em um único fluxo de conversa.
  • Oferece controle máximo de orquestração sem dependências de framework.
  • Permite definir exatamente como o roteamento de modelos entre as ferramentas.
  • Funciona com qualquer modelo do Gemini.
  • Exige que você gerencie manualmente as definições de ferramentas, os loops de conversa, o estado multiturno, o tratamento de erros e a implantação.
  • A sobrecarga de desenvolvimento pode se tornar um fardo em comparação com o uso de um framework como o ADK.
Integração baseada em esquema com o BigQueryToolset (ADK): um padrão que usa referências de tabela para retornar insights de dados rapidamente. Prototipagem rápida, ferramentas internas em que a governança de dados é menos crítica ou cenários em que os insights de dados são um dos vários recursos de um agente do ADK.
  • Oferece o caminho de integração mais rápido no framework do ADK.
  • Não requer pré-configuração do agente de dados.
  • Funciona diretamente com nomes de tabelas de banco de dados.
  • Não tem governança semântica e gera SQL apenas com base na inferência de esquema.
  • Opera em um modo sem estado no nível da API.
  • Oferece respostas somente em texto e não é compatível com gráficos.
Integração controlada com o DataAgentToolset (ADK): um padrão que consulta um agente de dados pré-configurado referenciando o ID dele. Aplicativos Production que exigem acesso consistente a dados ou sistemas multiagente em que o agente de dados é um componente confiável e reutilizável.
  • Oferece governança semântica e comportamento consistente para todos os consumidores.
  • Melhora a precisão usando consultas verificadas e um glossário empresarial.
  • Garante que os agentes de dados sejam reutilizáveis em integrações de ADK, MCP e API direta.
  • É necessário pré-configurar os recursos do agente de dados.
  • Opera em um modo sem estado no nível da API.
  • Retorna respostas somente em texto e não é compatível com gráficos.
Subagentes personalizados (ADK): um padrão que usa uma classe de agente personalizada para se conectar diretamente à API e transmitir blocos de dados de volta ao usuário. Aplicativos voltados ao usuário em que a baixa latência de resposta é uma prioridade ou pipelines de vários agentes em que a recuperação de dados alimenta agentes downstream.
  • Oferece feedback de streaming em tempo real.
  • Acessa todos os tipos de resposta, como gráficos, tabelas e SQL.
  • Combinável com outros agentes do ADK usando o estado da sessão.
  • Exige mais esforço de desenvolvimento para criar uma classe de agente ADK personalizada.
  • Exige que você gerencie a conexão de streaming e a análise de resposta diretamente.
Protocolo de Contexto de Modelo (MCP): um padrão que usa um padrão aberto para conectar aplicativos de IA a fontes de dados e ferramentas em diferentes ambientes. Organizações que exigem interoperabilidade de ferramentas em vários clientes de IA e IDEs ou equipes que precisam que as mesmas ferramentas de dados sejam acessíveis pelo framework do ADK, IDEs e aplicativos personalizados.
  • Usa um padrão de ferramenta universal que funciona com qualquer cliente compatível com o MCP.
  • Desvincula a implementação da ferramenta dos aplicativos consumidores.
  • Oferece opções de servidor gerenciado, como o servidor MCP do Google Cloud .
  • Requer uma camada de infraestrutura extra para o servidor da caixa de ferramentas.
  • Oferece uma integração mais flexível do que os conjuntos de ferramentas do ADK.
  • Depende do ecossistema em evolução da MCP Toolbox.
  • Opera em um modo sem estado que exige que você gerencie o estado de vários turnos externamente.
Agent-to-Agent (A2A): um padrão que usa o protocolo A2A, um padrão aberto que permite que agentes especializados em diferentes sistemas colaborem de forma segura sem precisar de código de integração personalizado. Ambientes corporativos altamente distribuídos em que um agente de roteamento central precisa delegar tarefas a agentes de dados que operam em diferentes sistemas ou redes.
  • Reduz a necessidade de código de integração personalizado entre frameworks diferentes.
  • Garante uma interoperabilidade multiplataforma perfeita.
  • Oferece descoberta de recursos segura e padronizada.
  • Introduz uma pequena latência de rede em comparação com os subagentes internos.
  • Exige que você defina as configurações do servidor A2A.

Integração direta com a API

A integração direta com a API oferece controle granular sobre a lógica e a arquitetura do aplicativo, mas exige que você crie a infraestrutura de suporte. Com essa abordagem, você é responsável por tarefas como autenticação, gerenciamento de conversas, análise de respostas e implantação.

Esta seção abrange os seguintes tópicos:

Integração de agente único

Com uma integração de agente único, seu back-end chama diretamente a API Análise conversacional usando REST ou uma biblioteca de cliente e transmite a consulta e o contexto do usuário. Esse padrão é adequado para aplicativos de baixa complexidade, como apps da Web, ferramentas de chat interno ou microsserviços, que usam um fluxo simples de texto para resposta. Também é possível usar essa abordagem para prototipagem e trabalho de prova de conceito.

Esse padrão é compatível com conversas com estado, em que o Google gerencia o histórico de conversas, e conversas sem estado, em que o aplicativo gerencia o histórico.

Para implementações de referência, consulte o guia de início rápido da API Análise conversacional ou a demonstração principal da API Análise conversacional no GitHub.

Integração de orquestrador personalizado

Com essa abordagem, você cria um agente raiz que atua como o principal ponto de entrada e coordenador do aplicativo. O agente raiz usa um modelo padrão do Gemini equipado com ferramentas por meio de chamadas de função. Quando um usuário faz uma pergunta relacionada a dados, o agente raiz emite uma chamada de ferramenta para a API Análise conversacional, recebe o resultado e pode continuar o raciocínio ou chamar outras ferramentas downstream.

A chamada de função envolve as seguintes etapas:

  1. Declarar: defina esquemas de ferramentas como objetos FunctionDeclaration que incluem definições de parâmetros.
  2. Invocação: o modelo retorna uma mensagem functionCall estruturada que contém o nome e os argumentos da função.
  3. Executar: o aplicativo executa a chamada de API e retorna o resultado em uma mensagem FunctionResponse.
  4. Sintetizar: o modelo do Gemini usa o resultado para gerar uma resposta final ou determinar a próxima ação.

Essa abordagem é adequada para aplicativos em que os usuários podem pedir insights de dados junto com outras tarefas. Por exemplo, um usuário pode pedir ao agente para "Mostrar as vendas e, em seguida, escrever um e-mail para a equipe de vendas". O agente raiz pode encaminhar a pergunta de dados para a API Análise conversacional e usar outras ferramentas para tarefas que não envolvem dados.

Para uma implementação de referência, consulte as páginas orquestrar ou multimodal na demonstração principal da API Análise conversacional no GitHub.

Orquestração baseada em framework (ADK)

O Kit de Desenvolvimento de Agente (ADK) é um framework que prioriza o código para criar agentes de IA que gerenciam a complexidade do roteamento multiagente, da execução de ferramentas e do gerenciamento de estado. O framework do ADK é o mesmo que alimenta o Gemini Enterprise.

Ao usar o ADK, é possível encadear a API Análise conversacional com outras ferramentas e agentes para realizar ações complexas.

Esta seção abrange os seguintes tópicos:

Integração baseada em esquema com BigQueryToolset

O conjunto de ferramentas BigQueryToolset no framework do ADK inclui uma ferramenta ask_data_insights pré-criada. Para usar essa ferramenta, transmita os nomes das tabelas e a pergunta do usuário para ela, que chama a API Análise conversacional usando o contexto inline.

Quando você chama a ferramenta, ela envia uma solicitação sem estado que inclui as referências de tabela do BigQuery especificadas para a API Análise conversacional. A API infere o esquema do banco de dados, gera e executa a consulta SQL e retorna uma resposta em texto. O resultado é transmitido de volta ao agente do ADK como uma resposta da ferramenta.

Esse padrão é uma maneira eficaz de adicionar Análise conversacional a um agente rapidamente. No entanto, como a chamada para a API não tem estado e não tem governança, ela gera um SQL baseado inteiramente no esquema da tabela, sem proteções semânticas. Esse padrão é mais rápido de implantar, mas é mais arriscado para a lógica de negócios de produção, em que convenções de nomenclatura, lógica de negócios ou controles de acesso são aplicados.

Integração controlada com o DataAgentToolset

O conjunto de ferramentas DataAgentToolset no framework do ADK oferece uma integração pré-criada que faz referência a um agente de dados pré-configurado pelo ID. O agente do ADK transmite a pergunta do usuário para a ferramenta ask_data_agent, que chama a API Análise conversacional com o contexto do agente de dados especificado.

É possível criar um agente de dados de maneira programática usando a API Análise conversacional ou o Catálogo de Agentes no console do Google Cloud . Um agente de dados vem equipado com os seguintes componentes:

  • Fontes de conhecimento: tabelas, visualizações ou funções definidas pelo usuário (UDFs) que o agente pode consultar.
  • Contexto estruturado: descrições de tabelas e colunas que ajudam o agente a entender os dados subjacentes.
  • Instruções: orientações adicionais para o agente interpretar e consultar as fontes de dados.
  • Consultas verificadas: consultas SQL pré-validadas que servem como exemplos para perguntas comuns.
  • Glossário: definições de termos comerciais que ajudam o agente a entender a linguagem específica do domínio.

Para um guia detalhado sobre como criar agentes usando o catálogo de agentes, consulte o codelab de análise conversacional no BigQuery.

Como o agente é definido como uma unidade governada, ele usa a mesma lógica, contexto e proteções confiáveis, independentemente de qual aplicativo ou subagente o chama.

Integração avançada de UX com subagentes personalizados

Os conjuntos de ferramentas BigQueryToolset e DataAgentToolset não retornam resultados ao usuário até que o processamento da solicitação de API seja concluído. Como o framework do ADK trata a API como uma ferramenta que bloqueia as respostas até a conclusão, as consultas mais longas podem deixar os usuários sem feedback.

Como alternativa para aplicativos em que a baixa latência de resposta é uma prioridade ou em que a recuperação de dados alimenta agentes downstream, é possível criar uma classe de agente ADK personalizada que se conecta diretamente à API Análise conversacional e transmite dados de forma assíncrona em blocos de volta para o usuário. Esse padrão é compatível com os seguintes tipos de resposta:

  • Mensagens de pensamento: o processo de raciocínio do agente de dados ao interpretar a pergunta.
  • Mensagens de progresso: atualizações de status durante a recuperação de dados para fontes de dados.
  • Geração de consultas: a consulta SQL ou do Looker gerada, que é transmitida conforme é produzida.
  • Dados: os resultados dos dados no formato JSON.
  • Visualização: especificações do gráfico Vega-Lite.
  • Resumo: a resposta final em texto.

Para ver uma lista completa dos tipos de dados retornados, consulte o tipo SystemMessage na documentação de referência da API.

Essa abordagem assíncrona garante que os usuários não precisem esperar que um processo complexo de recuperação de dados seja concluído. À medida que o agente de dados avança no processo de consulta, ele compartilha continuamente atualizações incrementais, como resumos de texto, dados brutos ou configurações de gráficos, em um espaço de trabalho temporário e compartilhado. Esses dados podem ser renderizados para o usuário em tempo real e compartilhados com subagentes especializados para realizar outras tarefas.

Para uma implementação de referência que inclui um agente raiz, um subagente de dados e um agente de visualização, consulte a demonstração de streaming do ADK no GitHub.

Integração vertical (MCP)

O Protocolo de Contexto de Modelo (MCP) é um padrão aberto que fornece uma maneira uniforme para que os aplicativos de IA se conectem a ferramentas e fontes de dados externas. O MCP padroniza a interface entre os modelos de IA e as ferramentas que eles usam.

Esta seção abrange os seguintes tópicos:

Servidor MCP remoto da API Análise conversacional

A API Análise conversacional fornece um servidor MCP remoto em https://geminidataanalytics.googleapis.com/mcp, com tecnologia do servidor MCP gerenciado pelo Google. Esse gateway oferece uma interface HTTP e de eventos enviados pelo servidor (SSE) unificada e segura que permite que agentes raiz em plataformas de IA de terceiros e plataformas gerenciadas pelo Google (como o Gemini Enterprise) descubram e se comuniquem com agentes de dados especializados no Google Cloud.

Visão geral da comunicação do agente raiz

A comunicação entre um agente raiz externo ou gerenciado pelo Google e a API Análise conversacional envolve três papéis distintos:

  1. Os operadores de dados criam e configuram agentes de dados com escopo em plataformas de análise conversacional, escrevem descrições claras das fontes de dados que cada agente pode acessar e das perguntas que ele pode responder, além de compartilhar esses agentes com usuários de negócios.
  2. Os administradores da plataforma registram uma conexão MCP personalizada na plataforma de agentes que aponta para o endpoint https://geminidataanalytics.googleapis.com/mcp. Os administradores configuram as credenciais do cliente OAuth 2.0 (ID do cliente e chave secreta do cliente) usando o endpoint de autorização do Google (https://accounts.google.com/o/oauth2/v2/auth), o endpoint de token (https://oauth2.googleapis.com/token) e os escopos de autorização necessários (https://www.googleapis.com/auth/geminidataanalytics e https://www.googleapis.com/auth/bigquery.readonly).
  3. Os usuários corporativos fazem perguntas em linguagem natural na plataforma de agentes. Em vez de consultar diretamente os bancos de dados brutos, o agente raiz da plataforma (o LLM orquestrador) se comunica com o servidor MCP remoto da API Análise conversacional para descobrir agentes de dados relevantes, encaminhar a pergunta do usuário ao agente de dados com escopo apropriado e retornar a resposta sintetizada.
Propagação de identidade

Para manter a governança de dados corporativos quando as solicitações vêm de agentes raiz externos ou de terceiros, o servidor MCP remoto aplica a propagação de identidade de ponta a ponta:

  • Autenticação delegada pelo usuário: quando um usuário empresarial interage com o agente raiz, a plataforma agêntica autentica o usuário por um fluxo do OAuth 2.0 de três etapas e inclui o token de acesso OAuth delegado pelo usuário nos cabeçalhos HTTP das solicitações enviadas ao gateway do MCP.
  • Encaminhamento de credenciais de usuário final (EUC, na sigla em inglês): o servidor MCP remoto valida o token e propaga as credenciais do usuário final pela camada da API Análise conversacional para os mecanismos de dados subjacentes, como BigQuery, Spanner, AlloyDB e Cloud SQL.
  • Acesso controlado aos dados: como as consultas são executadas usando a identidade do usuário autenticado, em vez de uma conta de serviço compartilhada, as fontes de dados subjacentes aplicam automaticamente as permissões do IAM, as políticas de segurança no nível da linha e da coluna e os limites de acesso controlado aos dados. Os usuários só podem descobrir agentes de dados e consultar conjuntos de dados que já têm permissão para acessar.
  • Modelo de duas identidades do Looker: para o BigQuery e bancos de dados operacionais, as consultas são executadas com as credenciais do OAuth do Google encaminhadas do usuário individual. Para agentes de dados do Looker, a autenticação usa um modelo de duas identidades: o token OAuth do Google do usuário autoriza o acesso ao agente de dados no Google IAM, mas a consulta é executada no Looker usando as credenciais fornecidas para um usuário da API Looker (transmitidas no bloco de credenciais da ferramenta de chat). O acesso ao modelo do Looker, as permissões e as regras no nível da linha refletem esse usuário da API configurado, e não a identidade do Looker do usuário final individual.
Como os agentes raiz acessam os métodos de API

Quando um cliente do MCP se conecta ao https://geminidataanalytics.googleapis.com/mcp, ele chama o método padrão tools/list do MCP para importar dinamicamente os esquemas de ferramentas expostos pela API Análise conversacional. O agente raiz interage com a API de Análise conversacional invocando essas ferramentas e recursos do MCP, que são mapeados diretamente para os métodos da API REST:

Ferramenta ou recurso do MCP Método mapeado da API Análise conversacional Como o agente raiz o usa
list_data_agents projects.locations.dataAgents.list

Descobre os agentes de dados disponíveis. O agente raiz transmite o PROJECT_ID (e o LOCATION) de destino e recebe uma lista de agentes de dados ativos que o usuário tem autorização para acessar, incluindo o ID e a descrição de cada agente. O agente raiz avalia essas descrições para determinar qual agente de dados pode responder à pergunta do usuário.

Dica: inclua o PROJECT_ID de destino nas instruções personalizadas do sistema do agente raiz para que ele não peça aos usuários corporativos que forneçam um ID do projeto.

get_data_agent

(ou o recurso MCP gda://agents/AGENT_ID)

 projects.locations.dataAgents.get

Inspeciona os metadados e o contexto de um agente de dados específico. O agente raiz transmite o AGENT_ID de destino para recuperar detalhes de configuração, como tabelas do BigQuery conectadas, instruções do sistema, glossários ou consultas verificadas, quando as descrições do agente não são suficientes para encaminhar um comando complexo.
chat projects.locations.chat

Atua como o proxy de execução para consultas de conversação. Para consultar um agente de dados descoberto, o agente raiz transmite data_agent_context, que contém o nome completo do recurso do agente (projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID) e a mensagem em linguagem natural do usuário em messages. Para consultas ad hoc sem estado, o agente raiz pode transmitir inline_context. A ferramenta retorna respostas em linguagem natural, consultas SQL geradas, linhas de resultado, especificações de gráficos Vega-Lite e o raciocínio do agente.

MCP Toolbox for Databases

Também é possível acessar a API de Análise conversacional pelo servidor de código aberto MCP Toolbox for Databases. Esse servidor oferece ferramentas pré-criadas compatíveis com o MCP que expõem o método chat na API Análise conversacional:

O MCP é uma camada de interoperabilidade que expõe recursos de análise como ferramentas para clientes compatíveis com o MCP, em vez de um modelo de execução separado da API Análise conversacional.

Padrões de implementação do MCP para arquiteturas independentes e do ADK

É possível implementar o MCP usando os seguintes padrões:

Padrão Detalhes
MCP independente (sem ADK)

Use o servidor do MCP Toolbox for Databases como um servidor independente para se conectar a qualquer cliente compatível com o MCP. Esse padrão é usado com frequência para as seguintes tarefas:

  • Integração com IDE: conecte um IDE, como Antigravity, Cursor ou VS Code, ao servidor para consultar dados de forma conversacional em um editor.
  • Cliente MCP personalizado: crie um aplicativo que use o servidor para fornecer uma interface de ferramenta uniforme em vários provedores de IA.
  • CLI do Gemini: use a CLI como um cliente MCP para conversas de dados baseadas em terminal.
MCP no ADK

O framework do ADK oferece os seguintes mecanismos para integrar servidores MCP aos Agentic Workflows:

  • ToolboxToolset: uma variante especializada para o servidor MCP Toolbox for Databases que aceita vários métodos de autenticação.
  • McpToolset: conecta um agente do ADK a qualquer servidor MCP usando conexões locais ou remotas. Descobre automaticamente as ferramentas do servidor e as expõe ao agente.

Também é possível criar servidores MCP usando o framework FastMCP para expor ferramentas criadas com o framework do ADK a qualquer cliente compatível com o MCP. Essa abordagem disponibiliza seus agentes do ADK como ferramentas em outros ecossistemas.

Escolha um padrão de integração que atenda aos requisitos de arquitetura específicos do seu aplicativo:

  • O uso de conjuntos de ferramentas integrados do Kit de Desenvolvimento de Agente (ADK), como BigQueryToolset ou DataAgentToolset, oferece uma integração mais estreita sem dependências de servidores externos. Essa abordagem é ideal para sistemas que existem inteiramente dentro do framework do ADK.
  • O uso das ferramentas na MCP Toolbox oferece interoperabilidade entre clientes compatíveis com o MCP. Essa abordagem é ideal para ferramentas de dados que precisam atender a vários aplicativos de consumo ou IDEs de terceiros.

Orquestração horizontal (A2A)

O protocolo Agent-to-Agent (A2A) é um padrão aberto que permite que agentes especializados em diferentes sistemas se comuniquem e colaborem de forma segura, sem a necessidade de código de integração personalizado.

À medida que os sistemas crescem, as organizações costumam implantar vários agentes especializados, criados em diferentes frameworks ou infraestruturas em nuvem. O A2A estabelece um nível de mensagens universal para esses agentes autônomos. Em vez de usar APIs personalizadas, cada agente publica um card de agente, que é um perfil detectável que detalha os recursos do agente, os formatos de dados compatíveis e os requisitos de segurança.

Quando um orquestrador central ou agente de mesmo nível precisa de dados analíticos, ele delega a tarefa de forma segura a um agente de dados por meio de mensagens A2A estruturadas. O agente de dados processa a solicitação de forma autônoma e retorna as descobertas, o que separa a lógica de execução do solicitante.

Para saber como descobrir cards de agentes, enviar mensagens e transmitir artefatos estruturados usando o protocolo A2A, consulte Orquestrar agentes de dados com o A2A.

Escolher um padrão de integração

Use a tabela a seguir para comparar a complexidade, a governança e os recursos de cada padrão de integração.

Os níveis de complexidade são definidos da seguinte maneira:

  • Baixo: padrões que exigem o mínimo de código personalizado e dependem de interfaces do usuário ou ferramentas pré-criadas.
  • Médio: padrões que exigem desenvolvimento de front-end personalizado e integração de API ou SDK, mas evitam uma infraestrutura complexa de orquestração de back-end.
  • Alta: padrões que exigem desenvolvimento de aplicativos full-stack, gerenciamento de estado de conversas, várias camadas de autenticação ou infraestrutura de orquestrador intermediária.
  • Variável: padrões em que a complexidade depende do método de integração escolhido.
Padrão de integração Complexidade Personalização Agent Governance Controle de acesso Multiagente Streaming Portabilidade
Incorporação de iframe do Looker Baixo Baixo Gerenciado pelo Looker Looker Não Integrado Somente Looker
API Looker e SDKs Média Alta Gerenciado pelo Looker Looker Não Integrado Somente Looker
API de Análise conversacional com fonte do Looker Varia Alta Gerenciadas pela API Looker e IAM Sim Sim Qualquer Google Cloud plataforma
Agente único (API direta) Média Alta Gerenciadas pela API IAM Não Sim (compatível) Qualquer Google Cloud plataforma
Orquestrador personalizado Alta Muito alto Gerenciadas pela API IAM Manual Manual Qualquer Google Cloud plataforma
Orientado por esquemas com BigQueryToolset (ADK) Baixo Média Nenhum (inferência de esquema) IAM Sim (ADK) Não (bloqueio) Ecossistema do ADK
Regido com DataAgentToolset (ADK) Baixo Média Gerenciadas pela API IAM Sim (ADK) Não (bloqueio) Ecossistema do ADK
Subagente de streaming personalizado (ADK) Alta Muito alto Gerenciadas pela API IAM Sim (ADK) Sim (personalizado) Ecossistema do ADK
MCP independente Média Média Nenhum (inferência de esquema) IAM Não Não Qualquer cliente MCP
MCP no ADK Média Alta Nenhum (inferência de esquema) IAM Sim (ADK) Não Clientes ADK e MCP
Protocolo A2A Alta Alta Dependente do framework IAM Sim Sim Multiplataforma

A seguir