Esquema de registro de conversas

Este documento descreve o layout da tabela, as colunas, os tipos de evento, os campos de identidade do usuário e a estrutura de payload JSON para o registro de conversas da análise de conversação no BigQuery. Para uma visão geral de como o registro de conversas funciona, consulte Visão geral do registro de conversas.

Layout de tabela e criação automática

Crie o conjunto de dados de destino no mesmo projeto que o agente de dados antes de ativar a geração de registros. O agente de serviço da API Conversational Analytics cria a tabela no local do conjunto de dados no primeiro turno registrado (ou adiciona as colunas de esquema ausentes a uma tabela compatível). A tabela criada automaticamente é particionada por dia em timestamp (herdando qualquer expiração de partição padrão no conjunto de dados) e em cluster em event_type, agent e user_id. Sempre filtre em timestamp ao consultar a tabela.

Colunas

A tabela a seguir descreve as colunas na tabela de destino de registro de conversas.

Coluna Tipo Modo Índice
timestamp TIMESTAMP REQUIRED Horário UTC do evento. Coluna de particionamento.
event_id STRING NULLABLE ID exclusivo do evento. Ele permanece o mesmo se uma gravação for repetida, para que você possa usá-lo para remover duplicatas.
event_type STRING NULLABLE Tipo de evento. Consulte Tipos de evento.
agent STRING NULLABLE O tipo de agente, não o nome ou ID do agente (por exemplo, ConversationalAnalyticsAgent). Para diferenciar os agentes, use o ID do agente de dados (consulte Campos em attributes).
session_id STRING NULLABLE Um turno, não uma conversa inteira. Todos os eventos de uma pergunta e resposta compartilham um session_id. Para agrupar as interações em conversas, use o ID da conversa em attributes.
invocation_id STRING NULLABLE Uma execução em uma rodada.
user_id STRING NULLABLE O autor da pergunta. Consulte Identidade do usuário.
trace_id STRING NULLABLE ID de trace do OpenTelemetry (32 caracteres hexadecimais).
span_id STRING NULLABLE ID desta operação na árvore de execução da vez.
parent_span_id STRING NULLABLE ID da operação pai.
content JSON NULLABLE Payload do evento. O formato depende de event_type.
content_parts RECORD REPEATED Conteúdo com várias partes, com um elemento por parte (por exemplo, mime_type, uri, object_ref, text, part_index, part_attributes e storage_mode).
attributes JSON NULLABLE Metadados: ID do agente de dados, ID da conversa, chave de usuário interna, versão do modelo e uso detalhado de tokens.
latency_ms JSON NULLABLE Medições de latência, como total_ms e time_to_first_token_ms.
status STRING NULLABLE OK ou ERROR.
error_message STRING NULLABLE Detalhes do erro. Ele também pode ser definido em linhas OK LLM_RESPONSE quando o modelo para por um motivo diferente de uma parada normal (por exemplo, quando atinge o limite máximo de tokens).
is_truncated BOOLEAN NULLABLE true se algum valor de texto no evento excedeu 512.000 caracteres (500 * 1,024) e foi cortado. Os valores de corte terminam com ...[TRUNCATED]. Não é possível recuperar a parte removida.

Tipos de evento

A tabela a seguir descreve os valores que podem aparecer na coluna event_type e as colunas ou campos JSON que armazenam os dados de cada evento.

Valor de event_type Descrição Colunas preenchidas e campos JSON
INVOCATION_STARTING Início de uma curva. Nenhum
USER_MESSAGE_RECEIVED A pergunta do usuário. content.text_summary
AGENT_RESPONSE A resposta do agente, como um objeto estruturado. content.text_summary (texto simples) e content.response (consulte Estrutura de AGENT_RESPONSE)
LLM_RESPONSE Uma linha para cada chamada de modelo, incluindo chamadas que solicitaram uma ferramenta (não gravada quando uma rodada é respondida diretamente de uma consulta verificada, em que attributes.fast_path é true). A saída do modelo não é armazenada. Tokens: content.usage.prompt, content.usage.completion, content.usage.total. Modelo: attributes.model_version. Motivo da conclusão: attributes.finish_reason. Uso detalhado: attributes.usage_metadata (por exemplo, cached_content_token_count e thoughts_token_count).
INVOCATION_COMPLETED Fim de uma rodada, com latência por rodada. content está vazio. latency_ms.total_ms
EMBEDDING_SUGGESTION Sugestões para o proprietário do agente sobre colunas que poderiam se beneficiar de embeddings. Ele aparece apenas para alguns agentes. content.reason, content.suggested_columns
INVOCATION_ERROR, AGENT_ERROR, LLM_ERROR Falha na curva. status é ERROR e content é NULL. error_message (resumo de uma linha com instruções SQL e nomes de tabelas editados)

Identidade do usuário

A coluna user_id contém o endereço de e-mail do autor da chamada: o endereço de e-mail do usuário, o endereço de e-mail de uma conta de serviço quando um autor da chamada de API se autentica com uma conta de serviço ou NULL se o autor da chamada não tiver um endereço de e-mail (como algumas identidades da federação de identidade de colaboradores). Uma chave de usuário interna também é registrada em attributes.session_metadata.user_id em cada linha, para que você possa contar usuários distintos com internal_user_key (consulte Criar a visualização de eventos entre agentes).

Para atribuir turnos aos seus próprios usuários finais ao chamar a API por uma conta de serviço, registre o mapeamento de usuários no aplicativo. A API não aceita um identificador de usuário final para geração de registros.

Campos dentro de attributes

A tabela a seguir mostra as expressões do GoogleSQL usadas para extrair campos de metadados da coluna JSON attributes.

O que é necessário Expressão do GoogleSQL
ID do agente de dados JSON_VALUE(attributes, '$.session_metadata.state."data-agent-id"')
Nome completo do recurso do agente de dados JSON_VALUE(attributes, '$.adk.app_name')
ID da conversa JSON_VALUE(attributes, '$.session_metadata.state."conversation-id"')
Chave de usuário interna JSON_VALUE(attributes, '$.session_metadata.user_id')
Versão do modelo (em LLM_RESPONSE linhas) JSON_VALUE(attributes, '$.model_version')

Estrutura de AGENT_RESPONSE

Para ler a resposta do agente como texto simples, use JSON_VALUE(content, '$.text_summary'). Ele combina as partes de Markdown, suposição e insight da resposta, além de perguntas de esclarecimento. Nas linhas AGENT_RESPONSE, content.response é um objeto JSON, não uma string. Portanto, JSON_VALUE(content, '$.response') retorna NULL.

A tabela a seguir descreve os caminhos em content.response.

Caminho em content.response Tipo Índice
parts ARRAY<JSON> A resposta, em partes.
parts[].markdown STRING Texto da resposta (Markdown).
parts[].insight STRING Um insight extraído dos dados.
parts[].assumption STRING Uma suposição feita pelo agente.
parts[].data_result_artifact_name STRING Nome de um resultado de dados.
parts[].chart_artifact_name STRING Nome de um gráfico.
followup_questions ARRAY<STRING> Sugestões de perguntas complementares.
clarifying_question STRING Defina quando o agente fez uma pergunta de esclarecimento ao usuário em vez de responder.
citation_sources JSON Fontes citadas na resposta.

A seguir