Este documento descreve os principais conceitos para usar a API Conversational Analytics (geminidataanalytics.googleapis.com), que permite criar e interagir com agentes de dados que usam linguagem natural para tirar dúvidas sobre dados estruturados. Além disso, descreve como os agentes funcionam, os fluxos de trabalho comuns, os modos de conversa, os papéis do Identity and Access Management (IAM) e como desenvolver sistemas com vários agentes.
Como os agentes de dados funcionam
Os agentes de dados da API Conversational Analytics usam o contexto que você fornece (informações e dados comerciais) 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 do usuário: o usuário envia uma pergunta em linguagem natural, além do contexto adicional fornecido.
- Fontes de dados: o agente se conecta aos seus dados no Looker, no BigQuery e no Looker Studio para recuperar as informações necessárias.
- 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 do agente: o agente gera uma resposta, que pode incluir texto, tabelas de dados ou especificações para gráficos.
Fluxos de trabalho 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 eles).
O diagrama a seguir ilustra o processo completo, desde a configuração inicial por um criador de agente até as interações finais de 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 "raciocínio de repetição" para determinar a melhor forma de responder a pergunta.
- O agente responde: o agente retorna uma resposta, que pode incluir texto, tabelas de dados ou gráficos.
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. | Qualquer usuário |
Usuário sem estado de agente de dados 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:
- Saiba como 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.