O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Visão geral da geração de registros de conversas

Com o registro de conversas da análise conversacional, é possível registrar as conversas de um agente de dados em uma tabela do BigQuery no seu projeto para analisar a qualidade das respostas, acompanhar a adoção e monitorar os custos em todos os seus agentes de análise conversacional. Para cada turno, o registro captura a pergunta do usuário, a resposta do agente, a latência, o uso de tokens do modelo e os identificadores necessários para agrupar os turnos por agente, conversa e usuário. As linhas são gravadas usando o esquema de análise de agentes do BigQuery por meio da API BigQuery Storage Write (gRPC).

O que é registrado

Cada turno registrado grava várias linhas de evento (events) na tabela de destino que registram as seguintes informações:

A pergunta do usuário.
A resposta do agente: o texto, os insights, as suposições, as perguntas de acompanhamento sugeridas, as fontes de citação e os nomes de todos os resultados de dados ou gráficos.
Latência por turno.
Uso de tokens do modelo, versão do modelo e motivo de conclusão (por que o modelo parou de gerar tokens) para cada chamada de modelo.
O ID do agente de dados e o ID da conversa, para que você possa analisar vários agentes em uma tabela.
Um identificador de usuário. Para mais informações sobre identificadores de usuário, consulte Identidade do usuário.
Detalhes de status e erro.

O que não é registrado

A geração de registros de conversas não registra o seguinte:

As consultas SQL executadas pelo agente: o registro contém a resposta final e os nomes dos resultados de dados e gráficos referenciados, mas não as consultas que os produziram. A exceção é quando um usuário pede explicitamente ao agente para mostrar ou explicar o SQL. Nesse caso, o SQL pode aparecer no texto da resposta.
As chamadas de ferramenta do agente: cada chamada de modelo grava uma linha LLM_RESPONSE, incluindo chamadas em que o modelo decide executar uma ferramenta. Antes que a linha seja gravada, a saída do modelo é removida, incluindo o nome e os argumentos de qualquer ferramenta que ele tenha chamado. Somente o uso de tokens, a versão do modelo e o motivo da conclusão são mantidos.
Feedback do usuário: o feedback de "Gostei" ou "Não gostei" não é registrado.

Algumas conversas não são registradas, como as que ocorrem no painel de prévia do BigQuery Studio. Para mais informações sobre plataformas de conversa sem suporte, consulte Limitações.

Como funciona a geração de registros de conversas

Quando um usuário conversa com um agente de dados que tem o registro de conversas ativado, a análise de conversas processa cada turno pelas seguintes etapas:

Configurar: o proprietário de um agente ativa a geração de registros de conversas e seleciona um conjunto de dados de destino e um nome de tabela no projeto do agente no BigQuery Studio.
Perguntar: um usuário envia uma pergunta ao agente. No BigQuery Studio, os usuários recebem um aviso de que as conversas são registradas.
Verificação de privacidade: antes de o agente começar a trabalhar na vez, uma verificação de privacidade lê os metadados das tabelas de fonte de conhecimento do agente usando as credenciais do usuário que está conversando. Essa verificação confirma que nenhuma das tabelas usa segurança no nível da linha (políticas de acesso à linha), segurança no nível da coluna (tags de política) ou mascaramento de dados dinâmicos. Se a verificação encontrar uma política ou não puder confirmar que não há nenhuma, a vez não será registrada, e o agente ainda responderá à pergunta do usuário.
Responder: o agente responde ao usuário normalmente.
Gravação: o agente de serviço da API Conversational Analytics do projeto (service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com) grava as linhas de registro na tabela de destino usando a API Storage Write (gRPC). Na primeira vez que um turno é registrado, o agente de serviço cria a tabela, caso ela ainda não exista.
Consulta: as linhas geralmente aparecem alguns segundos após a conclusão da resposta. O tempo de entrega não é garantido.

Os erros de registro nunca causam falhas em uma rodada, e a verificação de privacidade e a gravação de registros podem adicionar latência. Uma permissão ausente no conjunto de dados de registro, um conjunto de dados que não existe ou uma cota esgotada não faz com que a solicitação de chat falhe. A análise de conversação não informa falhas de registro na interface do chat ou no Cloud Logging.

Privacidade, governança de dados e segurança

Ao ativar a geração de registros de conversas para um agente, analise como os avisos do usuário final, o acesso a dados, a criptografia, os controles de rede e a geração de registros de auditoria se aplicam aos seus registros.

Avisos para usuários finais e conteúdo registrado

Os seguintes avisos e regras regem o que o registro de conversas registra e quem pode ver os dados registrados:

Aviso ao usuário final no BigQuery Studio: quando o registro de conversas está ativado para um agente, os usuários que conversam com ele no BigQuery Studio recebem o seguinte aviso, inclusive na tela de nova conversa antes que o usuário envie um primeiro comando:

Todos os comandos e respostas são registrados no BigQuery e podem ser acessados por usuários com permissões de conjunto de dados.
Suas responsabilidades ao usar a API: se você ativar o registro de conversas (registro de rastreamento) em um agente de dados e disponibilizar esse agente para os usuários finais pelo seu próprio aplicativo ou integração, o Google não poderá mostrar um aviso a esses usuários. Você é responsável por todos os avisos, divulgações ou consentimentos que se aplicam às conversas registradas de acordo com a legislação aplicável e seus contratos com os usuários finais. Para mais informações, consulte Segurança, privacidade, risco e compliance da API Conversational Analytics.
O que o registro contém e quem pode vê-lo: a tabela de destino armazena conteúdo de perguntas e respostas de acordo com estas regras de privacidade:
- Perguntas e respostas completas: as respostas podem incluir valores retornados das suas fontes de conhecimento. Qualquer pessoa que possa ler a tabela de registros pode ver os dados que o agente retornou a um usuário, incluindo dados que não podem ser lidos nas tabelas de origem. Conceda acesso de leitura ao conjunto de dados de registro apenas para as pessoas que devem ver esse conteúdo.
- Identificadores de usuário e local de gravação: a coluna user_id identifica o autor da pergunta (consulte Identidade do usuário), e as linhas são gravadas apenas no destino configurado no projeto do agente.
- Tabelas com segurança no nível da linha, segurança no nível da coluna ou mascaramento de dados: se as fontes de conhecimento de um agente usarem segurança no nível da linha (políticas de acesso de linha), segurança no nível da coluna (tags de política) ou mascaramento de dados dinâmicos, as interações não serão registradas. A verificação de privacidade ignora as tabelas em bigquery-public-data e analisa apenas as tabelas e visualizações que você seleciona como fontes de conhecimento, não as tabelas por trás de uma visualização:
  - Uma visualização em uma tabela que usa essas políticas pode passar na verificação, para que as interações possam ser registradas. Antes de ativar a geração de registros, verifique se as tabelas por trás das visualizações não usam políticas de acesso de linha, tags de política ou mascaramento de dados.
  - Se você adicionar uma dessas políticas a uma tabela de origem mais tarde, as linhas que já foram registradas vão permanecer na tabela de registros. Se a política de retenção ou governança proibir a manutenção dessas linhas, exclua-as.

Controle de acesso, criptografia e segurança de rede

É possível gerenciar a retenção, o acesso, a criptografia e a segurança do perímetro dos registros de conversa usando as seguintes configurações:

Retenção e controle de acesso no conjunto de dados de registro: configure a retenção, os papéis do conjunto de dados, as políticas de tabela e os registros de auditoria para a tabela de destino:
- Retenção: o Google não exclui linhas de registro. Defina uma expiração de partição no conjunto de dados ou na tabela de registros que corresponda à sua política (por exemplo, 90 dias).
- Privilégio mínimo: mantenha o conjunto de dados de registro separado dos outros conjuntos de dados para que o acesso de gravação do agente de serviço compartilhado da API Conversational Analytics fique longe das outras tabelas. Conceda aos analistas roles/bigquery.dataViewer no conjunto de dados de registro ou dê a eles acesso apenas a visualizações autorizadas ou conjuntos de dados autorizados.
- Controles no nível da coluna e da linha na tabela de registros: é possível aplicar tags de política, mascaramento de dados ou políticas de acesso de linha à própria tabela de registros, como em content ou user_id. Esses controles de tabela de registros não afetam a verificação de privacidade da fonte de conhecimento.
- Registro de auditoria: as alterações na configuração do agente de dados e as operações da tabela de registros são registradas nos registros de auditoria. Para mais informações, consulte Operações auditadas.
CMEK, VPC Service Controls e residência de dados: os seguintes controles de criptografia, perímetro e local se aplicam à geração de registros de conversas:
- CMEK: 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 (bq-PROJECT_NUMBER@bigquery-encryption.iam.gserviceaccount.com) o papel roles/cloudkms.cryptoKeyEncrypterDecrypter na chave. A CMEK em um agente de dados criptografa o recurso do agente, não a tabela de registros (consulte Chaves de criptografia gerenciadas pelo cliente).
- VPC Service Controls: se você usar um perímetro de serviço, inclua geminidataanalytics.googleapis.com e bigquery.googleapis.com no perímetro que contém o projeto do agente. O agente de serviço grava na tabela de registros da infraestrutura gerenciada pelo Google. Portanto, se o perímetro restringir bigquery.googleapis.com, adicione uma regra de entrada como a seguinte. Substitua PROJECT_NUMBER pelo número do projeto do agente:
```
- ingressFrom:
    identities:
    - serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com
    sources:
    - accessLevel: "*"
  ingressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - permission: bigquery.tables.get
      - permission: bigquery.tables.create
      - permission: bigquery.tables.update
      - permission: bigquery.tables.updateData
    resources:
    - projects/PROJECT_NUMBER
```
  Para mais informações, consulte Configurar a segurança do perímetro com o VPC Service Controls.
- Residência de dados: as linhas de registro e a tabela criada automaticamente são armazenadas no local do conjunto de dados de registro, onde as políticas da organização de local de recursos (gcp.resourceLocations) são aplicadas.

Atribuição do agente de serviço e do autor da chamada

O agente de serviço da API Conversational Analytics, e não o usuário que está conversando, cria e atualiza a tabela de registros e adiciona linhas a ela. Para realizar essas operações, o agente de serviço precisa do papel de Editor de dados do BigQuery (roles/bigquery.dataEditor) no conjunto de dados de registro.

Nas entradas de registro de auditoria que os Registros de auditoria do Cloud registram, o campo authenticationInfo.principalEmail (ou authenticationInfo.principalSubject para identidades federadas) identifica o principal que realizou cada operação:

Registrar a criação de tabelas, atualizações de esquema e anexos de linha: o agente de serviço, service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.iam.gserviceaccount.com.
Solicitações de configuração do agente de dados (CreateDataAgent, CreateDataAgentSync, UpdateDataAgent e UpdateDataAgentSync): o usuário, a conta de serviço ou a identidade federada que chama a API. Quando as credenciais da conta de serviço delegada se aplicam, essas entradas também incluem authenticationInfo.serviceAccountDelegationInfo.

Operações auditadas

Os Registros de auditoria do Cloud registram as mudanças na configuração de registro de conversas e as operações da tabela de registros para os seguintes serviços:

API Conversational Analytics: os métodos a seguir geram registros de auditoria em geminidataanalytics.googleapis.com:
- CreateDataAgent, CreateDataAgentSync, UpdateDataAgent e UpdateDataAgentSync geram registros de auditoria de atividade do administrador que registram os campos bigqueryAgentAnalyticsEnabled e bigqueryAgentAnalyticsTable de um agente, incluindo o projeto, o conjunto de dados e a tabela de destino.
- O SetAgentOpsObservability gera registros de auditoria de atividade do administrador que registram os campos dataSourceType, telemetryEnabled, bqaaEnabled e updateMask da solicitação.
- O RetrieveAgentOpsObservability gera registros de auditoria de acesso a dados quando o tipo de registro de auditoria ADMIN_READ ou DATA_READ correspondente está ativado para geminidataanalytics.googleapis.com.
BigQuery: as operações do agente de serviço na tabela de registros e as consultas executadas nela geram os seguintes registros de auditoria:
- A criação de tabelas de registros e as atualizações de esquema geram registros de auditoria de atividades do administrador em bigquery.googleapis.com.
- As adições de linhas ao final pela API Storage Write (gRPC) geram registros de auditoria de acesso a dados para o método google.cloud.bigquery.storage.v1.BigQueryWrite.AppendRows, incluindo metadados TableDataChange (WRITE_API_APPEND_ROWS). Essas entradas usam o nome de serviço bigquery.googleapis.com, não bigquerystorage.googleapis.com. Somente os registros de auditoria de política negada usam bigquerystorage.googleapis.com.
- As consultas na tabela de registros geram registros de auditoria de acesso a dados em bigquery.googleapis.com, como as entradas JobInsertion, JobChange e TableDataRead.

Para mais informações, consulte Registros de auditoria da API Conversational Analytics e Visão geral dos registros de auditoria do BigQuery.

Limitações

A geração de registros de conversas tem as seguintes limitações:

O painel Prévia no editor de agentes do BigQuery Studio não é registrado.
As conversas diretas sem um agente de dados não são registradas.
Os agentes que usam um escopo de pesquisa em vez de tabelas específicas ou que não declaram tabelas do BigQuery não são registrados. Os agentes que configuram apenas gráficos de propriedades do BigQuery (sem tabelas do BigQuery) como fontes de conhecimento não são registrados.
O SQL gerado, as chamadas de ferramentas e os eventos de ferramentas ou solicitações do Kit de Desenvolvimento de Agente (ADK) (TOOL_STARTING, TOOL_COMPLETED, TOOL_ERROR e LLM_REQUEST) não são registrados. Somente a resposta e os nomes dos resultados de dados e gráficos são registrados. As interações respondidas diretamente de uma consulta verificada não gravam linhas LLM_RESPONSE, e as interações de consulta verificada com falha não são registradas.
O feedback do usuário com Gostei ou Não gostei não é registrado.
As interações não serão registradas se as fontes de conhecimento usarem políticas de acesso por linha, segurança no nível da coluna (tags de política) ou mascaramento de dados, incluindo políticas de dados anexadas diretamente às colunas. As interações também não serão registradas se a verificação de privacidade não puder verificar essas políticas, como quando o usuário do chat não tiver permissão para inspecionar os metadados da política de uma tabela ou se a verificação expirar. A verificação não analisa as visualizações para as tabelas por trás delas.
Somente agentes de tabela do BigQuery são compatíveis. As fontes de dados do Looker, Data Studio, AlloyDB, Spanner e Cloud SQL não são compatíveis.
O conjunto de dados de destino já precisa existir no mesmo projeto que o agente.
As alterações de esquema em tabelas atuais são apenas aditivas. Um tipo ou modo de coluna conflitante interrompe as gravações nessa tabela.
Cada turno qualificado é registrado sem uma configuração de amostragem. Em vez disso, faça a amostragem no momento da consulta (consulte Amostra de perguntas e respostas de todos os agentes para análise).
A coluna agent contém o tipo de agente, e não o nome de exibição dele. Use o ID do agente de dados em attributes.
Os autores de chamadas de API que usam uma conta de serviço para muitos usuários finais veem o e-mail dessa conta de serviço em todas as linhas.
Os valores de texto com mais de 512.000 caracteres (500 * 1,024) são cortados com o sufixo ...[TRUNCATED], e a parte removida não pode ser recuperada.
As gravações são feitas com o melhor esforço e com novas tentativas limitadas. As rodadas que não são gravadas não são registradas, e as novas tentativas podem, ocasionalmente, produzir linhas duplicadas (use event_id para eliminar duplicações).
Um agente não herda a configuração de observabilidade para envolvidos no projeto.

Preços

A análise conversacional não cobra separadamente pela geração de registros de conversas. Seu projeto paga os preços padrão do BigQuery para ingestão de dados da API BigQuery Storage Write (gRPC), armazenamento e consultas de análise. A ingestão da API BigQuery Storage Write (gRPC) inclui 2 TiB de uso sem custo financeiro por mês para cada conta de faturamento, compartilhados entre o uso da API Storage Write (gRPC). Filtre consultas em timestamp para reduzir os bytes verificados. A verificação de privacidade pré-execução lê os metadados da tabela e executa consultas de simulação sem custos financeiros.