Criar agentes de dados

Pré-lançamento

Este recurso está sujeito aos "Termos da Oferta 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 assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

Observação: para enviar feedback ou solicitar suporte sobre esse recurso, envie um e-mail para [e-mail].

Neste documento, descrevemos como criar, editar, gerenciar e excluir agentes de dados no BigQuery.

No BigQuery, é possível ter conversas com agentes de dados para fazer perguntas sobre dados do BigQuery usando linguagem natural. Os agentes de dados contêm metadados de tabelas e instruções de processamento de consultas específicas para casos de uso que definem a melhor maneira de responder às perguntas dos usuários sobre um conjunto de fontes de conhecimento, como tabelas, visualizações ou funções definidas pelo usuário (UDFs) que você seleciona.

Antes de começar

1. Verify that billing is enabled for your Google Cloud project.

2. Enable the BigQuery, Gemini Data Analytics, and Gemini for Google Cloud APIs.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the APIs

Funções exigidas

Para trabalhar com agentes de dados, você precisa ter um dos seguintes papéis do Identity and Access Management da API Conversational Analytics:

• 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 projeto.
• Crie, edite, compartilhe e exclua seus próprios agentes de dados no projeto: Criador do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentCreator) no projeto. Essa função concede automaticamente o papel 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 do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer).

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

• Usuário sem estado do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentStatelessUser).
• Leitor de dados do BigQuery (roles/bigquery.dataViewer) em qualquer tabela que o agente de dados use como fonte de conhecimento.
• Leitor do catálogo do Dataplex ( roles/datacatalog.catalogViewer) no projeto
• Se uma tabela de dados usar o controle de acesso no nível da coluna, o leitor refinado (roles/datacatalog.categoryFineGrainedReader) na tag de política apropriada. Para mais informações, consulte Papéis usados com controle de acesso no nível da coluna.
• Se uma tabela de dados usar controle de acesso no nível da linha, você precisará ter a política de acesso no nível da linha nessa tabela. Para mais informações, consulte Criar ou atualizar políticas de acesso no nível da linha.
• Se uma tabela de dados usar mascaramento de dados, o leitor mascarado (roles/bigquerydatapolicy.maskedReader) na política de dados adequada. Para mais informações, consulte Funções para consultar dados mascarados.

Para trabalhar com recursos do BigQuery, como ver tabelas ou executar consultas, consulte Funções do BigQuery.

Práticas recomendadas

Ao usar a análise de dados de conversas, as consultas são executadas automaticamente para responder às suas perguntas. Você pode receber cobranças inesperadas nos seguintes casos:

• Se as tabelas forem grandes
• Se as consultas usarem junções de dados
• Se as consultas fizerem muitas chamadas para funções de IA

Para evitar esse problema, considere o tamanho ao selecionar fontes de conhecimento e, ao conversar, use junções.

Gerar insights

Você pode gerar insights de dados no Dataplex Universal Catalog para qualquer tabela que queira usar como fonte de conhecimento.

Os insights gerados fornecem metadados de tabelas que o agente de dados pode usar para ajudar a gerar respostas às suas perguntas.

Se você não gerar insights antecipadamente, o sistema vai fazer isso automaticamente quando você selecionar uma tabela como fonte de conhecimento ao criar um agente de dados.

Trabalhar com o agente de dados de amostra

Se você não sabe como configurar agentes para análises de conversação, pode conferir o agente de amostra predefinido gerado para cada projeto doGoogle Cloud . Você pode conversar com ele e ver os parâmetros para saber como ele foi criado, mas não pode modificar.

Para conferir o agente de amostra, faça o seguinte:

1. No console Google Cloud , acesse a página Agentes do BigQuery.

   Acessar "Agentes"

2. Selecione a guia Catálogo de agentes.

3. Na seção Exemplos de agentes do Google, clique no card do agente de exemplo.

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.

Observação: se você estiver em uma conversa com uma fonte de dados, também poderá criar um agente com base nela.

Configurar noções básicas

1. No console Google Cloud , acesse a página Agentes do BigQuery.

   Acessar "Agentes"

2. Selecione a guia Catálogo de agentes.

3. Clique em New agent. A página Novo agente é aberta.

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

5. No campo Descrição do agente, digite 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 saber quando esse é o agente de dados certo para conversar. Por exemplo, Ask questions about customer orders and revenue.

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

7. Na seção Recentes, selecione as tabelas, visualizações ou UDFs que você quer usar como fontes de conhecimento. As UDFs têm o prefixo "fx" no consoleGoogle Cloud .

8. Para ver outras fontes de conhecimento, selecione Mostrar mais.

9. Opcional: adicione uma fonte de conhecimento que não está listada na seção Recentes:

   1. Na seção Pesquisar, digite o nome da fonte no campo Pesquisar tabelas e pressione Enter. O nome da origem não precisa ser exato.

   2. Na seção Resultados da pesquisa, selecione uma ou mais fontes.

10. 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, você pode fornecer metadados adicionais da tabela. Somente o agente de dados usa esses metadados, e eles não afetam a tabela de origem.

Siga estas práticas recomendadas ao criar uma tabela e descrições de campos:

• Use essas descrições como um guia para entender como o agente de dados entende o esquema. Se as descrições sugeridas pelo agente estiverem corretas, aceite-as.

• Se o agente de dados não entender o esquema depois que você configurar essas descrições, ajuste-as manualmente para fornecer as informações corretas.

Siga estas etapas para configurar descrições de tabelas e campos:

1. Na seção Fontes de conhecimento, clique no link Personalizar de uma tabela.

2. Crie uma descrição da tabela. Você pode digitar uma descrição no campo Descrição da tabela ou aceitar a sugestão do Gemini.

3. Na seção Campos, revise as descrições de campo sugeridas pelo Gemini.

4. Selecione as descrições de campo que você quer aceitar e clique em Aceitar sugestões. Selecione as descrições que você quer rejeitar e clique em Rejeitar sugestões.

5. Para editar manualmente a descrição de um campo, clique em Editar ao lado dele. O painel Editar campo é aberto.

   1. No campo Descrição, digite uma descrição.
   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 será reaberta.

7. Repita essas etapas para cada tabela que precisa de personalização.

Configurar recursos avançados

Configure recursos avançados opcionais, como instruções do agente, consultas verificadas (antes conhecidas como consultas de ouro) e configurações.

Criar instruções para o agente

O agente precisa entender o contexto das perguntas do usuário sem precisar de instruções personalizadas. Crie instruções personalizadas para o agente somente se precisar mudar o comportamento dele ou melhorar o contexto de maneiras que ainda não são compatíveis com outros recursos de contexto, como metadados personalizados de tabela e campo ou consultas verificadas.

Na seção Instruções, digite as instruções para o agente de dados no campo Instruções do agente. Como o agente de dados usa essas instruções para entender o contexto das perguntas dos usuários e fornecer respostas, deixe as instruções o mais claras possível.

Se você não receber uma resposta satisfatória do agente, adicione contexto estruturado, como descrições ou exemplos. Se você ainda não receber uma resposta satisfatória, adicione instruções personalizadas como os exemplos na tabela a seguir. Para mais exemplos de instruções, clique em Mostrar exemplos.

Tipo de informação	Descrição	Exemplos
Campos-chave	Os campos mais importantes para análise.	"Os campos mais importantes nesta tabela são: ID do cliente, ID do produto e data do pedido."
Como filtrar e agrupar	Campos que o agente deve usar para filtrar e agrupar dados.	"Quando uma pergunta for sobre uma linha do tempo ou 'ao longo do tempo', use sempre a coluna order_created_date." "Quando alguém diz 'por produto', agrupe pela coluna product_category."
Filtragem padrão	Campos para filtrar por padrão.	"A menos que seja indicado o contrário, sempre filtre os dados em order_status = 'Complete'."
Sinônimos e termos comerciais	Termos alternativos para campos-chave.	"Se alguém perguntar sobre 'Receita' ou 'Vendas', use a coluna 'total_sale_amount'." "Consideramos clientes 'fiéis' aqueles com purchase_count > 5."
Campos excluídos	Campos que o agente de dados deve evitar usar.	"Nunca use estes campos: Data da transação derivada, Cidade derivada."
Mesclar relações	Como duas ou mais tabelas estão relacionadas e quais colunas são usadas para uni-las. O agente precisa usar JOINs SQL padrão em pares de colunas para combinar dados. Consulte a coluna de exemplo.	Atividade do cliente order_items.user_id = users.id (para vincular vendas a clientes) events.user_id = users.id (para vincular a atividade do site a clientes conectados)

Criar consultas verificadas

Um agente usa consultas verificadas de duas maneiras:

• Se um agente puder usar uma consulta verificada para responder a uma pergunta que você fizer, ele vai invocar a consulta exatamente como foi escrita para garantir uma resposta confiável.
• Se o agente não puder usar a consulta verificada para responder a uma pergunta, ele ainda vai usar a consulta como referência para entender os dados e as práticas recomendadas para consultá-los.

Você pode selecionar consultas verificadas em uma lista gerada pelo sistema ou criar as suas.

Para criar uma consulta verificada para o agente de dados, antes conhecida como consulta de ouro, faça o seguinte:

1. Selecione uma ou mais consultas verificadas sugeridas pelo Gemini:

   1. Na seção Consultas verificadas, clique em Revisar sugestões. A página Analisar as consultas verificadas sugeridas é aberta.
   2. Analise as consultas verificadas sugeridas. Selecione as opções que se aplicam ao seu caso de uso.
   3. Clique em Adicionar. A página do novo agente é reaberta.

2. Para criar sua própria consulta verificada, clique em Adicionar consulta. A página Adicionar consulta verificada é aberta.

   1. No campo Pergunta, digite a pergunta do usuário que a consulta verificada responde.
   2. Clique em Gerar SQL para que o Gemini gere uma consulta verificada que corresponda à pergunta do usuário especificada.
   3. Modifique a consulta verificada, se quiser.
   4. Clique em Executar e verifique se a consulta retorna os resultados esperados.
   5. Clique em Adicionar. A página do novo agente é reaberta.

3. Repita essas etapas conforme necessário para criar outras consultas verificadas.

Definir configurações

Na seção Configurações, é possível definir as seguintes configurações opcionais:

1. Crie rótulos para ajudar a 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 Google Cloud .

   1. Na seção Configurações, clique em Gerenciar marcadores.
   2. Clique em Adicionar rótulo.
   3. Nos campos chave e valor, insira o par de chave-valor do rótulo.
   4. Se quiser adicionar mais rótulos, clique em Adicionar rótulo novamente.
   5. Para excluir um marcador, clique em Excluir.
   6. Quando terminar, clique em Adicionar. A página do novo agente é reaberta.

2. Opcional: defina um limite de tamanho para as consultas processadas pelo agente de dados. Na seção Configurações, digite um valor no campo Máximo de bytes faturados. Defina esse limite como 10485760 ou mais. Caso contrário, você vai receber a seguinte mensagem de erro:

Value error. In BigQuery on-demand pricing charges are
rounded up to the nearest MB, with a minimum of 10 MB of data processed
per query. So, max bytes billed must be set to greater or equal to
10485760.

Se você não especificar um valor, maximum bytes billed vai usar a cota de uso de consultas por dia do projeto. A cota de uso por dia é ilimitada, a menos que você tenha especificado uma cota personalizada.

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

Visualizar e publicar o agente

1. Na seção Prévia, digite um exemplo de pergunta do usuário no campo Faça uma pergunta e pressione Enter. Para verificar se o agente de dados retorna as informações esperadas, 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 seu 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 seu agente está no modo de rascunho, ele aparece na seção Meus agentes de rascunho da 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. Clique em Publicar para publicar o agente de dados e disponibilizá-lo para uso no projeto. Você pode criar conversas com o agente de dados usando o BigQuery Studio e o Looker Studio Pro, se tiver uma assinatura do Looker Studio. Também é possível criar sua própria interface para conversar com o agente de dados usando a API Conversational Analytics.

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. Imediatamente após 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 agentes em rascunho.
• Compartilhados por outras pessoas na sua organização: agentes criados e compartilhados com você por outras pessoas. Se outras pessoas concederem permissões a você, será possível editar esses agentes compartilhados.

Editar um agente de dados

Siga estas etapas para editar um agente de dados:

1. Acesse a página Agentes do BigQuery.

   Acessar "Agentes"

2. Selecione a guia Catálogo de agentes.

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

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

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

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

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

8. 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. Acesse a página Agentes do BigQuery.

   Acessar "Agentes"

2. Selecione a guia Catálogo de agentes.

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

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

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

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

7. No campo Novos principais, insira um ou mais principais.

8. Clique na lista Selecionar um papel.

9. Na lista Papel, selecione um dos seguintes papéis:

   • Usuário do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser): permite 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.

10. Clique em Salvar.

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

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

    

Excluir um agente de dados

1. Acesse a página Agentes do BigQuery.

   Acessar "Agentes"

2. Selecione a guia Catálogo de agentes.

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

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

5. Na caixa de diálogo Excluir agente?, clique em Excluir.

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 análise de conversação no BigQuery.
• Saiba mais sobre a API Conversational Analytics.
• Analisar dados com conversas.
• Saiba mais sobre como o papel Leitor do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) concede permissão para visualizar o agente de dados.