Este documento descreve os principais conceitos para usar a API Conversational Analytics (acessada por geminidataanalytics.googleapis.com ou endpoints regionais), que permite criar e interagir com agentes de dados que usam linguagem natural para tirar dúvidas sobre dados estruturados. Este documento descreve a arquitetura do agente, os fluxos de trabalho comuns, os modos de conversa, os papéis do Identity and Access Management (IAM) e o design de sistemas multiagentes.
Para revisar as abordagens arquitetônicas disponíveis para a API Conversational Analytics e como a API gerencia o contexto da conversa, consulte Padrões de integração e gerenciamento de estado.
Como os agentes de dados funcionam
Os agentes de dados da API Conversational Analytics usam o contexto (informações e dados comerciais) que você fornece e ferramentas (como SQL e Python) para interpretar perguntas em linguagem natural e gerar respostas com base em seus dados estruturados.
O diagrama a seguir ilustra as etapas do fluxo de trabalho de um agente quando um usuário faz uma pergunta:
Como no diagrama, quando um usuário faz uma pergunta, o agente processa a solicitação nas seguintes etapas:
- Entrada: o usuário envia uma pergunta em linguagem natural, além de qualquer contexto adicional fornecido anteriormente.
- Fontes de dados: o agente se conecta aos seus dados no Looker, no BigQuery (incluindo tabelas ou um gráfico) e no Data Studio para recursos de chat. Ele também pode consultar dados dos bancos de dados do AlloyDB, do GoogleSQL para Spanner, do Cloud SQL para MySQL e do Cloud SQL para PostgreSQL usando o método
QueryData. - Mecanismo de raciocínio: o núcleo do agente processa a pergunta do usuário usando as ferramentas disponíveis para gerar uma resposta.
- Saída: o agente retorna um fluxo de mensagens, que podem conter texto, dados ou gráficos. Essas mensagens podem incluir citações que vinculam partes específicas do texto de resposta às fontes de contexto fornecidas, como termos de glossário ou consultas de exemplo. Para algumas fontes de dados, as mensagens de texto fornecem insights detalhados sobre o raciocínio do agente, informam o progresso de uma ação ou fornecem a resposta final à consulta.
Workflows para criar e usar agentes
A API Conversational Analytics é compatível com fluxos de trabalho para criadores de agentes (que criam e configuram agentes) e para usuários de agentes (que interagem com agentes existentes).
O diagrama a seguir ilustra o processo completo, desde a configuração inicial por um criador de agente até as interações finais com um usuário de agente:
As seções a seguir descrevem em detalhes os fluxos de trabalho para criadores e usuários de agentes.
O fluxo de trabalho de criação de um agente
O criador de agente é responsável por configurar os agentes. Esse fluxo de trabalho envolve as seguintes etapas:
- Criar agente: o criador começa criando um novo agente e fornecendo o contexto necessário, incluindo instruções do sistema e conexões com fontes de dados. Essa etapa é crucial para que o agente entenda e responda as perguntas dos usuários de forma eficaz.
- Compartilhar o agente: após a configuração do agente, o criador o compartilha com outros usuários e define os controles de acesso baseados em papéis adequados para gerenciar permissões.
O fluxo de trabalho do usuário do agente
Geralmente, o usuário do agente é um usuário comercial que precisa de respostas de um agente configurado. Esse fluxo de trabalho envolve as seguintes etapas:
- Encontrar um agente: o usuário começa encontrando um agente que foi compartilhado com ele.
- Fazer uma pergunta: o usuário faz uma pergunta em linguagem natural. Essa pergunta pode ser uma única consulta ou parte de uma conversa dividida em vários turnos.
- O agente "raciocina": o mecanismo de raciocínio do agente processa a pergunta. O mecanismo de inferência usa o conhecimento predefinido do agente e as ferramentas disponíveis (como SQL, Python e gráficos) em um "ciclo de raciocínio" para determinar a melhor forma de responder a pergunta.
- O agente responde: o agente retorna um fluxo de mensagens, que podem conter texto, dados ou gráficos. Para algumas fontes de dados, as mensagens de texto fornecem insights detalhados sobre o raciocínio do agente, informam o progresso de uma ação ou fornecem a resposta final à consulta.
Modos de conversa
Os agentes da API Conversational Analytics são compatíveis com diferentes modos de conversa que determinam como um agente lida com o histórico de conversas e a persistência do contexto em todas as interações. Os seguintes modos de conversa estão disponíveis:
- Modo sem estado: o agente não armazena o histórico da conversa. Cada interação é tratada de forma independente. Esse modo é indicado para situações em que não é necessário manter o contexto em turnos.
- Modo com estado: o agente retém o contexto e o histórico da conversa, o que torna as interações mais contextualizadas. Esse modo é indicado para situações em que é necessário manter o contexto em vários turnos. É recomendado para maior precisão e respostas personalizadas.
Escolha um modo de conversa com base no que a situação exige em termos de histórico de conversa e persistência de contexto.
Papéis IAM
Os papéis do IAM controlam quem pode criar, gerenciar, compartilhar e interagir com os agentes da API Conversational Analytics. Na tabela a seguir, você encontra uma descrição dos principais papéis do IAM para a API Conversational Analytics:
| Papel | Escopo típico | O que o papel permite | Quem pode usar o papel |
|---|---|---|---|
Criador de agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentCreator) |
Projeto | Criar agentes e herdar permissões de proprietário neles. | Analistas de dados |
Proprietário de agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentOwner) |
Projeto, agente | Editar, compartilhar ou excluir agentes com outros usuários. | Analista de dados sênior |
Editor de agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor) |
Agente, projeto | Atualizar a configuração ou o contexto de um agente. | Analista de dados júnior |
Usuário de agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser) |
Agente, projeto | Conversar com um agente. | Profissional de marketing, proprietário do repositório |
Leitor de agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) |
Projeto, agente | Listar agentes e acessar os detalhes deles. Não é possível editar o agente. | Qualquer usuário |
Usuário de consulta de dados do Gemini Data Analytics (roles/geminidataanalytics.queryDataUser) |
Projeto | Consultar dados de fontes de banco de dados compatíveis usando o método QueryData. |
Desenvolvedor de aplicativos, analista de dados |
Usuário de chat sem estado do Gemini Data Analytics (roles/geminidataanalytics.dataAgentStatelessUser) |
Projeto | Conversar com um representante sem armazenamento de contexto ou histórico de conversa. | Qualquer usuário |
Sistemas com vários agentes
É possível desenvolver sistemas complexos integrando vários agentes da API Conversational Analytics. Um padrão comum é usar um agente "orquestrador" principal que delega tarefas a um ou mais agentes especializados que lidam com domínios específicos, como dados de vendas ou de marketing. Dessa forma, é possível criar um sistema que lida com diversas perguntas combinando os pontos fortes de vários agentes.
O diagrama a seguir ilustra esse padrão multiagente e mostra como um agente principal pode delegar uma pergunta de dados a um agente especializado do Conversational Analytics:
O fluxo de trabalho típico de um sistema multiagente envolve as seguintes etapas:
- Um usuário comercial ou analista de dados faz uma pergunta em linguagem natural, como "Mostre as três principais lojas por receita".
- Um agente "orquestrador" principal delega a solicitação ao agente especializado competente.
- O agente especializado recebe a solicitação delegada, se conecta às fontes de dados pertinentes, usa as ferramentas para gerar as consultas SQL e os gráficos necessários e gera uma resposta.
- A resposta do agente especializado é enviada ao usuário, como "As lojas 4, 9 e 3 têm a maior receita. Confira o gráfico."
A seguir
Depois de entender os conceitos básicos da API Conversational Analytics, saiba como implementar estes recursos:
- Compare os padrões de integração arquitetônica para determinar a melhor abordagem para seu aplicativo.
- Entenda o gerenciamento de estado para agentes de dados e como a API gerencia o contexto da conversa.
- Saiba como se autenticar e se conectar a uma fonte de dados.
- Saiba como criar e configurar um agente com HTTP.
- Saiba como criar e configurar um agente com Python.
- Saiba como orientar o comportamento de um agente com contexto criado.
- Entenda o controle de acesso com o IAM para a API Conversational Analytics.
- Saiba como proteger seus agentes de dados e conversas usando a CMEK.
- Saiba como renderizar respostas de agentes para fontes de dados do Looker.