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 responder a perguntas sobre seus dados estruturados. Este documento descreve como os agentes funcionam, fluxos de trabalho típicos, modos de conversa, papéis do Identity and Access Management (IAM) e como projetar 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 nos 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 mostrado 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 de qualquer contexto adicional que você forneça.
- 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.
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 consumidores 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 consumidor de agente:
As seções a seguir descrevem os fluxos de trabalho para criadores e consumidores de agentes em mais detalhes.
O fluxo de trabalho de criação de agentes
O criador do 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 permitir que o agente entenda e responda às perguntas dos usuários de forma eficaz.
- Compartilhar o agente: depois que o agente é configurado, 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 consumidor do agente
O consumidor do agente geralmente é um usuário comercial que precisa receber 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 em várias etapas.
- O agente "pensa": 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 "loop de inferência" para determinar a melhor maneira de responder à 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 de conversas. Cada interação é tratada de forma independente. Esse modo é útil para aplicativos em que não é necessário manter o contexto em várias interações.
- Modo com estado: o agente retém o contexto e o histórico de conversas, permitindo interações mais contextualizadas. Esse modo é útil para aplicativos em que é necessário manter o contexto em vários turnos. Recomendamos usar o modo com estado para ter mais precisão e respostas personalizadas.
Escolha um modo de conversa com base nos requisitos do seu aplicativo para histórico de conversas 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. A tabela a seguir descreve os principais papéis do IAM para a API Conversational Analytics:
| Papel | Escopo típico | O que a função permite | Quem pode usar essa função |
|---|---|---|---|
Criador do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentCreator) |
Projeto | Criar agentes e herdar permissões de proprietário neles. | Qualquer analista de dados |
Proprietário do 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 do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor) |
Agente, Projeto | Atualiza a configuração ou o contexto de um agente. | Analista de dados júnior |
Usuário do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser) |
Agente, Projeto | Converse com um representante. | Profissional de marketing, proprietário da loja |
Leitor do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) |
Projeto, agente | Listar agentes e receber os detalhes deles. | Qualquer usuário |
Usuário sem estado do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentStatelessUser) |
Projeto | Converse com um agente sem armazenamento de contexto ou histórico de conversas. | Qualquer usuário |
Sistemas com vários agentes
É possível projetar 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 marketing. Com essa abordagem, é possível criar um sistema que lida com uma ampla variedade de 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 adequado.
- Um agente especializado recebe a solicitação delegada, se conecta às fontes de dados relevantes, usa as ferramentas para gerar as consultas e os gráficos SQL 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. Aqui está um gráfico."
A seguir
Depois de entender os conceitos básicos da API Conversational Analytics, saiba como implementar esses 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 mais sobre como orientar o comportamento de um agente com contexto criado.
- Entenda o controle de acesso com o IAM para a API Conversational Analytics.