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 responder a perguntas sobre seus dados estruturados. Este documento descreve a arquitetura do agente, os fluxos de trabalho típicos, 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 ela 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 do contexto adicional fornecido anteriormente.
- Fontes de dados: o agente se conecta aos seus dados no Looker, no BigQuery (incluindo tabelas ou um gráfico), no Data Studio ou em fontes de dados de banco de dados (AlloyDB, GoogleSQL para Spanner, Cloud SQL para MySQL e Cloud SQL para PostgreSQL em pré-lançamento no
v1beta). - 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 pode conter texto, dados ou gráficos. Essas mensagens podem incluir citações que vinculam partes específicas do texto da resposta às fontes de contexto fornecidas, como termos do glossário ou exemplos de consultas. 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 dão a resposta final à sua consulta.
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 agentes atuais).
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 raciocínio 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 pode 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 dão a resposta final à sua 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 do 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 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 | Atualizar 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 | Conversar com um agente. | Profissional de marketing, proprietário do repositório |
Leitor do 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 | Consulte 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.
A API Conversational Analytics é compatível com o protocolo Agent-to-Agent (A2A) (link em inglês), que oferece uma interface padronizada para descobrir recursos, delegar consultas e transmitir SQL estruturado e artefatos de gráficos entre agentes. Para saber como implementar fluxos de trabalho multiagentes usando o protocolo A2A, consulte Orquestrar agentes de dados com A2A.
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 da Análise Conversacional:
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 orquestrar agentes de dados com A2A.
- Compare os padrões de integração arquitetônicos 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 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 do agente para fontes de dados do Looker.