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 e notebooks ou uma abordagem independente seguindo as etapas em Configuração e pré-requisitos.

Guias de início rápido, codelabs e notebooks

Os recursos a seguir oferecem experiências guiadas para ajudar você a começar a usar a API Conversational Analytics:

• App de início rápido: use este aplicativo de início rápido do Streamlit para integrar com a API Conversational Analytics em um ambiente de teste local.
• Codelab da API Conversational Analytics: siga um tutorial detalhado para aprender a usar o SDK do Python com dados do BigQuery.
• Notebooks do Colaboratory da API Conversational Analytics:
  • 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.

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.

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

Os recursos a seguir oferecem documentação de referência, exemplos e ferramentas para ajudar você a criar aplicativos com a API Conversational Analytics:

• 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.
• Demonstrações e ferramentas do Conversational Analytics: confira demonstrações e ferramentas que mostram os recursos da API e oferecem padrões de integração práticos.
• Kit de desenvolvimento de agentes (ADK): saiba como usar a função ask_data_insights no ADK para responder a perguntas sobre seus dados em linguagem natural.