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

Este produto ou recurso está sujeito 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 responda a perguntas sobre dados estruturados no BigQuery, no Looker e no Looker Studio usando linguagem natural. 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 os notebooks do Colaboratory ou uma abordagem independente seguindo as etapas em Configuração e pré-requisitos.

Notebooks interativos do Colaboratory

Para um guia interativo e explicativo sobre como configurar seu ambiente, criar um agente de dados e fazer chamadas de API, consulte os seguintes notebooks do Colaboratory:

• Notebook do Colaboratory HTTP da API Conversational Analytics
• Notebook do Colaboratory do SDK da API Conversational Analytics

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.
• Conceder papéis e permissões do IAM da API Conversational Analytics: descreve os papéis predefinidos do IAM para 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.
• Escreva instruções eficazes para o sistema: aprenda a estruturar o conteúdo YAML para o parâmetro system_instruction e orientar o comportamento do agente, além de melhorar a precisão da resposta. Além disso, confira exemplos de instruções do sistema nas fontes de dados do BigQuery e nas 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

• 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.

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.
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

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

• Documentação de referência da API Conversational Analytics: oferece descrições detalhadas de métodos, endpoints e definições de tipo para estruturas de solicitação e resposta.
• Resolver problemas de erros da API Conversation Analytics: resolver problemas comuns da API Conversation Analytics.