Com os agentes de dados conversacionais, você interage com os dados do banco de dados usando uma interface de linguagem natural. Ao criar esses agentes, você ajuda os usuários a "conversar com os dados", revelando insights de bancos de dados operacionais sem precisar escrever consultas SQL complexas.
De forma geral, um agente de dados é uma combinação de persona, um conjunto de fontes de dados e acesso a um conjunto de conhecimentos comerciais essenciais para as finalidades dele.
Para desenvolvedores de aplicativos, esses agentes oferecem os seguintes benefícios:
- Alta precisão: ao usar o contexto criado, você pode alcançar alta precisão para perguntas comerciais específicas. O contexto criado é o principal fator que os criadores de agentes podem usar para melhorar a precisão. Ele inclui descrições de esquema, instruções do sistema e contexto estruturado que fornece mais informações sobre as consultas de banco de dados esperadas.
- Menos complexidade: os agentes traduzem a linguagem natural em consultas SQL, execução e até mesmo resumo ou visualização de dados.
- Flexibilidade: você pode criar agentes para testes pessoais ou publicá-los para disponibilizar a outros usuários no seu projeto ou de forma programática usando a API.
Antes de começar
-
Verifique se o faturamento está ativado para o projeto do Google Cloud .
-
Ative o Cloud SQL, a API Data Analytics com Gemini e o Gemini para Google Cloud APIs.
Funções necessárias para ativar APIs
Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (
roles/serviceusage.serviceUsageAdmin), que contém a permissãoserviceusage.services.enable. Saiba como conceder papéis.
Funções exigidas
Para trabalhar com agentes de dados, você precisa ter permissões do IAM que correspondam ao seu caso de uso. A tabela a seguir lista os papéis necessários com base em se você está criando e publicando agentes, provisionando agentes no Gemini Enterprise ou descobrindo e usando agentes. Para mais informações, consulte Papéis do IAM da API Conversational Analytics.
| Caso de uso | Funções exigidas |
|---|---|
| Criar, editar, publicar, compartilhar e excluir agentes |
|
| Provisionar agentes no Gemini Enterprise |
Para disponibilizar um agente publicado aos usuários do Gemini Enterprise, você precisa de permissões para registrar e gerenciar agentes A2A no console de administração do Gemini Enterprise. |
| Descobrir e usar agentes |
|
Ao gerenciar o acesso aos recursos de banco de dados do Cloud SQL para PostgreSQL, considere as seguintes camadas de permissões:
- Google Cloud IAM: controla o acesso à instância do banco de dados como um recurso
da nuvem. Isso inclui permissões para se conectar, gerenciar a instância e executar consultas SQL, por exemplo, usando a permissão
executeSql. - Permissões de banco de dados: controlam o acesso a objetos no banco de dados, como tabelas, visualizações e esquemas. Eles são gerenciados usando comandos SQL, como
GRANT, e sistemas de usuários e funções específicos do banco de dados.
Para o Cloud SQL para PostgreSQL, você precisa das funções apropriadas do IAM do Cloud SQL para se conectar à instância e ter autorização para enviar consultas. Para interagir com objetos como tabelas e visualizações, o usuário do banco de dados conectado precisa ter os privilégios necessários concedidos usando o sistema GRANT do Cloud SQL para PostgreSQL.
Para mais informações, consulte
Sobre usuários e papéis do PostgreSQL.
Se o agente usar uma conta de serviço, você poderá receber uma função de banco de dados atribuída. Por exemplo, consulte Gerenciar usuários com a autenticação de banco de dados do IAM.
Criar um agente de dados
As seções a seguir descrevem como criar um agente de dados. Depois de criar um agente, é possível editar as configurações dele.
Configurar noções básicas
No console Google Cloud , acesse a página do Cloud SQL para PostgreSQL.
Selecione uma instância na lista.
No menu de navegação, clique em Agentes.
Clique na guia Agentes.
Selecione um banco de dados e faça login usando sua conta do IAM.
Clique em New agent. A página Novo agente é aberta.
Na seção Editor, no campo Nome do agente, insira um nome descritivo para o agente de dados, por exemplo,
Q4 sales dataouUser activity logs.No campo Descrição do agente, insira uma descrição do agente de dados. Uma boa descrição explica o que o agente faz, quais dados ele usa e ajuda você a determinar se é o agente de dados correto para uma conversa. Por exemplo,
What are the top 10 selling products in Q2?Na seção Fontes de conhecimento, clique em Adicionar fonte. A página Adicionar dados é aberta.
Selecione as tabelas em que o agente vai se concentrar ao responder a perguntas. Para ver mais fontes de conhecimento, selecione Mostrar mais.
Clique em Adicionar. A página do novo agente é reaberta.
Personalizar descrições de tabelas e campos
Para melhorar a precisão do agente de dados de conversa, você pode fornecer metadados adicionais da tabela. Somente o agente de dados usa esses metadados, e eles não afetam a tabela de origem. É possível adicionar os seguintes metadados:
- Descrições de esquema:adicione descrições às suas tabelas e colunas para ajudar o agente a entender seus dados. Se você não adicionar descrições, o agente vai usar as descrições de esquema das suas definições de dados.
Siga estas práticas recomendadas ao adicionar descrições de tabelas e campos:
- Adicione descrições à definição de dados, e não apenas à definição do agente de dados. Isso garante que outros agentes também se beneficiem das descrições.
- Para criar um protótipo da descrição adequada e ajudar os agentes de dados a entender seus dados, adicione descrições ao agente específico. Depois de verificar se a descrição tem o impacto desejado, decida se quer adicioná-la à definição de dados.
Para configurar as descrições de tabela e campo, siga estas etapas:
- Na guia Catálogo de agentes, abra o agente que você quer personalizar.
- Clique em Editar agente.
- Em Fontes de conhecimento, encontre a tabela que você quer personalizar e clique em Personalizar.
- Insira uma descrição da tabela.
- Para editar a descrição de um campo, clique em
Editar ao lado dele. O painel Editar campo é aberto.
- No campo ID, insira uma descrição do campo.
- Para salvar a descrição do campo, clique em Atualizar.
- Para salvar a descrição e as atualizações de campo, clique em Atualizar. A página do novo agente é reaberta.
- Repita essas etapas para cada tabela que você quiser personalizar.
Adicionar rótulos aos agentes de dados
Na seção Configurações do agente, você pode criar rótulos para organizar seus recursos do Google Cloud . Rótulos são pares de chave-valor que permitem agrupar objetos relacionados entre si ou com outros recursos do Google Cloud.
- Na guia Catálogo de agentes, abra o agente a que você quer adicionar um rótulo.
- Clique em Editar agente.
- Na seção Configurações do agente, clique em Adicionar marcador. O painel Gerenciar marcadores é aberto.
- Clique em Adicionar rótulo.
- Nos campos chave e valor, insira o par de chave-valor do rótulo.
- Se quiser adicionar mais rótulos, clique em Adicionar rótulo novamente.
- Para excluir um marcador, clique em Excluir.
- Quando terminar, clique em Adicionar. A página do novo agente é reaberta.
Continue para a próxima seção para colocar o agente no modo de rascunho ou publicá-lo.
Visualizar e publicar o agente
Na seção Prévia, insira um exemplo de pergunta no campo Fazer uma pergunta e pressione Enter.
Para verificar se o agente de dados retorna os dados esperados, analise a resposta dele. Se a resposta não for o que você espera, mude as configurações na seção Editor para refinar a configuração do agente de dados até receber respostas satisfatórias. Você pode continuar testando e modificando o agente para refinar os resultados dele.
Clique em Salvar.
Para colocar o agente de dados no modo de rascunho, que pode ser editado novamente mais tarde, clique em Voltar para retornar à página Catálogo de agentes. Como o agente está no modo de rascunho, ele aparece na seção Meus agentes em rascunho na guia Catálogo de agentes.
Para publicar o agente, permaneça na página de criação e siga para a próxima etapa.
Para publicar o agente de dados e disponibilizá-lo para uso no projeto, clique em Publicar. Ao publicar o agente, outros usuários que têm acesso às mesmas tabelas de banco de dados podem ver e conversar com ele, aproveitando as instruções e o contexto que você criou.
É possível criar conversas com o agente de dados usando a página Agentes no console do Google Cloud . Também é possível criar sua própria interface para conversar com o agente de dados usando a API Conversational Analytics.
Opcional: na caixa de diálogo Seu agente foi publicado, clique em Compartilhar para compartilhar o agente de dados com outros usuários.
- No painel Permissões de compartilhamento, clique em Adicionar principal.
- No campo Novos principais, insira um ou mais principais.
- Clique na lista Selecionar um papel.
- Na lista Papel, selecione um dos seguintes papéis:
- Usuário do agente de dados do Gemini Data Analytics
(
roles/geminidataanalytics.dataAgentUser): concede permissão para conversar com o agente de dados. - Editor do agente de dados do Gemini Data Analytics (
roles/geminidataanalytics.dataAgentEditor): concede permissão para editar o agente de dados. - Leitor do agente de dados do Gemini Data Analytics
(
roles/geminidataanalytics.dataAgentViewer): concede permissão para visualizar o agente de dados.
- Usuário do agente de dados do Gemini Data Analytics
(
- Clique em Salvar.
Opcional: você pode publicar o agente de dados no Gemini Enterprise. Para mais informações, consulte Publicar um agente de dados no Gemini Enterprise.
Para voltar à página do novo agente, clique em Fechar. Depois de salvar ou publicar o agente, ele vai aparecer no Catálogo de agentes.
Gerenciar agentes de dados
Você pode encontrar os agentes na guia Catálogo de agentes, que consiste em três seções:
- Meus agentes: uma lista de todos os agentes que você cria e publica. Você pode modificar e compartilhar agentes publicados com outras pessoas.
- Meus agentes de rascunho: agentes que você ainda não publicou. Não é possível compartilhar rascunhos de agentes.
- Compartilhados por outras pessoas na sua organização: agentes que outras pessoas criam e compartilham com você. Se outras pessoas concederem permissões a você, será possível editar esses agentes compartilhados.
Editar um agente de dados
Para editar um agente de dados, siga estas etapas:
No console Google Cloud , acesse a página do Cloud SQL para PostgreSQL.
Selecione uma instância na lista.
No menu de navegação, clique em Agentes.
Faça login em Agentes usando a autenticação do Identity and Access Management (IAM).
Clique na guia Catálogo de agentes.
Localize o card do agente de dados que você quer modificar.
Para abrir o agente de dados no editor de agentes, clique em Abrir ações e em Editar no card do agente.
Edite a configuração do agente de dados conforme necessário.
Para salvar as mudanças sem publicar, clique em Salvar.
Para publicar as mudanças, clique em Publicar. Na caixa de diálogo Compartilhar, você pode compartilhar o agente com outras pessoas ou clicar em Cancelar.
Para voltar ao painel Agentes, clique em Voltar.
Compartilhar um agente de dados
Siga estas etapas para compartilhar um agente de dados publicado. Não é possível compartilhar agentes em rascunho.
No console Google Cloud , acesse a página do Cloud SQL para PostgreSQL.
Selecione uma instância na lista.
No menu de navegação, clique em Agentes.
Faça login em Agentes usando a autenticação do Identity and Access Management (IAM).
Clique na guia Catálogo de agentes.
Localize o card do agente de dados que você quer modificar.
Para abrir o agente de dados no editor de agentes, clique em Abrir ações > clique em Editar no card do agente.
Para compartilhar o agente de dados com outros usuários, clique em Compartilhar.
No painel Permissões de compartilhamento, clique em Adicionar principal.
No campo Adicionar principais, insira um ou mais principais.
Clique em Selecionar papel.
Na lista Papel, selecione um dos seguintes papéis:
- Usuário do agente de dados do Gemini Data Analytics
(
roles/geminidataanalytics.dataAgentUser): concede permissão para conversar com o agente de dados. - Editor do agente de dados do Gemini Data Analytics
(
roles/geminidataanalytics.dataAgentEditor): concede permissão para editar o agente de dados. - Leitor do agente de dados do Gemini Data Analytics
(
roles/geminidataanalytics.dataAgentViewer): concede permissão para visualizar o agente de dados.
- Usuário do agente de dados do Gemini Data Analytics
(
Clique em Salvar.
Para voltar à página de edição do agente, clique em Fechar.
Para voltar ao painel Agentes, clique em Voltar.
Excluir um agente de dados
No console Google Cloud , acesse a página do Cloud SQL para PostgreSQL.
Selecione uma instância na lista.
No menu de navegação, clique em Agentes.
Faça login em Agentes usando a autenticação do Identity and Access Management (IAM).
Selecione a guia Catálogo de agentes.
Na seção Agentes da guia Catálogo de agentes, localize o card do agente de dados que você quer excluir.
Clique em Abrir ações > Excluir.
Na caixa de diálogo Excluir agente?, clique em Excluir. A exclusão permanente do agente remove o agente do projeto.
Depois que você exclui um agente, as conversas ficam disponíveis no modo somente leitura. Não é possível fazer novas perguntas ao agente excluído.
Publicar um agente de dados no Gemini Enterprise
A publicação de um agente de dados envolve a colaboração entre analistas de dados, administradores do Gemini Enterprise e usuários comerciais. Para saber mais sobre os papéis necessários para esses usuários, consulte Papéis necessários.
Criar e publicar um agente
Para criar, editar e publicar um agente, siga estas etapas:
- Crie ou edite seu agente de dados no Cloud SQL para PostgreSQL.
- Publique o agente. Ao publicar o agente, selecione Gemini Enterprise como uma opção de publicação.
- Para copiar o JSON do endpoint A2A, clique em Copiar JSON.
- Compartilhe o JSON do endpoint A2A e a lista de usuários com o administrador do Gemini Enterprise para que ele possa registrar o agente personalizado no console Google Cloud e configurar as permissões de acesso. Para mais informações, consulte Provisionar um agente.
- Compartilhe o agente com os usuários e grupos que precisam de acesso.
Provisionar um agente
Para disponibilizar um agente publicado aos usuários no console do Google Cloud , siga estas etapas:
No console Google Cloud , acesse Gemini Enterprise.
Clique no nome do app em que você quer registrar o agente.
Clique em Agentes > Adicionar agentes.
Na seção Escolher um tipo de agente, clique em Adicionar para Agente personalizado via A2A.
No campo JSON do card do agente, insira os detalhes do card que você recebeu do analista de dados em formato JSON.
Clique em Visualizar detalhes do agente > Próxima.
Para permitir que o agente acesse recursos do Google Cloud em seu nome, siga estas etapas:
Insira o ID do cliente e a chave secreta do cliente que você gerou na seção Configurar detalhes de autorização.
No campo URI de autorização, insira o seguinte:
https://accounts.google.com/o/oauth2/v2/auth?client_id=client_id&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
Substitua client_id pelo ID do cliente gerado em Configurar detalhes de autorização.
No campo URI do token, insira o seguinte:
https://oauth2.googleapis.com/token
No campo Escopos, insira o seguinte:
https://www.googleapis.com/auth/cloud-platform
Clique em Concluir.
Compartilhe o agente com os usuários ou grupos.
Para mais informações, consulte Registrar e gerenciar agentes A2A.
Encontrar e usar um agente
Você pode encontrar e usar um agente de dados no Gemini Enterprise usando qualquer um dos seguintes métodos:
- Localize o agente na Galeria de agentes e inicie uma conversa dedicada.
- Use o URL dedicado do agente para abrir o Gemini Enterprise diretamente em uma sessão com esse agente de dados específico do Cloud SQL para PostgreSQL.
- Invoque o agente escrevendo um
@mention, como@sales_pipeline_agent, no chat principal do Gemini Enterprise. - Faça uma pergunta analítica geral, como "Qual é a tendência do nosso pipeline de vendas nos últimos três meses?", para permitir que o Gemini Enterprise encaminhe automaticamente a consulta ao agente de dados relevante.
Depois de encontrar o agente, você pode interagir com ele usando um dos métodos a seguir:
- Conclua o login único do OAuth para autenticar com segurança no Cloud SQL para PostgreSQL.
- Faça perguntas em linguagem natural. O agente de análise de conversação processa suas solicitações e transmite a resposta de volta ao Gemini Enterprise como texto, Markdown, gráficos ou tabelas.
- Acesse seu histórico de conversas no painel de histórico, onde as conversas são salvas automaticamente.
Locais
A análise de dados de conversação opera globalmente. Não é possível escolher qual região usar.
A seguir
- Saiba mais sobre a análise de conversas no Cloud SQL para PostgreSQL.
- Saiba mais sobre a API Conversational Analytics.
- Analisar dados com conversas.
- Saiba mais sobre como o papel de
Leitor do agente de dados do Gemini Data Analytics (
roles/geminidataanalytics.dataAgentViewer) concede permissão para visualizar o agente de dados.