Criar agentes de dados

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

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.
• Complexidade reduzida: 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

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

2. 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ão serviceusage.services.enable. Saiba como conceder papéis.

   Ativar as APIs

Funções exigidas

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

• Consulte 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.
• Crie 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 a função de proprietário do agente de dados do Gemini Data Analytics nos agentes de dados que você cria.
• Ver 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.
• Confira todos os agentes de dados no projeto: leitor de agentes de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) no nível do projeto.

Além disso, você precisa ter os seguintes papéis para criar ou editar um agente de dados:

• Um usuário do IAM ou uma conta de serviço adicionada à instância. Para mais informações, consulte Gerenciar usuários com autenticação de banco de dados do IAM para Cloud SQL.
• Os papéis cloudsql.studioUser e cloudsql.instanceUser concedidos ao usuário do IAM no nível do projeto. Para mais informações, consulte Adicionar uma vinculação de política do IAM a um projeto.

• Privilégios de banco de dados concedidos a um usuário do IAM ou a uma conta de serviço fazendo login como o usuário postgres.

  GRANT ALL ON SCHEMA public TO public;
  

  Para mais informações, consulte Conceder privilégios de banco de dados a um usuário individual do IAM ou a uma conta de serviço.

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

1. No console Google Cloud , acesse a página do Cloud SQL para PostgreSQL.

   Acessar o Cloud SQL

2. Selecione uma instância na lista.

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 Novo agente é aberta.

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

8. 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?

9. Na seção Fontes de conhecimento, clique em Adicionar fonte. A página Adicionar dados é aberta.

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

11. Clique em Adicionar. A página do novo agente é reaberta.

Personalizar descrições de tabelas e campos

Para melhorar a acurácia 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 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:

1. Na guia Catálogo de agentes, abra o agente que você quer personalizar.
2. Clique em Editar agente.
3. Em Fontes de conhecimento, encontre a tabela que você quer personalizar e clique em Personalizar.
4. Insira uma descrição da tabela.
5. Para editar a descrição de um campo, clique em Editar ao lado dele. O painel Editar campo é aberto.
   1. No campo ID, insira uma descrição do campo.
   2. Para salvar a descrição do campo, clique em Atualizar.
6. Para salvar a descrição e as atualizações de campo, clique em Atualizar. A página do novo agente é reaberta.
7. 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.

1. Na guia Catálogo de agentes, abra o agente a que você quer adicionar um rótulo.
2. Clique em Editar agente.
3. Na seção Configurações do agente, clique em Adicionar marcador. O painel Gerenciar marcadores é aberto.
4. Clique em Adicionar rótulo.
5. Nos campos chave e valor, insira o par de chave-valor do rótulo.
6. Se quiser adicionar mais rótulos, clique em Adicionar rótulo novamente.
7. Para excluir um marcador, clique em Excluir.
8. 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

1. Na seção Prévia, insira uma pergunta de exemplo no campo Fazer uma pergunta e pressione Enter.

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

2. Clique em Salvar.

3. 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.

4. 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 Análises de conversação.

5. Opcional: na caixa de diálogo Seu agente foi publicado, clique em Compartilhar para compartilhar o agente de dados com outros usuários.

   1. No painel Permissões de compartilhamento, clique em Adicionar principal.
   2. No campo Novos principais, insira um ou mais principais.
   3. Clique na lista Selecionar um papel.
   4. 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.

6. Clique em Salvar.

7. 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 rascunhos de agentes: agentes que você ainda não publicou. Não é possível compartilhar rascunhos de agentes.
• Compartilhados por outras pessoas na sua organização: agentes criados e compartilhados com você por outras pessoas. 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 console Google Cloud , acesse a página do Cloud SQL para PostgreSQL.

   Acessar o Cloud SQL

2. Selecione uma instância na lista.

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

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

5. Clique na guia Catálogo de agentes.

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

7. Para abrir o agente de dados no editor, clique em Abrir ações e em Editar no card do agente.

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

9. Para salvar as mudanças sem publicar, clique em Salvar.

10. 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.

11. 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.

1. No console Google Cloud , acesse a página do Cloud SQL para PostgreSQL.

   Acessar o Cloud SQL

2. Selecione uma instância na lista.

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

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

5. Clique na guia Catálogo de agentes.

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

7. Para abrir o agente de dados no editor, clique em Abrir ações > Editar no card do agente.

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

9. No painel Permissões de compartilhamento, clique em Adicionar principal.

10. No campo Adicionar principais, insira um ou mais principais.

11. Clique em Selecionar papel.

12. 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.

13. Clique em Salvar.

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

15. Para voltar ao painel Agentes, clique em Voltar.

Excluir um agente de dados

1. No console Google Cloud , acesse a página do Cloud SQL para PostgreSQL.

   Acessar o Cloud SQL

2. Selecione uma instância na lista.

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

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

5. Selecione a guia Catálogo de agentes.

6. Na seção Agentes da guia Catálogo de agentes, localize o card do agente de dados que você quer excluir.

7. Clique em Abrir ações > Excluir.

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

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

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 Análises de conversação.
• 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.