API Conversational Analytics: crie agentes de dados e converse com seus dados

Este produto ou recurso está sujeitos aos "Termos das Soluções Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os produtos e recursos pré-GA estão disponíveis no estado em que se encontram e podem ter suporte limitado. Você encontra mais detalhes nas descrições das fases de lançamento.

Importante: a API Data QnA foi descontinuada. Se você estiver migrando da API Data QnA, consulte o guia de migração para ter uma visão geral das principais diferenças e das etapas de migração necessárias.

Os desenvolvedores podem usar a API Conversational Analytics, acessada pelo geminidataanalytics.googleapis.com, para criar uma interface de chat ou um agente de dados com tecnologia de IA que use linguagem natural para responder a perguntas sobre dados estruturados no BigQuery, no Looker e no Looker Studio. Com a API Conversational Analytics, você fornece ao seu agente de dados informações e dados comerciais (contexto), além de acesso a ferramentas como SQL, Python e bibliotecas de visualização. Essas respostas do agente são apresentadas ao usuário e podem ser registradas pelo aplicativo cliente, criando uma experiência de chat de dados simples e auditável.

Saiba como e quando o Gemini para Google Cloud usa seus dados.

Como uma tecnologia em estágio inicial, os produtos do Gemini para Google Cloud podem gerar uma saída plausível, mas que é factualmente incorreta. Recomendamos que você valide todas as saídas dos produtos do Gemini para Google Cloud antes de usá-las. Para mais informações, consulte Gemini para Google Cloud e IA responsável.

Observação: as ofertas de pré-lançamento (1) são destinadas ao uso apenas em ambientes de teste e não devem ser usadas em um ambiente de produção ou para processar dados pessoais ou outros dados sujeitos a requisitos de conformidade legal ou regulamentar e (2) estão sujeitas aos Termos das Ofertas Pré-GA dos Termos Específicos do Serviço e ao Adendo de Consentimento do Programa Trusted Tester do Gemini para Google Cloud .

Começar a usar a API Conversational Analytics

Para começar a usar a API Conversational Analytics, primeiro consulte a documentação de arquitetura e conceitos principais para entender como os agentes processam solicitações, os fluxos de trabalho para criadores e usuários de agentes, os modos de conversa e os papéis do Identity and Access Management (IAM). Em seguida, para começar a criar agentes de dados, escolha entre uma experiência guiada com inícios rápidos, codelabs, notebooks, o Kit de Desenvolvimento de Agentes (ADK) e a MCP Toolbox ou uma abordagem independente seguindo as etapas em Configuração e pré-requisitos.

Guias de início rápido

Use o app de início rápido do Streamlit para integrar com a API Conversational Analytics em um ambiente de teste local.

Codelabs

Siga um tutorial detalhado para aprender a usar o SDK do Python com dados do BigQuery no codelab da API Conversational Analytics.

Notebooks

Use os seguintes notebooks do Colaboratory da API Conversational Analytics para experiências guiadas que vão ajudar você a começar a usar a API:

• Notebook do Colaboratory HTTP: oferece um guia interativo e explicativo sobre como configurar seu ambiente, criar um agente de dados e fazer chamadas de API usando solicitações HTTP.
• Notebook do Colaboratory do SDK do Python: oferece um guia interativo e explicativo sobre como configurar seu ambiente, criar um agente de dados e fazer chamadas de API usando o SDK do Python.

Kit de Desenvolvimento de Agente (ADK) e MCP Toolbox

Saiba como usar a função ask_data_insights no Kit de desenvolvimento de agentes (ADK) para responder a perguntas sobre seus dados em linguagem natural.

Confira as demonstrações e ferramentas da API Conversational Analytics que mostram os recursos da API e oferecem padrões de integração práticos.

Configuração e pré-requisitos

Antes de usar a API ou os exemplos, siga estas etapas:

• Ativar a API Conversational Analytics: descreve os pré-requisitos para ativar a API Conversational Analytics.
• Controle de acesso da API Conversational Analytics com o IAM: descreve como usar o Identity and Access Management para compartilhar e gerenciar o acesso a agentes de dados.
• Autenticar e se conectar a uma fonte de dados com a API Conversational Analytics: fornece instruções para autenticar a API e configurar conexões com seus dados do BigQuery, do Looker e do Looker Studio.

Criar e interagir com um agente de dados

Depois de concluir as etapas anteriores, use a API Conversational Analytics para criar e interagir com um agente de dados seguindo estas etapas:

• Criar um agente de dados usando HTTP: oferece um exemplo completo de como criar e interagir com um agente de dados usando solicitações HTTP diretas com Python.
• Criar um agente de dados usando o SDK do Python: oferece um exemplo completo de como criar e interagir com um agente de dados usando o SDK do Python.
• Orientar o comportamento do agente com contexto criado: saiba como fornecer contexto criado para orientar o comportamento do agente e melhorar a precisão da resposta. Você também pode conferir exemplos de contexto criado com fontes de dados do BigQuery e com fontes de dados do Looker.
• Renderizar uma resposta do agente da API Conversational Analytics como uma visualização: fornece um exemplo de processamento de especificações de gráficos de respostas da API e renderização delas como visualizações usando o SDK do Python e a biblioteca Vega-Altair.

Práticas recomendadas

Consulte os seguintes guias para saber mais sobre as práticas recomendadas para usar a API Conversational Analytics:

• Gerenciar os custos do BigQuery para os agentes: saiba como monitorar e gerenciar os custos do BigQuery para seus agentes da API Conversational Analytics definindo limites de gastos no nível do projeto, do usuário e da consulta.
• Faça perguntas eficazes: aprenda a criar perguntas eficazes para seus agentes e aproveitar ao máximo a API Conversational Analytics.
• Resolver erros da API Conversational Analytics: resolver erros comuns da API Conversational Analytics.
• Limitações conhecidas: fornece informações detalhadas sobre as limitações conhecidas da API Conversational Analytics, incluindo limitações de consultas, dados, visualizações e perguntas.

Principais operações da API

A API fornece os seguintes endpoints principais para gerenciar agentes de dados e conversas:

Operação	Método HTTP	Endpoint	Descrição
Criar um agente	POST	/v1beta/projects/*/locations/*/dataAgents	Cria um novo agente de dados.
Obter um agente	GET	/v1beta/projects/*/locations/*/dataAgents/*	Recupera detalhes de um agente de dados específico.
Acessar a política do Identity and Access Management	POST	/v1beta/projects/*/locations/*/dataAgents/*:getIamPolicy	Recebe as permissões do Identity and Access Management atribuídas a cada usuário para um agente de dados específico. Usuários com o papel de Proprietário do agente de dados podem chamar esse endpoint para conferir a política do Identity and Access Management do agente de dados antes de usar o endpoint setIAMpolicy para compartilhar um agente de dados com outros usuários.
Definir a política do Identity and Access Management	POST	/v1beta/projects/*/locations/*/dataAgents/*:setIamPolicy	Define a política do Identity and Access Management para um agente de dados específico. Usuários com o papel de Proprietário do agente de dados precisam chamar esse endpoint para compartilhar um agente de dados com outros usuários, o que atualiza as permissões do Identity and Access Management desses usuários.
Atualizar um agente	PATCH	/v1beta/projects/*/locations/*/dataAgents/*	Modifica um agente de dados.
Listar agentes	GET	/v1beta/projects/*/locations/*/dataAgents	Lista os agentes de dados disponíveis em um projeto.
Listar agentes acessíveis	GET	/v1beta/projects/*/locations/*/dataAgents:listaccessible	Lista os agentes de dados acessíveis em um projeto. Um agente de dados é considerado acessível se o usuário que invoca essa API tiver a permissão get no agente. Use o campo creator_filter para gerenciar quais agentes esse método retorna: NONE (padrão): retorna todos os agentes de dados acessíveis ao usuário, independente de quem os criou. CREATOR_ONLY: retorna apenas os agentes de dados acessíveis e criados pelo usuário. NOT_CREATOR_ONLY: retorna apenas os agentes de dados acessíveis ao usuário e criados por outras pessoas.
Excluir um agente	DELETE	/v1beta/projects/*/locations/*/dataAgents/*	Remove um agente de dados.
Criar uma conversa	POST	/v1beta/projects/*/locations/*/conversations	Inicia uma nova conversa persistente.
Conversar usando uma referência de conversa	POST	/v1beta/projects/*/locations/*:chat	Continua uma conversa com estado enviando uma mensagem de chat que faz referência a uma conversa e ao contexto do agente associado. Para conversas com várias interações, o Google Cloud armazena e gerencia o histórico da conversa.
Usar uma referência de agente de dados para conversar	POST	/v1beta/projects/*/locations/*:chat	Envia uma mensagem de chat sem estado que faz referência a um agente de dados salvo para contexto. Para conversas com várias interações, o aplicativo precisa gerenciar e fornecer o histórico da conversa com cada solicitação.
Conversar usando contexto inline	POST	/v1beta/projects/*/locations/*:chat	Envia uma mensagem de chat sem estado fornecendo todo o contexto diretamente na solicitação, sem usar um agente de dados salvo. Para conversas com várias interações, o aplicativo precisa gerenciar e fornecer o histórico da conversa com cada solicitação.
Receber uma conversa	GET	/v1beta/projects/*/locations/*/conversations/*	Recupera detalhes de uma conversa específica.
Listar conversas	GET	/v1beta/projects/*/locations/*/conversations	Lista as conversas em um projeto específico.
Listar mensagens em uma conversa	GET	/v1beta/projects/*/locations/*/conversations/*/messages	Lista as mensagens em uma conversa específica.
Excluir uma conversa	DELETE	/v1beta/projects/*/locations/*/conversations/*	Exclui uma conversa específica. É necessário ter o papel de Administrador de tópicos do Identity and Access Management ou pelo menos a permissão cloudaicompanion.topics.delete do Identity and Access Management para chamar esse endpoint.

Enviar feedback

Use os links a seguir para registrar um bug ou solicitar um recurso.

• Enviar um relatório de bug
• Enviar uma solicitação de atributo

Outros recursos

A referência da API REST do Conversational Analytics oferece descrições detalhadas de métodos, endpoints e definições de tipo para estruturas de solicitação e resposta.