Este documento descreve os principais conceitos para usar a API Análises de conversação (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 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.
Como os agentes de dados funcionam
Os agentes de dados da API Análises de conversação usam o contexto (informações comerciais e dados) 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 e no Looker Studio para recursos de chat. Ele também pode consultar dados de 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 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 fornecem a resposta final à consulta.
Workflows para criar e usar agentes
A API Análises de conversação é 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 "raciocínio de repetição" 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 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:
- 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 Análises de conversação.
- Saiba como proteger seus agentes de dados e conversas usando a CMEK.
- Saiba como renderizar respostas de agentes para fontes de dados do Looker.