Criar agentes de dados

Os agentes de dados conversacionais permitem interagir 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", desbloqueando insights de bancos de dados operacionais sem exigir que eles escrevam consultas SQL complexas.

Em um nível alto, um agente de dados é uma combinação de persona, um conjunto de fontes de dados, com acesso a um conjunto de conhecimentos comerciais essenciais para fins específicos.

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 informações adicionais sobre as consultas de banco de dados esperadas.
  • Complexidade reduzida: os agentes traduzem a linguagem natural em consultas SQL, execução e até mesmo resumo ou visualização de dados.
  • Flexibilidade: é possível criar agentes para testes pessoais ou publicá-los para disponibilizá-los a outros usuários no projeto ou programaticamente usando a API.

Antes de começar

  1. Verifique se o faturamento está ativado para o Google Cloud projeto.

  2. Ative o Spanner, a API Data Analytics com o 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ão serviceusage.services.enable. Saiba como conceder papéis.

    Ativar as APIs

Funções exigidas

Para trabalhar com agentes de dados, é necessário ter um dos seguintes papéis do Identity and Access Management (IAM) da API Análises de conversação:

  • Consultar dados de fontes de banco de dados compatíveis usando o método QueryData: Usuário de consulta de dados do Gemini Data Analytics (roles/geminidataanalytics.queryDataUser) no nível do projeto.
  • Criar, editar, compartilhar e excluir todos os agentes de dados no projeto: Proprietário do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentOwner) no nível do projeto.
  • Criar seus próprios agentes de dados no projeto: Criador do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentCreator) no nível do projeto. Esse papel concede automaticamente o papel de Proprietário do agente de dados do Gemini Data Analytics nos agentes de dados criados.
  • Visualizar e editar todos os agentes de dados no projeto: Editor do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor) no nível do projeto.
  • Visualizar todos os agentes de dados no projeto: Leitor do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) no nível do projeto.

Além disso, é necessário ter os seguintes papéis para criar ou editar um agente de dados:

Para trabalhar com recursos do Spanner, consulte Papéis e permissões do Spanner.

Criar um agente de dados

As seções a seguir descrevem como criar um agente de dados. Depois de criar um agente, você pode editar as configurações dele.

Configurar noções básicas

  1. No Google Cloud console, acesse a página Spanner.

    Acessar o Spanner

  2. Selecione uma instância na lista e, em seguida, um banco de dados.

  3. No menu de navegação, clique em Agentes.

  4. Clique na guia Agentes.

  5. Selecione um banco de dados e faça login usando sua conta do IAM.

  6. Clique em New agent. A página New agent será aberta.

  7. Na seção Editor, no campo Agent name, insira um nome descritivo para o agente de dados, por exemplo, Q4 sales data ou User activity logs.

  8. No campo Agent description, insira uma descrição do agente de dados. Uma boa descrição explica o que o agente faz, quais dados ele usa e ajuda a determinar se esse é o agente de dados correto para uma conversa. Por exemplo, What are the top 10 selling products in Q2?

  9. Na seção Knowledge sources, clique em Add source. A página Add data será aberta.

  10. Selecione as tabelas em que o agente vai se concentrar ao responder a perguntas. Para conferir outras fontes de conhecimento, selecione Show more.

  11. Clique em Adicionar. A nova página do agente será reaberta.

Personalizar descrições de tabelas e campos

Para melhorar a acurácia do agente de dados conversacional, é possível fornecer outros metadados de 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 para tabelas e colunas para ajudar o agente a entender seus dados. Se você não adicionar descrições, o agente usará as descrições de esquema das 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 para 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 pretendido, você pode decidir se quer adicioná-la à definição de dados.

Para configurar descrições de tabelas e campos, siga estas etapas:

  1. Na guia Agent Catalog, abra o agente que você quer personalizar.
  2. Clique em Edit Agent.
  3. Em Knowledge Sources, encontre a tabela que você quer personalizar e clique em Customize.
  4. Insira uma descrição da tabela.
  5. Para editar qualquer descrição de campo, clique em Edit ao lado do campo. O painel Edit field será aberto.
    1. No campo ID, insira uma descrição do campo.
    2. Para salvar a descrição do campo, clique em Update.
  6. Para salvar a descrição e as atualizações de campo, clique em Update. A nova página do agente será reaberta.
  7. Repita essas etapas para cada tabela que você quer personalizar.

Adicionar rótulos a agentes de dados

Na seção Agent Settings, é possível criar rótulos para organizar seus Google Cloud recursos. Os rótulos são pares de chave-valor que permitem agrupar objetos relacionados entre si ou com outros Google Cloud recursos.

  1. Na guia Agent Catalog, abra o agente ao qual você quer adicionar um rótulo.
  2. Clique em Edit Agent.
  3. Na seção Agent Settings, clique em Add label. O painel Manage labels será aberto.
  4. Clique em Adicionar rótulo.
  5. Nos campos key e value, insira o par de chave-valor do rótulo.
  6. Se você quiser adicionar mais rótulos, clique em Adicionar rótulo novamente.
  7. Para excluir um rótulo, clique em excluir.
  8. Quando terminar, clique em Adicionar. A nova página do agente será reaberta.

Continue na próxima seção para colocar o agente no modo de rascunho ou para publicar o agente.

Visualizar e publicar o agente

  1. Na seção Preview , insira uma pergunta de exemplo no campo Ask a question e pressione Enter.

    Para verificar se o agente de dados retorna os dados esperados, revise a resposta do agente. 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.

  2. Clique em Salvar.

  3. Para colocar o agente de dados no modo de rascunho, que pode ser editado novamente mais tarde, clique em Go back para retornar à página Agent Catalog. Como o agente está no modo de rascunho, ele aparece na seção My draft agents na guia Agent Catalog.

    Para publicar o agente, permaneça na página de criação do agente e siga para a próxima etapa.

  4. Para publicar o agente de dados e disponibilizá-lo para uso no projeto, clique em Publish. A publicação do agente permite que outros usuários que têm acesso às mesmas tabelas de banco de dados visualizem e conversem com o agente, beneficiando-se das instruções e do contexto criados.

    É possível criar conversas com o agente de dados usando a página Agents no Google Cloud console. Também é possível criar sua própria interface para conversar com o agente de dados usando a API Análises de conversação.

  5. Opcional: na caixa de diálogo Your agent has been published, clique em Share para compartilhar o agente de dados com outros usuários.

    1. No painel Share permissions, clique em Add principal.
    2. No campo New principals, insira um ou mais principais.
    3. Clique na lista Select a role.
    4. Na lista Role, 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.

  6. Clique em Salvar.

  7. Para retornar à nova página do agente, clique em Close. Depois de salvar ou publicar o agente, ele vai aparecer no Agent Catalog.

Gerenciar agentes de dados

É possível encontrar agentes atuais na guia Agent Catalog, que consiste em três seções:

  • My agents: uma lista de todos os agentes criados e publicados. É possível modificar e compartilhar agentes publicados com outras pessoas.
  • Meus agentes de rascunho: agentes que ainda não foram publicados. Não é possível compartilhar agentes de rascunho.
  • Compartilhado por outros em sua organização: agentes que outras pessoas criam e compartilham com você. Se outras pessoas concederem permissões, você poderá editar esses agentes compartilhados.

Editar um agente de dados

Para editar um agente de dados, siga estas etapas:

  1. No Google Cloud console, acesse a página Spanner.

    Acessar o Spanner

  2. Selecione uma instância na lista e, em seguida, um banco de dados.

  3. No menu de navegação, clique em Agentes.

  4. Faça login em Agents usando a autenticação do Identity and Access Management (IAM).

  5. Clique na guia Agent Catalog.

  6. Localize o card do agente de dados que você quer modificar.

  7. Para abrir o agente de dados no editor de agentes, clique em Open actions e em Edit no card do agente.

  8. Edite a configuração do agente de dados conforme necessário.

  9. Para salvar as alterações sem publicar, clique em Salvar.

  10. Para publicar as alterações, clique em Publicar. Na caixa de diálogo Share , você pode compartilhar o agente com outras pessoas ou clicar em Cancel.

  11. Para retornar ao painel Agents, clique em Go back.

Compartilhar um agente de dados

Siga estas etapas para compartilhar um agente de dados publicado. Não é possível compartilhar agentes de rascunho.

  1. No Google Cloud console, acesse a página Spanner.

    Acessar o Spanner

  2. Selecione uma instância na lista e, em seguida, um banco de dados.

  3. No menu de navegação, clique em Agentes.

  4. Faça login em Agents usando a autenticação do Identity and Access Management (IAM).

  5. Clique na guia Agent Catalog.

  6. Localize o card do agente de dados que você quer modificar.

  7. Para abrir o agente de dados no editor de agentes, clique em Open actions > clique em Edit no card do agente.

  8. Para compartilhar o agente de dados com outros usuários, clique em Share.

  9. No painel Share permissions, clique em Add principal.

  10. No campo Add principals, insira um ou mais principais.

  11. Clique em Selecionar papel.

  12. Na lista Role, 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.

  13. Clique em Salvar.

  14. Para retornar à página de edição do agente, clique em Close.

  15. Para retornar ao painel Agents, clique em Go back.

Excluir um agente de dados

  1. No Google Cloud console, acesse a página Spanner.

    Acessar o Spanner

  2. Selecione uma instância na lista e, em seguida, um banco de dados.

  3. No menu de navegação, clique em Agentes.

  4. Faça login em Agents usando a autenticação do Identity and Access Management (IAM).

  5. Selecione a guia Agent Catalog.

  6. Na seção Agents da guia Agent Catalog, localize o card do agente de dados que você quer excluir.

  7. Clique em Open actions > Delete.

  8. Na caixa de diálogo Delete agent?, clique em Delete. A exclusão do agente remove permanentemente o agente do projeto.

    Depois de excluir um agente, as conversas atuais ficam disponíveis no modo somente visualização. Não é possível fazer novas perguntas ao agente excluído.

Locais

O recurso Análises de conversação opera globalmente. Não é possível escolher qual região usar.

A seguir