Criar agentes de dados

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 os dados do BigQuery usando linguagem natural. Os agentes de dados contêm metadados de tabela e instruções de processamento de consultas específicas de 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ê selecionar.

Antes de começar

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

2. Ative as APIs BigQuery, Gemini Data Analytics, Gemini para Google Cloude Knowledge Catalog, se ainda não estiverem ativadas.

   Funções necessárias para ativar APIs

   Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar as APIs

Funções exigidas

Para trabalhar com agentes de dados, você precisa ter permissões do Identity and Access Management (IAM) que correspondam ao seu caso de uso. As seções a seguir listam os papéis necessários para criar e publicar agentes, provisionar agentes no Gemini Enterprise ou descobrir e usar agentes em várias plataformas. Para mais informações, consulte Papéis do IAM da API Conversational Analytics.

• Criar, editar, publicar, compartilhar e excluir agentes:
  • Para criar agentes de dados em um projeto: Criador do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentCreator) no projeto. Esse papel concede automaticamente o papel de proprietário do agente de dados do Gemini Data Analytics nos agentes de dados que você criar.
  • Para editar, compartilhar ou excluir um agente de dados: proprietário do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentOwner) no agente ou projeto.
  • Para editar um agente de dados em um projeto: Editor do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor) no projeto.
  • Para visualizar agentes de dados em um projeto: Leitor do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer) no projeto.
• Provisionar agentes no Gemini Enterprise:
  • Para disponibilizar um agente publicado aos usuários no Gemini Enterprise, você precisa de permissões para registrar e gerenciar agentes personalizados e configurar um Gateway de Agente no console de administração do Gemini Enterprise.
• Descubra e use agentes:
  • Para conversar com agentes de dados: usuário do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser).
  • Para conferir todos os agentes de dados no projeto: Leitor do Agente de Dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentViewer).
  • Para interagir com a interface de chat com tecnologia do Gemini no Data Studio: usuário do BigQuery Studio (roles/bigquery.studioUser) ou usuário do Gemini para Google Cloud (roles/cloudaicompanion.user), cada um com a permissão cloudaicompanion.topics.create. Conceda esses papéis no nível do projeto. Os usuários também precisam do papel de Leitor de recursos do Data Studio (roles/datastudio.viewer).
• Adicionar fontes de conhecimento a um agente:
  • Leitor do Data Catalog (roles/datacatalog.viewer) no projeto.
• Configurar e visualizar registros de conversas:
  • Para criar o conjunto de dados de registro e conceder acesso no projeto do agente: bigquery.datasets.create e Proprietário de dados do BigQuery (roles/bigquery.dataOwner) ou Administrador do BigQuery (roles/bigquery.admin) no conjunto de dados de registro.
  • Para mudar as configurações de registro de conversas de um agente: geminidataanalytics.dataAgents.update, incluído no Editor do agente de dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentEditor).
  • Para que o agente de serviço da API Conversational Analytics ([e-mail]) crie a tabela de registros e grave linhas: Editor de dados do BigQuery (roles/bigquery.dataEditor) no conjunto de dados de registros. Se o conjunto de dados de registro usar chaves do Cloud KMS gerenciadas pelo cliente (CMEK), conceda à conta de serviço de criptografia do BigQuery ([e-mail]) o papel de criptografador/descriptografador de CryptoKey do Cloud KMS (roles/cloudkms.cryptoKeyEncrypterDecrypter) na chave do Cloud KMS.
  • Para analistas que consultam registros de conversas: Visualizador de dados do BigQuery (roles/bigquery.dataViewer) no conjunto de dados de registro e Usuário de jobs do BigQuery (roles/bigquery.jobUser) em um projeto para executar consultas.

Para conversar, consulte os papéis necessários para conversas.

Os agentes agem em seu nome e usam suas permissões. Os agentes só podem acessar dados e recursos que você tem permissão para acessar.

Práticas recomendadas

A análise de conversação executa consultas automaticamente em seu nome para responder às suas perguntas. Considere os seguintes fatores que podem aumentar o custo da consulta:

• Tamanhos de tabela grandes
• Uso de combinações de dados em consultas
• Chamadas frequentes para funções de IA em consultas

Gerar insights

Também é possível gerar insights de dados no Knowledge Catalog para qualquer tabela que você queira usar como fonte de conhecimento.

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

Se você não gerar insights gerados com antecedência, o sistema vai gerá-los 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 souber como configurar agentes para a análise de conversação, consulte o agente de amostra predefinido gerado para cada projeto do Google Cloud . Você pode conversar com ele e ver os parâmetros para entender como ele foi criado, mas não pode modificá-lo.

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

1. No console do 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 nessa conversa.

Primeiros passos

1. No console do 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 será 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, gráficos ou UDFs que você quer usar como fontes de conhecimento. As UDFs têm o prefixo "fx" no console do Google Cloud .

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

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

   1. Na seção Pesquisar, digite o nome da origem 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 será reaberta.

Personalizar descrições de tabelas e campos

Para melhorar a precisão do agente de dados, você pode fornecer mais metadados de 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 descrições de tabelas e 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, você poderá aceitá-las.

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

Siga estas etapas para configurar as 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. Digite uma descrição no campo Descrição da tabela ou aceite 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 será aberto.

   1. No campo Descrição, digite uma descrição para o campo.
   2. Para salvar a descrição do campo, clique em Atualizar.

6. Para salvar as atualizações de descrição e campo, clique em Atualizar. A página do novo agente é reaberta.

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

Observação : se as mudanças nas descrições não forem refletidas no Google Cloud console, use o método list para verificar ou o método patch para atualizar as descrições.

Criar instruções do 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 apenas 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 tabelas e campos 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 do usuário e fornecer respostas, elas precisam ser o mais claras possível.

Se você não receber uma resposta satisfatória do agente, adicione contexto estruturado, como descrições, exemplos ou termos de glossário. Se você ainda não receber uma resposta satisfatória, adicione instruções personalizadas, como os exemplos na tabela a seguir.

Para ver ainda mais exemplos de instruções, clique em Mostrar exemplos.

Tipo de informação	Descrição	Exemplos
Campos principais	Os campos mais importantes para análise.	Os campos mais importantes nesta tabela são: ID de cliente, ID do produto, 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 disser 'por produto', agrupe pela coluna product_category."
Filtragem padrão	Campos para filtrar por padrão.	"A menos que indicado de outra forma, sempre filtre os dados em order_status = 'Complete'."
Sinônimos e termos de negócios	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 entre si e quais colunas são usadas para uni-las. O agente precisa usar junções 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 as vendas aos clientes) events.user_id = users.id (para vincular a atividade no site aos clientes que fizeram login)

Criar consultas verificadas

Um agente usa consultas verificadas de duas maneiras:

• Se um agente puder usar uma consulta verificada para responder a uma pergunta, 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 usá-la 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.

Observação: para criar uma consulta verificada parametrizada, consulte Criar consultas verificadas parametrizadas.

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 Analisar 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 será 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 que você especificou.
   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 será reaberta.

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

Criar consultas verificadas parametrizadas

As consultas verificadas parametrizadas extraem valores da pergunta de um usuário para o agente de análise de conversação e fornecem resultados personalizados.

Analistas e criadores podem criar modelos SQL reutilizáveis que contêm marcadores de posição para esses valores. Os modelos substituem dinamicamente os parâmetros no ambiente de execução para responder a uma variedade maior de perguntas dos usuários do que as consultas verificadas regulares.

Quando um usuário faz uma pergunta que corresponde ao padrão do modelo, o agente de análise de conversação extrai os valores de parâmetro da pergunta, como nome do produto, região e data. Em seguida, ele injeta esses valores na consulta parametrizada. As respostas correspondentes do modelo de consulta aparecem como verificadas.

As consultas verificadas parametrizadas aumentam significativamente o poder e a flexibilidade das consultas verificadas. Eles garantem respostas consistentes e confiáveis em várias entradas e reduzem o número de consultas individuais a serem mantidas.

Como funciona

Um especialista, como um analista de dados, define uma consulta verificada usando uma pergunta de modelo, por exemplo, "Quais foram as vendas de @product em @region?". Em seguida, o especialista cria ou modifica a consulta verificada usando parâmetros SQL, como mostra o exemplo a seguir:

SELECT * FROM sales WHERE region = @region AND product = @product

Depois que a consulta verificada é salva, um usuário pode fazer uma pergunta em linguagem natural ao agente de análise de conversação, por exemplo, "Quais foram as vendas de laptops na América do Norte?"

Para responder à pergunta do usuário, o agente executa as seguintes etapas:

1. Corresponde à pergunta com o padrão associado à consulta verificada parametrizada. O agente usa o processamento de linguagem natural (PLN) para identificar e extrair os valores de @region (América do Norte) e @product (laptops) da pergunta do usuário.
2. Substitui os valores extraídos nos marcadores de posição @region e @product no modelo SQL.
3. Executa a consulta SQL completa, por exemplo, SELECT * FROM sales WHERE region = 'North America' AND product = 'Laptops'.
4. Retorna os resultados para o usuário. As correspondências são sempre marcadas como verificadas.

Dicas para criar consultas parametrizadas eficazes

• Use nomes de parâmetros claros. Use nomes descritivos para parâmetros, por exemplo, @start_date em vez de @d1.
• Crie descrições detalhadas de parâmetros. O modelo de linguagem grande (LLM) para análise de conversas usa descrições de parâmetros para identificar os parâmetros e os valores deles nas perguntas dos usuários. Por exemplo, num_enrollments é um nome de parâmetro eficaz, mas number of student enrollments from ages 5-14 é uma descrição de parâmetro que fornece mais contexto sobre a consulta.
• Garanta a consistência dos tipos de dados. Verifique se os tipos de dados esperados pela consulta SQL correspondem aos tipos de dados que provavelmente serão extraídos da pergunta do usuário.
• Forneça um escopo bem definido. Crie modelos para padrões de perguntas comuns e importantes em que a construção da consulta é complexa ou a lógica não é intuitiva. Isso ajuda o LLM a retornar os melhores resultados.
• Teste tudo. Teste com várias frases em linguagem natural para garantir que os parâmetros sejam extraídos corretamente.

Criar uma consulta verificada parametrizada

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

Antes de criar ou modificar uma consulta, rascunhe-a considerando o padrão de linguagem natural e sua pergunta. Por exemplo, se você perguntar "Sabemos o estoque total de bananas orgânicas no depósito US-EAST?", poderá reescrever a pergunta como a consulta verificada parametrizada "Qual é o estoque total de @product no depósito @region?" O agente transforma essa pergunta em uma consulta SQL que você atualiza com valores padrão.

Para criar uma consulta verificada parametrizada para um agente de dados, você pode criar uma nova consulta ao criar um novo agente ou editar uma consulta verificada existente para um agente novo ou existente.

As instruções a seguir usam uma consulta verificada de amostra para configurar com parâmetros.

Selecione uma consulta verificada sugerida pelo Gemini

1. Na seção Consultas verificadas de um agente novo ou atual, clique em Analisar sugestões. A página Analisar as consultas verificadas sugeridas é aberta.
2. Marque a caixa de seleção ao lado de uma consulta verificada sugerida.
3. Na janela de consulta, clique em Mostrar mais para expandir a descrição da consulta.
4. Para abrir a consulta, clique em Editar.
5. Para concluir a configuração da consulta, consulte Configurar os parâmetros da consulta verificada.

Criar um agente e uma consulta verificada

1. Consulte as Etapas iniciais e continue com as demais etapas de configuração para Consultas verificadas.
2. No console do Google Cloud , na seção Consultas verificadas do novo agente, clique em Adicionar consulta. A página Adicionar consulta verificada é aberta.
3. Para concluir a configuração da consulta, consulte Configurar os parâmetros da consulta verificada.

Configurar os parâmetros da consulta verificada

1. No campo Pergunta, digite a pergunta do usuário respondida pela consulta verificada.
2. Para especificar parâmetros, use o símbolo @ seguido de um nome de parâmetro. Essa sintaxe identifica um marcador de posição que ingere um valor da pergunta do usuário. Use uma pergunta em linguagem natural que mostre como os parâmetros serão usados nas perguntas do usuário. Por exemplo: "Qual é o estoque total de @product no depósito @region?"

3. Clique em Gerar SQL. O SQL é semelhante ao exemplo a seguir:

      SELECT
          SUM(stock) AS total_stock
      FROM
          inventory
      WHERE
          product_id = @product
          AND region = @region;
   

4. Para adicionar valores padrão aos marcadores de posição na consulta, clique em Gerenciar parâmetros de consulta e em Adicionar parâmetro de consulta.

5. Para o primeiro parâmetro, quatro campos aparecem para Nome, Tipo, Valor e Descrição.

   • Em Nome, copie @product da sua pergunta e cole nesse campo.
   • Em Tipo, selecione STRING.
   • Em Valor, insira organic bananas.
   • Em Descrição, insira uma descrição o mais específica possível. Por exemplo, um produto localizado em um depósito regional.

6. Para o segundo parâmetro, clique em Adicionar parâmetro de consulta.

   • Em Nome, copie @region da sua pergunta e cole nesse campo.
   • Em Tipo, selecione STRING.
   • Em Valor, insira US-EAST.
   • Em Descrição, insira uma descrição o mais específica possível, por exemplo, a regional warehouse where products are located..

7. Depois de preencher os campos dos dois parâmetros, clique em Salvar.

Testar a consulta verificada parametrizada

1. Clique em Executar e verifique se a consulta retorna os resultados esperados.
2. Para testar a consulta para usuários em uma tela posterior, copie todo o campo de pergunta.
3. Clique em Salvar para sair da tela Adicionar consulta e voltar à página Editar do agente.
4. Na página Editar do agente, cole o campo de pergunta que você copiou anteriormente na janela Visualização.
   1. Substitua a variável @product por organic bananas.
   2. Substitua a variável @region por US-EAST.
5. Pressione Enter. Verifique o resultado. Nesse caso, uma resposta válida é o número total de bananas em estoque na região US-EAST, por exemplo,1.000.
6. Para criar ou editar outras consultas verificadas, repita essas etapas conforme necessário.

Agora que você salvou a consulta, um usuário pode perguntar "Sabemos o estoque total de bananas orgânicas no depósito US-EAST?" A análise conversacional faz o seguinte:

1. Corresponde esta pergunta ao padrão.
2. Extrai o parâmetro @product como @product = "organic bananas" e o parâmetro @region = "US-EAST" da pergunta.
3. Executa a consulta: SELECT SUM(stock) AS total_stock FROM inventory WHERE product_id = 'organic bananas' AND region = 'US-EAST';
4. Retorna o total_stock calculado.

Criar ou revisar termos do glossário

É possível criar termos de glossário personalizados do BigQuery locais para um agente ou revisar termos de glossário empresarial importados do Knowledge Catalog que se aplicam às fontes de conhecimento selecionadas para um agente.

• Como os termos do glossário empresarial do Knowledge Catalog se aplicam globalmente aos recursos do BigQuery, se você usar o Knowledge Catalog, crie e gerencie os termos do glossário empresarial no Knowledge Catalog, em vez de para agentes individuais.
• Se você precisar modificar os termos do glossário empresarial importados do Knowledge Catalog, edite-os no Knowledge Catalog e volte ao BigQuery para conferir as mudanças.
• Os termos do glossário personalizado do BigQuery permanecem no BigQuery. Eles não aparecem no Knowledge Catalog.
• Se você não estiver usando o Knowledge Catalog, poderá criar termos de glossário personalizados do BigQuery para termos que precisam ser definidos para um agente específico.

Siga estas etapas para criar termos de glossário personalizados para um agente:

1. Na seção Glossário da página Editor do agente, clique em Adicionar termo.
2. Na seção Termos personalizados, é possível editar ou excluir os termos personalizados existentes.
3. Para criar um ou mais termos, clique em Criar termo.
   1. Insira um Termo, uma Definição e um ou mais Sinônimos separados por vírgula.
   2. Para criar o termo, clique em Adicionar.
   3. Se quiser excluir o novo termo, clique em Excluir.
4. Para criar mais termos personalizados, repita essas etapas.

Siga estas etapas para conferir os termos do glossário empresarial importados do Knowledge Catalog:

1. Na seção Glossário da página Editor do agente, clique em Adicionar termo.
2. Navegue até a seção da página chamada Importado do Dataplex.
3. Para modificar os termos importados no Knowledge Catalog, clique em Acessar os glossários do Dataplex.
4. Depois de modificar os termos no Knowledge Catalog, volte para a página Editor do agente para conferir os termos modificados.

Definir as configurações

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

1. Na seção Modelo, escolha quais tipos de modelos estão disponíveis para os usuários em uma conversa com o agente. Os modelos de pré-lançamento e de disponibilidade geral estão disponíveis por padrão. Os modelos em pré-lançamento podem usar o endpoint global.

2. Crie rótulos para ajudar a organizar seus recursos doGoogle 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 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 incluir mais rótulos, clique novamente em Adicionar rótulo.
   5. Para excluir um marcador, clique em Excluir.
   6. Quando terminar, clique em Adicionar. A página do novo agente será reaberta.

3. Para gravar os eventos de conversa do agente em uma tabela do BigQuery no projeto do agente para monitoramento e análise, na seção Registro de conversas, ative a opção Ativar registro de conversas:

   1. Se as configurações de registro de conversas não estiverem disponíveis ao editar um agente, mude o seletor de visualização para Rascunho e verifique se tabelas específicas do BigQuery estão selecionadas como fontes de conhecimento.

   2. Em Definir um destino para armazenar os registros, selecione um conjunto de dados de destino no projeto do agente em ID do conjunto de dados. Em ID da tabela, selecione uma tabela ou clique em Selecionar ou criar uma tabela > + Nova tabela, insira um nome em Especificar nova tabela (por exemplo, agent_events) e clique em Salvar.

   3. Leia o Aviso de registro de dados e divulgação ao usuário.

   4. Aguarde a validação das configurações. Se o conjunto de dados não existir, crie-o primeiro no BigQuery. Se o agente de serviço da API Conversational Analytics ([e-mail]) não tiver acesso ao conjunto de dados, clique em Conceder acesso para conceder roles/bigquery.dataEditor no conjunto de dados ou peça ao administrador para conceder.

   Depois de publicar o agente, faça uma pergunta de teste na tela de chat principal do agente publicado (a seção Visualização não é registrada) e atualize o conjunto de dados de destino no BigQuery Studio para confirmar que a tabela de registros aparece. Para atualizar o destino ou desativar a geração de registros mais tarde, edite o agente e publique as mudanças (as linhas atuais não são excluídas). Para mais informações, consulte Visão geral da geração de registros de conversas.

4. 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 usará como padrão a cota de uso de consulta 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 publicá-lo.

Visualizar e publicar o agente

1. Na seção Visualização, digite um exemplo de pergunta do usuário no campo Fazer uma pergunta e pressione Enter. Para verificar se o agente de dados retorna os dados esperados, analise 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.

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 agora está no modo de rascunho, ele aparece na seção Meus agentes de rascunho na guia Catálogo de agentes.

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

4. Clique em Publicar para abrir o painel Canais de publicação e publicar o agente de dados, disponibilizando-o para uso no projeto.

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 Compartilhar permissões, 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 Análise de Dados do Gemini (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 Análise de Dados do Gemini (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.

É possível criar conversas com o agente de dados usando o BigQuery Studio ou o Data Studio. Você também pode criar sua própria interface para conversar com o agente de dados usando a API Conversational Analytics. Para saber como publicar no Data Studio, consulte Publicar um agente de dados no Data Studio. Para saber como publicar no Gemini Enterprise, consulte Publicar um agente de dados no Gemini Enterprise.

Gerenciar agentes de dados

Encontre 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. É possível modificar e compartilhar agentes publicados com outras pessoas.
• Meus rascunhos de agentes: agentes que você ainda não publicou. Não é possível compartilhar agentes de rascunho.
• Compartilhado por outras pessoas na 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

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, é possível 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 de 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 Compartilhar permissões, 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 análise de dados do Gemini (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 Análise de Dados do Gemini (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 retornar 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 Meus agentes de 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.

Publicar um agente de dados no Data Studio

Quando você publica seu agente e o compartilha com os usuários do Data Studio, ele aparece automaticamente para que eles conversem na página Conversar com seus dados no Data Studio.

Criar e publicar seu agente no Data Studio

Como analista de dados, você pode criar, editar e publicar um agente no Data Studio seguindo estas etapas:

1. Crie ou edite seu agente de dados no BigQuery.
2. Publique o agente. Ao publicar o agente, selecione Data Studio como a opção de publicação.
3. Siga as instruções para compartilhar o agente, concedendo os papéis apropriados do Identity and Access Management aos usuários do Data Studio.

Compartilhar seu agente com usuários do Data Studio

Você pode compartilhar agentes com usuários do Data Studio diretamente copiando um link que abre uma conversa com o agente no Data Studio ou pode enviar um e-mail para informar ao usuário que ele tem acesso a um agente.

Para compartilhar um link direto para o agente, copie o URL dedicado dele das seguintes maneiras:

• No catálogo de agentes: selecione Abrir ações > selecione Copiar link > selecione Data Studio.
• Na visualização de detalhes do agente: selecione Copiar link do agente > selecione Data Studio.
• No menu flutuante Compartilhar: selecione Copiar link para o agente no Data Studio.
• Depois de clicar em Salvar no painel Compartilhar permissões, selecione Copiar link.

Para enviar uma notificação por e-mail informando os destinatários sobre o acesso a um agente, selecione Enviar e-mail no painel Compartilhar permissões. As notificações por e-mail são enviadas apenas para os usuários ou grupos com quem você acabou de compartilhar o agente nessa sessão de edição. Todos os membros de um grupo recebem a notificação por e-mail, mesmo que um determinado usuário já tenha permissão no nível do agente. O e-mail inclui o nome do usuário que compartilhou o agente, o nome do agente e um link para abrir o agente no Data Studio.

Observação: se você estiver enviando um e-mail para um Grupo do Google com as configurações de Quem pode postar definidas como Somente participantes do grupo, um proprietário ou administrador do grupo precisará atualizar as configurações do grupo para Toda a organização para permitir as entregas.

Publicar um agente de dados no Gemini Enterprise

É possível publicar um agente de dados do BigQuery no Gemini Enterprise para que os usuários de negócios possam consultar e analisar dados usando linguagem natural diretamente no Gemini Enterprise. Esse processo geralmente envolve a colaboração entre analistas de dados, administradores do Gemini Enterprise e usuários corporativos. Para mais informações sobre os papéis necessários para esses usuários, consulte Papéis necessários.

Para publicar um agente de dados no Gemini Enterprise, siga estas etapas:

1. Revise os pré-requisitos.
2. Crie e publique o agente de dados no BigQuery.
3. Provisionar o agente no Gemini Enterprise.
4. Descubra e converse com o agente.

Revise os pré-requisitos

A maneira recomendada de publicar agentes de análise de conversação do BigQuery é usando o Registro de Agentes. Siga os pré-requisitos nesta seção para garantir que o agente seja detectável no Gemini Enterprise.

Como alternativa, é possível publicar o agente usando o JSON do card A2A. Se você usar esse método, consulte Criar e publicar o agente de dados no BigQuery.

Para usar o Registro de Agentes, primeiro configure o Gateway de Agente com o mapeamento de região apropriado. A região de armazenamento do agente de dados do BigQuery e a vinculação de registro do Gateway de Agente no Gemini Enterprise precisam ser iguais.

Configure a região de armazenamento do agente na seção Região do editor de agentes na UI da Web do BigQuery. Não é possível mudar a região depois que o agente é salvo.

A imagem a seguir mostra as opções de região disponíveis no Gateway de Agente:

Como administrador do Gemini Enterprise, configure um Gateway de Agente para seu aplicativo do Gemini Enterprise seguindo estas etapas:

1. Configure um Gateway de Agente que inclua a vinculação do Agent Registry correspondente à região do seu agente de dados. As opções incluem EUA, UE ou Global.
2. No Gemini Enterprise, abra o aplicativo, acesse Segurança > Configuração e insira o nome do recurso do gateway na seção Configuração do Gateway de Agente. Para instruções detalhadas, consulte Rotear o tráfego do Gemini Enterprise pelo Gateway de Agente.

Criar e publicar o agente de dados no BigQuery

Como analista de dados, você cria, configura e publica um agente no BigQuery seguindo estas etapas:

1. No BigQuery, crie ou edite seu agente de dados.
2. Na seção Região, verifique se a região de armazenamento corresponde às fontes de dados e à configuração do Gateway de Agente. As opções incluem EUA, UE ou Global.
3. Clique em Publicar ou em Publicar atualizações se o agente já tiver sido publicado.
4. No painel Canais de publicação, em Outros canais, escolha o método de publicação:
   • Se o BigQuery e o Gemini Enterprise estiverem no mesmo projeto, na seção Registro de agentes, marque a caixa de seleção Registrar este agente.
     • Se você quiser remover o agente do registro, clique em Cancelar registro.
   • Se o BigQuery e o Gemini Enterprise estiverem em projetos diferentes, na seção Integrar via A2A (Agent2Agent), clique em Copiar JSON para copiar os dados JSON do endpoint A2A e compartilhe os dados JSON com o administrador do Gemini Enterprise. Esses dados JSON são usados quando você provisiona o agente na seção Gemini Enterprise.
5. Clique em Publicar ou Publicar atualizações.
6. Compartilhe o agente com os usuários e grupos que precisam de acesso, concedendo a eles o papel de Usuário do Agente de Dados do Gemini Data Analytics (roles/geminidataanalytics.dataAgentUser).

Provisionar o agente no Gemini Enterprise

Como administrador do Gemini Enterprise, disponibilize o agente de dados para os usuários no seu aplicativo usando um dos seguintes métodos:

Opção 1: importar do Agent Registry

Siga estas etapas para importar o agente registrado:

1. Se o Gemini Enterprise estiver em um projeto diferente do projeto do BigQuery, siga as etapas abaixo para registrar manualmente o agente no Agent Registry. Caso contrário, pule esta etapa:
   1. No console do Google Cloud , acesse Registro de agentes no mesmo projeto do Gemini Enterprise, selecione a guia Agentes e clique em Adicionar agente.
   2. No painel Detalhes do agente, em Tipo, selecione A2A.
   3. Em Região, selecione a região que corresponde ao agente de dados e à configuração do Gateway de Agente.
   4. Selecione Colar JSON, cole os dados JSON do endpoint A2A do BigQuery e clique em Salvar.
2. No Gemini Enterprise, clique no nome do app em que você quer adicionar o agente.
3. No menu de navegação, clique em Agentes > clique em Adicionar agente.
4. No painel Escolha um tipo de agente, localize Agentes do registro de agentes e clique em Adicionar.
5. No painel Adicionar agente, pesquise o agente por nome, ID do registro do agente, tipo, produtor ou caso de uso, ou localize o card do agente na lista.
6. No card do agente, clique em Adicionar agente.
7. Na etapa Revisar detalhes do agente, revise os metadados do agente preenchidos com base no card A2A do agente, incluindo nome, descrição, URL do agente, recursos e habilidades, e clique em Próxima.
8. Na etapa Autenticar agente, selecione como o Gemini Enterprise se autentica com o provedor do agente:
   • Credenciais padrão gerenciadas pelo Google: o Google gerencia as credenciais do OAuth automaticamente. Não é necessário configurar manualmente ou inserir credenciais de cliente.
   • OAuth personalizado: selecione essa opção apenas se sua organização exigir credenciais personalizadas do cliente OAuth e insira o ID do cliente, a chave secreta do cliente, o URL de autorização e o URL do token.
9. Clique em Concluir.
10. O agente aparece na tabela de agentes com o estado Ativado e o tipo de agente A2A (personalizado).
11. Compartilhe o agente com os usuários ou grupos que precisam de acesso.

Opção 2: importar usando o JSON do card do A2A

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.

Se o BigQuery e o Gemini Enterprise estiverem em projetos diferentes, siga estas etapas para importar o agente usando o JSON do card A2A:

1. No Gemini Enterprise, clique no nome do app em que você quer adicionar o agente.
2. No menu de navegação, clique em Agentes > clique em Adicionar agente.
3. No painel Escolha um tipo de agente, localize Agente personalizado via A2A e clique em Adicionar.
4. No campo JSON do cartão do agente, insira o JSON do cartão do agente recebido do analista de dados.
5. Clique em Visualizar detalhes do agente > clique em Próxima.
6. Na etapa Autorização do agente, selecione o método de autenticação:
   • Credenciais padrão gerenciadas pelo Google: o Google gerencia as credenciais do OAuth automaticamente, sem que você precise inserir ou gerar manualmente um ID do cliente e uma chave secreta do cliente.
   • OAuth personalizado: selecione essa opção se quiser fornecer manualmente credenciais OAuth personalizadas, seguindo as etapas em Registrar e gerenciar agentes A2A.
7. Na etapa Autorizações de ferramentas, clique em Concluir.
8. O agente aparece na tabela de agentes com o estado Ativado e o tipo de agente A2A (personalizado).
9. Compartilhe o agente com os usuários ou grupos que precisam de acesso.

Descobrir e usar um agente

Você pode descobrir e usar um agente de dados no Gemini Enterprise usando qualquer um destes métodos:

• Descoberta manual: localize um agente de dados na Galeria de agentes e use-o com qualquer um destes métodos:
  • Navegar pela galeria: selecione o agente e inicie um chat dedicado.
  • Link direto: use o URL dedicado do agente para abrir o Gemini Enterprise diretamente em uma sessão com esse agente de dados específico do BigQuery.
  • Intenção direcionada: invoque o agente por @mention (por exemplo, @sales_pipeline_agent) no chat principal do Gemini Enterprise.
  • Orquestração integrada: faça uma pergunta analítica geral (por exemplo, "Como está a tendência do nosso pipeline de vendas nos últimos três meses?") e o Gemini Enterprise vai encaminhar automaticamente a consulta para o agente de dados relevante.

Depois de descobrir o agente, interaja com ele seguindo estas etapas:

• Autenticar: conclua o login único do OAuth para se autenticar com segurança no BigQuery.
• Chat: faça perguntas em linguagem natural ao agente. As solicitações são processadas pelo agente, e a resposta é transmitida de volta ao Gemini Enterprise como texto, Markdown, gráficos ou tabelas.
• Ver o histórico de conversas: as conversas são salvas automaticamente no painel de histórico.

Monitorar agentes e conversas

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.

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

É possível monitorar o desempenho, a adoção, a latência e os custos dos agentes de dados e das conversas deles usando o Google Cloud Observability no BigQuery. Ao ativar a observabilidade do agente, você pode conferir métricas como as seguintes:

• O número de agentes usados nas conversas
• O número de usuários que fizeram perguntas
• O número de conversas criadas
• Os agentes que responderam ao maior número de perguntas
• As fontes de conhecimento mais usadas com frequência
• Engajamento do usuário
• Uso de tokens projetado
• Latência de resposta por hora

Antes de começar

Ative as APIs Cloud Trace, Cloud Monitoring e API Cloud Logging, se ainda não estiverem ativadas.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar as APIs

Papéis e permissões necessárias

Para ativar a observabilidade do agente, é necessário ter as seguintes permissões no projeto:

• cloudaicompanion.gibqObservabilitySettings.create
• cloudaicompanion.gibqObservabilitySettings.list
• cloudaicompanion.gibqObservabilitySettings.update
• cloudaicompanion.settingBindings.gibqObservabilitySettingsCreate
• cloudaicompanion.settingBindings.gibqObservabilitySettingsList
• cloudaicompanion.settingBindings.gibqObservabilitySettingsUse
• geminidataanalytics.dataAgents.create
• geminidataanalytics.operations.get
• observability.traceScopes.create
• resourcemanager.projects.update
• serviceusage.services.enable
• serviceusage.values.test

Para receber as permissões necessárias para monitorar seus agentes usando métricas, traces e registros, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

• Acessar dados e configurações de monitoramento: Leitor do Monitoring (roles/monitoring.viewer)
• Ver traces: Usuário do Cloud Trace (roles/cloudtrace.user)
• Ver registros: Visualizador de registros (roles/logging.viewer)
• Acessar conjuntos de dados e o conteúdo deles: Visualizador de dados do BigQuery (roles/bigquery.dataViewer)
• Ver as configurações de administrador: Usuário do Gemini para Google Cloud (roles/cloudaicompanion.user)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Ativar observabilidade

A observabilidade do agente fica desativada por padrão. Um administrador pode ativá-lo para seu projeto ou organização. Para ativar a observabilidade dos agentes, selecione uma das seguintes opções:

Console

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

   Acessar "Agentes"

2. Selecione a guia Monitoramento.

3. Se a observabilidade estiver desativada, siga as instruções para ativá-la.

CLI do Google Cloud

1. Crie uma configuração de observabilidade:

   gcloud gemini gibq-observability-settings create SETTING_NAME \
     --conversational-analytics-setting-metrics-enabled \
     --conversational-analytics-setting-traces-enabled \
     --project=PROJECT_ID \
     --location=global

   Substitua:

   • SETTING_NAME: um nome para a configuração de observabilidade.
   • PROJECT_ID: o ID do projeto.

2. Vincule a configuração de observabilidade ao projeto:

   gcloud gemini gibq-observability-settings setting-bindings create BINDING_NAME \
     --gibq-observability-setting=SETTING_NAME \
     --target=projects/PROJECT_ID \
     --location=global \
     --project=PROJECT_ID

   Substitua BINDING_NAME por um nome para a vinculação de configuração. Recomendamos que você use binding-PROJECT_ID como nome da vinculação.

API

1. Crie uma configuração de observabilidade:

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d '{
             "conversational_analytics_setting": {
               "metrics_enabled": true
             }
           }' \
       "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings?gibq_observability_setting_id=SETTING_NAME"

   Substitua:

   • SETTING_NAME: um nome para a configuração de observabilidade.
   • PROJECT_ID: o ID do projeto.

2. Vincule a configuração de observabilidade ao projeto:

   curl -X POST \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       -d '{
             "target": "projects/PROJECT_ID",
             "product": "GEMINI_IN_BIGQUERY"
           }' \
       "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings/SETTING_NAME/settingBindings?setting_binding_id=BINDING_NAME"

   Substitua BINDING_NAME por um nome para a vinculação de configuração. Recomendamos que você use binding-PROJECT_ID como nome da vinculação.

Ver métricas

As métricas são coletadas depois que você ativa a observabilidade. Os dados não são preenchidos. Para conferir as métricas do agente, selecione uma das seguintes opções:

BigQuery

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

   Acessar "Agentes"

2. Selecione a guia Monitoramento.

Cloud Monitoring

1. No console do Google Cloud , acesse a página Painéis do Cloud Monitoring.

   Ir para "Painéis"

2. No painel Meus painéis, pesquise o painel chamado BigQuery Conversational Analytics.

3. Para abrir o painel, clique no nome dele.

4. Opcional: crie um painel personalizado.

5. Opcional: para ver as métricas individualmente, acesse a página do Metrics Explorer.

   Acessar o Metrics Explorer

   As métricas do agente incluem uso do agente, chamadas de modelo, uso de ferramentas, integridade, latência e uso de tokens.

Depurar chamadas de modelo

É possível visualizar a sequência de operações em uma conversa, como chamadas de modelo e de ferramenta, para ajudar a resolver problemas de erros e latência.

1. No console do Google Cloud , acesse a página Explorador de traces do Cloud Monitoring.

   Acessar o Explorador de traces

2. Clique em um período para analisar.

3. Revise as informações no painel Detalhes.

4. Opcional: crie um painel de trace personalizado.

Manter traces

Os dados do Cloud Trace são armazenados em um conjunto de dados de observabilidade por 30 dias. Para armazenar os dados de trace por mais tempo, mova-os para um conjunto de dados do BigQuery.

Funções exigidas

Para receber as permissões necessárias para expor traces em tempo real ao BigQuery criando um conjunto de dados vinculado, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto:

• Administrador do Cloud Trace (roles/cloudtrace.admin)
• Editor de observabilidade (roles/observability.editor)
• Usuário do BigQuery (roles/bigquery.user)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Mover dados de trace para o BigQuery

Para reter os dados de trace, faça o seguinte:

1. Abra o Cloud Shell.

2. Encontre o local do bucket do _Trace:

   gcloud beta observability buckets list --location=-

   Anote o local do bucket do _Trace para a próxima etapa.

3. Crie um conjunto de dados vinculado no projeto do BigQuery que aponte para o bucket _Trace:

   gcloud beta observability buckets datasets links create \
       projects/PROJECT_ID/locations/LOCATION/buckets/_Trace/datasets/Spans/links/LINK_NAME \
       --dataset=Spans \
       --bucket=_Trace \
       --location=LOCATION \
       --project=PROJECT_ID

   Substitua:

   • PROJECT_ID: ID do projeto;
   • LOCATION: o local do bucket do _Trace da etapa anterior.
   • LINK_NAME: um nome para o conjunto de dados vinculado.

4. Crie um conjunto de dados padrão para armazenar os traces históricos. O comando a seguir define a validade padrão da partição como 90 dias (7.776.000 segundos):

   bq --location=LOCATION mk \
       --dataset \
       --default_partition_expiration=7776000 \
       --description="Archive storage for historical traces" \
       PROJECT_ID:STORAGE_DATASET

   Substitua STORAGE_DATASET por um nome para o conjunto de dados.

5. Crie uma tabela particionada vazia no conjunto de dados de armazenamento com o mesmo esquema do conjunto de dados vinculado. O particionamento por data ajuda a gerenciar a retenção de dados e os custos de consulta. Para criar a tabela, execute a seguinte consulta no editor de SQL:

   CREATE TABLE `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
   PARTITION BY DATE(start_time)
   AS
   SELECT *
   FROM `PROJECT_ID.LINK_NAME._AllSpans`
   WHERE FALSE;

   Substitua TABLE_NAME por um nome para a tabela.

6. Crie uma consulta programada para copiar diariamente os dados de trace do conjunto de dados vinculado para a tabela de arquivo. A consulta a seguir copia dados do dia anterior:

   INSERT INTO `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
   SELECT *
   FROM `PROJECT_ID.LINK_NAME._AllSpans`
   WHERE start_time >=
     TIMESTAMP_SUB(TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY), INTERVAL 1 DAY)
     AND start_time < TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY);

Para mais informações, leia sobre como encontrar e analisar traces.

Desativar a observabilidade

Para desativar a observabilidade dos seus agentes de dados, atualize a configuração de observabilidade:

gcloud gemini gibq-observability-settings update SETTING_NAME \
    --no-conversational-analytics-setting-metrics-enabled \
    --no-conversational-analytics-setting-traces-enabled \
    --project=PROJECT_ID \
    --location=global

Substitua:

• SETTING_NAME: o nome da configuração de observabilidade que você criou para ativar a observabilidade. Se você ativou a observabilidade usando o console do Google Cloud , o nome da configuração é default.
• PROJECT_ID: o ID do projeto.

Analisar registros de conversas no BigQuery

Além das métricas de observabilidade no nível do projeto no Cloud Monitoring e dos períodos no Cloud Trace, é possível ativar a geração de registros de conversa por agente no BigQuery Studio para gravar cada turno de conversa, incluindo a pergunta do usuário, a resposta do agente, a latência e o uso de tokens do modelo, em uma tabela do BigQuery no projeto do agente. Em seguida, é possível consultar e avaliar os eventos registrados usando o GoogleSQL, notebooks do Colab interativos ou o SDK para Python de análise de agentes do BigQuery. Para mais informações, consulte Visão geral da geração de registros de conversas.

A seguir

• Saiba mais sobre a análise conversacional no BigQuery.
• Saiba mais sobre a API Conversational Analytics.
• Analisar dados com conversas.
• Saiba 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.