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

Visualizar

Este produto ou recurso está sujeito aos "Termos das ofertas 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. Para mais informações, consulte as descrições da fase 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 Análises de conversação, acessada pelo geminidataanalytics.googleapis.com, para criar uma interface de chat ou um agente de dados com tecnologia de IA. A API usa linguagem natural para responder a perguntas sobre dados estruturados no BigQuery, no Looker e no Looker Studio. Ela também permite consultar dados do AlloyDB, do GoogleSQL para Spanner, do Cloud SQL e do Cloud SQL para PostgreSQL usando o novo método QueryData. Com a API Análises de conversação, você fornece ao seu agente de dados informações comerciais e dados (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).

Para começar a criar agentes de dados, conclua as etapas na documentação de configuração e pré-requisitos. Para conferir tutoriais guiados, aplicativos de exemplo, SDKs e outras ferramentas de desenvolvimento, acesse Tutoriais, demonstrações e ferramentas da API Análises de conversação.

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 Análises de conversação 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 Análises de conversação: fornece instruções para autenticar a API e configurar conexões com seus dados do BigQuery, do Looker, do Looker Studio e dos bancos de dados na nuvem (AlloyDB, GoogleSQL para Spanner, Cloud SQL e Cloud SQL para PostgreSQL).
• Chaves de criptografia gerenciadas pelo cliente (CMEK): descreve como usar suas próprias chaves de criptografia no Cloud Key Management Service para proteger agentes de dados e conversas que usam fontes de dados do Looker.

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.
  Observação:não é possível criar agentes de dados usando HTTP ou o SDK do Python e renderizar visualizações para fontes de dados de banco de dados (AlloyDB, GoogleSQL para Spanner, Cloud SQL e Cloud SQL para PostgreSQL).

Práticas recomendadas

Consulte os seguintes guias para saber mais sobre as práticas recomendadas para usar a API Análises de conversação:

• 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 Análises de conversação.
• Resolver erros da API Análises de conversação: resolver erros comuns da API Análises de conversação.
• Limitações conhecidas: fornece informações detalhadas sobre as limitações conhecidas da API Análises de conversação, incluindo limitações de consultas, dados, visualizações e perguntas.
• Renderizar respostas do agente para fontes de dados do Looker: conheça as práticas recomendadas para renderizar respostas da API Análises de conversação em uma interface do usuário ao usar fontes de dados do Looker.

Referência de API e bibliotecas do cliente

• Referência REST do Gemini Data Analytics: oferece descrições detalhadas de métodos, endpoints e definições de tipo.
• SDKs e ferramentas de desenvolvimento: lista bibliotecas de cliente específicas da linguagem.

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.
Criar um agente de forma síncrona	POST	/v1beta/projects/*/locations/*/dataAgents:createSync	Cria um novo agente de dados de forma síncrona.
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.
Atualizar um agente de forma síncrona	PATCH	/v1beta/projects/*/locations/*/dataAgents/*:updateSync	Modifica um agente de dados de forma síncrona.
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.
Excluir um agente de forma síncrona	DELETE	/v1beta/projects/*/locations/*/dataAgents/*:deleteSync	Remove um agente de dados de forma síncrona.
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 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.
Consultar dados	POST	/v1beta/projects/*/locations/*/conversations:queryData	Consulta dados dos bancos de dados AlloyDB, GoogleSQL para Spanner, Cloud SQL e Cloud SQL para PostgreSQL usando linguagem natural.

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