Rastrear decisões de agentes de IA com o BigQuery Graph

1. Introdução

O BigQuery Graph, o BigQuery Conversational Analytics e o SDK do BigQuery Agent Analytics estão atualmente na versão prévia do Google Cloud. O plug-in de análise de agentes do BigQuery está disponível para todos os usuários. Os exemplos neste codelab usam dados sintéticos.

À medida que os agentes de IA autônomos assumem mais responsabilidades operacionais (avaliar pedidos de empréstimo, gerenciar orçamentos de marketing, aprovar solicitações de acesso), as organizações precisam auditar e explicar as decisões deles. Reconstruir o contexto exato, as alternativas consideradas e a justificativa final da decisão de um agente é essencial para conformidade, gerenciamento de riscos e confiança operacional.

Este codelab usa o SDK do Analytics do BigQuery Agent para transformar registros de eventos de agentes brutos em um gráfico de contexto de agente , um gráfico consultável no BigQuery Graph de decisões de agentes, em uma programação, sem nenhum banco de dados de gráficos externos ou pipeline de ETL.

Termos-chave

• Trace de decisão do agente : as evidências de decisão extraídas das próprias execuções de um agente: as opções consideradas, os dados acessados e o resultado confirmado.
• Gráfico de contexto do agente : o gráfico digitado e consultável no BigQuery Graph em que esses traces são materializados. É a instância com escopo de agente do conceito de gráfico de contexto do setor (a camada durável e vinculada ao tempo do contexto de decisão que os agentes produzem e consomem). O qualificador "Agente" define o escopo para as execuções dos seus próprios agentes, em vez de uma camada de contexto empresarial.

Neste codelab, bqaa context-graph extrai os traces de decisão do agente de agent_events e os materializa em um gráfico de contexto do agente que pode ser consultado com GQL, seguindo o padrão do setor em que os gráficos de contexto são criados com base em traces de decisão.

O que você vai criar

• Um gráfico de contexto do agente (com o BigQuery Graph) que modela um fluxo de decisão de agente genérico: uma solicitação é recebida, o agente considera as opções e um resultado é confirmado.
• Uma tabela agent_events preenchida com um corpus de eventos sintéticos.
• Uma execução de bqaa context-graph em funcionamento que preenche o gráfico com esses eventos.
• Uma consulta GQL no estilo de auditoria que rastreia uma única decisão de ponta a ponta.

O que você vai aprender

• Como o plug-in de análise de agentes do BigQuery grava em agent_events.
• Como um gráfico de contexto é definido por apenas dois artefatos declarativos: um DDL de tabela e um esquema CREATE PROPERTY GRAPH.
• Como executar bqaa context-graph em um BigQuery Graph.
• Como consultar um gráfico usando GQL.
• Os recursos de nível de produção que o SDK oferece para implantações empresariais.

O que é necessário

• Ter um projeto do Google Cloud com o faturamento ativado.
• Papel de proprietário ou editor nesse projeto. Você vai criar um conjunto de dados do BigQuery e conceder o IAM.
• A CLI gcloud instalada e autenticada ou acesso ao Cloud Shell.
• Python 3.10 ou mais recente.
• Familiaridade com o SQL do BigQuery. Não é necessário ter conhecimento de GQL.

Este codelab é destinado a desenvolvedores de todos os níveis, incluindo aqueles que não conhecem o BigQuery Graph.

Os recursos criados neste codelab custam muito pouco, e a etapa final destrói tudo para que você não seja cobrado por um conjunto de dados inativo.

Duração estimada:este codelab leva aproximadamente 35 minutos para ser concluído.

2. Antes de começar

Escolher um projeto e uma região

Abra o Cloud Shell ou um terminal local:

export PROJECT_ID="your-project-id"
export REGION="us-central1"
export DATASET="agent_analytics_demo"
gcloud config set project "$PROJECT_ID"

A única variável DATASET contém a tabela agent_events bruta e as tabelas de gráficos materializadas. O uso de um conjunto de dados simplifica o codelab. As implantações de produção geralmente dividem eventos e gráficos em conjuntos de dados separados para que o IAM possa ser concedido de forma restrita por conjunto de dados.

Ative as APIs necessárias

Execute o comando abaixo para ativar as APIs usadas neste codelab:

gcloud services enable \
    bigquery.googleapis.com \
    aiplatform.googleapis.com \
    --project="$PROJECT_ID"

A API aiplatform.googleapis.com é necessária porque o caminho de extração padrão do SDK chama a função AI.GENERATE do BigQuery. Se você mudar para a extração determinística com --extraction-mode=compiled-only, essa API não será mais necessária.

Crie o conjunto de dados do BigQuery

Crie o conjunto de dados que vai conter a tabela agent_events bruta e as tabelas de gráficos materializadas:

bq --location=US mk --dataset "$PROJECT_ID:$DATASET"

Você vai receber uma mensagem de confirmação:

Dataset 'your-project-id:agent_analytics_demo' successfully created.

Se o conjunto de dados já existir, o comando vai gerar um erro inofensivo. Deixe-o no lugar.

3. Instalar o SDK

Configure um ambiente virtual do Python e instale o SDK do PyPI:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install bigquery-agent-analytics

O pacote bigquery-agent-analytics extrai a biblioteca de cliente do BigQuery. Portanto, essa é a única instalação necessária para todo o codelab.

Verifique a instalação:

bqaa context-graph --help | head -8

Você vai ver o banner da CLI.

Autenticar

Se você estiver em uma estação de trabalho:

gcloud auth login
gcloud auth application-default login

Os usuários do Cloud Shell podem pular esta etapa. As credenciais já estão configuradas.

4. Receber os artefatos do codelab

O codelab precisa de apenas dois artefatos prontos para uso: o DDL da tabela (as tabelas de gráficos físicos) e o esquema de gráfico de propriedades (CREATE PROPERTY GRAPH). Você não cria nenhum deles. O codelab os usa como estão, e o arquivo README na pasta de artefatos explica como adaptá-los ao seu próprio domínio de decisão.

O esquema de gráfico de propriedades é a única fonte da verdade para o que o gráfico contém. Você o aplica ao BigQuery uma vez. A partir daí, o gráfico implantado é o contrato. Ao materializar, bqaa context-graph lê a definição do gráfico de INFORMATION_SCHEMA.PROPERTY_GRAPHS do BigQuery (junto com os esquemas das tabelas a que ele se refere) para determinar quais entidades e relacionamentos extrair e onde gravá-los. Portanto, nenhum arquivo SQL é transmitido ao materializador.

Este codelab é independente. Portanto, não há nada para fazer o download. O comando abaixo grava o DDL do gráfico de contexto em um diretório de trabalho. O conteúdo dele é idêntico aos artefatos enviados em examples/context_graph/codelab/.

Crie o diretório de trabalho:

mkdir -p ~/context-graph-codelab
cd ~/context-graph-codelab

Grave o DDL do gráfico de contexto (context_graph_ddl.sql). Os marcadores ${PROJECT_ID} / ${DATASET} são preenchidos quando você aplica o arquivo na próxima etapa.

cat > context_graph_ddl.sql <<'SQL'

-- Node and edge table DDL for the context-graph codelab.
--
-- `bqaa context-graph` writes into these tables on every run.
-- `session_id` and `extracted_at` are SDK metadata columns that
-- `bqaa context-graph` fills automatically; they are required on
-- every table behind the graph.
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.decision_request` (
  request_id STRING, request_text STRING, requested_at TIMESTAMP,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.decision_option` (
  option_id STRING, option_label STRING, confidence FLOAT64,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.decision_outcome` (
  outcome_id STRING, status STRING, rationale STRING, decided_at TIMESTAMP,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.evaluates_option` (
  request_id STRING, option_id STRING,
  session_id STRING, extracted_at TIMESTAMP
);
CREATE TABLE IF NOT EXISTS `${PROJECT_ID}.${DATASET}.resulted_in` (
  request_id STRING, outcome_id STRING,
  session_id STRING, extracted_at TIMESTAMP
);

-- Graph DDL for the context-graph codelab.
--
-- Models a generic agent decision flow:
--   DecisionRequest -> evaluatesOption -> DecisionOption
--   DecisionRequest -> resultedIn       -> DecisionOutcome
CREATE OR REPLACE PROPERTY GRAPH `${PROJECT_ID}.${DATASET}.agent_decisions_graph`
  NODE TABLES (
    `${PROJECT_ID}.${DATASET}.decision_request` AS decision_request
      KEY (request_id)
      LABEL DecisionRequest PROPERTIES (request_id, request_text, requested_at),
    `${PROJECT_ID}.${DATASET}.decision_option` AS decision_option
      KEY (option_id)
      LABEL DecisionOption PROPERTIES (option_id, option_label, confidence),
    `${PROJECT_ID}.${DATASET}.decision_outcome` AS decision_outcome
      KEY (outcome_id)
      LABEL DecisionOutcome PROPERTIES (outcome_id, status, rationale, decided_at)
  )
  EDGE TABLES (
    `${PROJECT_ID}.${DATASET}.evaluates_option` AS evaluates_option
      KEY (request_id, option_id)
      SOURCE KEY (request_id) REFERENCES decision_request (request_id)
      DESTINATION KEY (option_id) REFERENCES decision_option (option_id)
      LABEL evaluatesOption,
    `${PROJECT_ID}.${DATASET}.resulted_in` AS resulted_in
      KEY (request_id, outcome_id)
      SOURCE KEY (request_id) REFERENCES decision_request (request_id)
      DESTINATION KEY (outcome_id) REFERENCES decision_outcome (outcome_id)
      LABEL resultedIn
  );
SQL

Confirme se o arquivo está no lugar:

ls

Você vai ver um arquivo:

context_graph_ddl.sql

O fluxo de decisão que eles descrevem tem três tipos de nós e duas bordas heterogêneas:

DecisionRequest é a pergunta que o agente recebeu. DecisionOption é uma alternativa que o agente considerou. DecisionOutcome registra a escolha confirmada e a justificativa.

5. Aplicar o esquema de gráfico de propriedades

bqaa context-graph grava em tabelas do BigQuery. Portanto, elas precisam existir antes da primeira execução. context_graph_ddl.sql cria as cinco tabelas primeiro e, em seguida, o gráfico de propriedades que as referencia (o BigQuery rejeita um CREATE PROPERTY GRAPH que aponta para tabelas que ainda não existem). Portanto, uma única aplicação configura tudo:

envsubst < context_graph_ddl.sql | bq query --use_legacy_sql=false

Você vai ver cinco resultados CREATE TABLE e um resultado CREATE PROPERTY GRAPH. O DDL é idempotente. Você pode executá-lo novamente com segurança.

Esse é o único trabalho de esquema que você faz e a única vez que esses arquivos SQL são usados. O BigQuery agora registra a definição do gráfico, e bqaa context-graph a lê de INFORMATION_SCHEMA.PROPERTY_GRAPHS por nome. Não há um arquivo separado para transmitir ao materializador, e o que você consulta com GQL e o que é materializado nunca podem se separar: eles são o mesmo gráfico implantado.

6. Gerar eventos de agente de amostra

Na produção, o plug-in de análise de agentes do BigQuery captura eventos automaticamente à medida que o agente do ADK é executado. Este snippet é apenas para referência. Não o execute neste codelab:

from google.adk.plugins import BigQueryAgentAnalyticsPlugin

plugin = BigQueryAgentAnalyticsPlugin(
    project_id="your-project-id",
    dataset_id="agent_analytics_demo",
)
runner = Runner(agent=root_agent, plugins=[plugin])

Para este codelab, você usa um pequeno gerador de eventos sintéticos que grava a mesma forma de linhas diretamente em agent_events. Execute:

bqaa seed-events \
    --project-id "$PROJECT_ID" \
    --dataset-id "$DATASET" \
    --sessions 5

O comando imprime um relatório JSON. Para cinco sessões, você vai ver "events_generated": 30, "events_inserted": 30 e "ok": true.

Visualize o corpus rapidamente: quantas sessões, quantos eventos e o período que eles abrangem, em uma linha:

bq query --use_legacy_sql=false \
    "SELECT COUNT(DISTINCT session_id) AS sessions, COUNT(*) AS events, MIN(timestamp) AS earliest_event, MAX(timestamp) AS latest_event FROM \`$PROJECT_ID.$DATASET.agent_events\`"

Para a execução padrão de cinco sessões, isso mostra cinco sessões e 30 eventos abrangendo alguns minutos. (Insira o cenário realista abaixo e a mesma consulta vai informar aproximadamente 100 sessões em cerca de três dias.)

Verifique se os eventos foram recebidos:

bq query --use_legacy_sql=false \
    "SELECT event_type, COUNT(*) AS n FROM \`$PROJECT_ID.$DATASET.agent_events\` GROUP BY event_type ORDER BY n DESC"

Você vai ver 25 linhas TOOL_COMPLETED e 5 linhas AGENT_COMPLETED. Cada sessão emite um submit_request, três evaluate_option, um commit_outcome e um AGENT_COMPLETED de fechamento: cinco eventos de ferramenta mais um terminador de agente por sessão. As linhas AGENT_COMPLETED são os terminadores de sessão que bqaa context-graph usa para detecção de eventos de terminal.

Opcional: dados de escala realista

O corpus de cinco sessões acima é intencionalmente pequeno para que a primeira execução seja rápida e barata. Quando você quiser dados com formato de produção (vários agentes e usuários distribuídos por vários dias, com sessões com falha, órfãs e truncadas), use o cenário decision-realistic. Ele é definido como padrão para 100 sessões em uma janela de 72 horas. O caminho da primeira execução acima não foi alterado.

bqaa seed-events \
    --project-id "$PROJECT_ID" \
    --dataset-id "$DATASET" \
    --scenario decision-realistic \
    --sessions 100 \
    --seed 42

session_outcome_counts do relatório JSON mostra a combinação: aproximadamente {"success": 70, "failed": 10, "orphaned": 10, "truncated": 10}.

Depois de ter esse corpus realista, o guia Conversational Analytics-first mostra como perguntar em inglês ("which requests weighed a low-confidence option?") antes de passar para GQL.

Confirme a distribuição de resultados classificando cada sessão das linhas dela (órfã = sem AGENT_COMPLETED; falha = AGENT_COMPLETED com status = 'error'; truncada = qualquer linha com is_truncated = true; caso contrário, sucesso). Uma primeira passagem classifica cada sessão e, em seguida, uma segunda agrega por resultado:

bq query --use_legacy_sql=false \
    "WITH per_session AS (SELECT session_id, CASE WHEN COUNTIF(event_type = 'AGENT_COMPLETED') = 0 THEN 'orphaned' WHEN COUNTIF(event_type = 'AGENT_COMPLETED' AND status = 'error') > 0 THEN 'failed' WHEN COUNTIF(is_truncated) > 0 THEN 'truncated' ELSE 'success' END AS outcome FROM \`$PROJECT_ID.$DATASET.agent_events\` GROUP BY session_id) SELECT outcome, COUNT(*) AS sessions FROM per_session GROUP BY outcome ORDER BY outcome"

Você vai ver aproximadamente 70 sessões bem-sucedidas, 10 com falha, 10 órfãs e 10 truncadas (além das 5 sessões bem-sucedidas do corpus da primeira execução, se você as tiver inserido anteriormente no mesmo conjunto de dados).

As 10 sessões órfãs nunca emitiram AGENT_COMPLETED. Portanto, a execução padrão de bqaa context-graph as ignora (ela materializa apenas sessões fechadas de eventos de terminal). Para que elas apareçam como session_orphaned em vez de tentar novamente para sempre, adicione --max-session-age-hours ao executar. Consulte --max-session-age-hours em Levar para produção.

Esse cenário distribui as sessões em uma janela de 72 horas de propósito. O tutorial Materializar o gráfico de contexto abaixo usa --lookback-hours 24 e é escrito para o pequeno corpus de cinco sessões da primeira execução. Portanto, as contagens exatas pressupõem que você não executou essa etapa opcional. Se você fez isso, essa é a lição pretendida: uma janela de materialização de 24 horas coleta apenas a parte recente de um backlog de vários dias. Amplie --lookback-hours para capturar as sessões mais antigas.

7. Materializar o gráfico de contexto

bqaa context-graph lê os agent_events brutos e deriva o que extrair diretamente do gráfico implantado: ele lê a definição CREATE PROPERTY GRAPH que você aplicou em Aplicar o esquema de gráfico de propriedades de INFORMATION_SCHEMA.PROPERTY_GRAPHS do BigQuery, a une aos esquemas das tabelas a que se refere, determina as entidades, os relacionamentos e os tipos de coluna e preenche as tabelas de gráficos. Você o aponta para o gráfico implantado por nome com --graph agent_decisions_graph. Não há arquivo SQL para transmitir.

Executar

bqaa context-graph localmente:

bqaa context-graph \
    --project-id "$PROJECT_ID" \
    --dataset-id "$DATASET" \
    --graph agent_decisions_graph \
    --lookback-hours 24 \
    --format json

A primeira execução lê todos os eventos na janela de lookback e grava as tabelas de gráficos. Portanto, isso pode levar alguns minutos para ser concluído.

Você vai ver um relatório JSON estruturado:

{
  "run_id": "...",
  "sessions_discovered": 5,
  "sessions_materialized": 5,
  "sessions_failed": 0,
  "rows_materialized": {
    "DecisionRequest": 5,
    "DecisionOption": 15,
    "DecisionOutcome": 5
  },
  "ok": true
}

ok: true indica que bqaa context-graph encontrou cinco sessões concluídas, extraiu o fluxo de decisão de cada uma delas usando AI.GENERATE e gravou as linhas correspondentes nas tabelas de gráficos. A extração determinística (--extraction-mode=compiled-only, abordada abaixo) retorna o mesmo formato de relatório (os mesmos campos, o mesmo ok: true), mas pula as chamadas AI.GENERATE.

Solução de problemas: extração vazia

Se você vir ok: false com error_code = "empty_extraction", a causa mais comum é que a API aiplatform.googleapis.com ainda não foi propagada ou sua conta não tem roles/aiplatform.user. Aguarde um minuto e tente novamente ou conceda o papel:

USER_EMAIL=$(gcloud auth list --filter=status:ACTIVE --format="value(account)")
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
    --member="user:$USER_EMAIL" --role="roles/aiplatform.user"

Em seguida, execute o comando bqaa context-graph acima novamente.

Verifique se o gráfico tem linhas:

bq query --use_legacy_sql=false \
    "SELECT COUNT(*) AS n FROM \`$PROJECT_ID.$DATASET.decision_request\`"

Você vai ver cinco linhas. Nas cinco sessões, há 25 nós de gráfico no total: 5 DecisionRequest, 15 DecisionOption e 5 DecisionOutcome, unidos por 15 bordas evaluatesOption e 5 bordas resultedIn (uma rede de decisão por sessão).

Duas maneiras de extrair decisões de eventos

bqaa context-graph oferece dois caminhos de extração. Escolha aquele que corresponde à sua carga de trabalho:

• Extração padrão. O caminho mais fácil. Usa AI.GENERATE do BigQuery para ler o conteúdo do evento e inferir entidades e relacionamentos. Funciona com qualquer formato de evento sem código extra. É isso que o codelab usa.
• Extração determinística (--extraction-mode=compiled-only). O caminho de menor custo e adequado para auditoria. Usa um pequeno extrator de referência do Python que você escreve uma vez para seu domínio. Sem chamadas da Vertex AI, sem cobranças por token, saída totalmente reproduzível. As implantações de produção escolhem essa opção quando a previsibilidade de custos ou a reprodutibilidade estrita são importantes.

O guia de implantação do gráfico de contexto é a referência para os dois caminhos, incluindo os detalhes do IAM e como criar um extrator de referência.

8. Consultar o trace de decisão

Com o gráfico preenchido, você pode responder à pergunta de auditoria diretamente. Considere uma concreta: "Para cada solicitação, quais opções o agente considerou e como ele resolveu?" Em GQL, essa é uma única travessia na solicitação, nas opções e no resultado.

Grave a consulta em um arquivo (traversal.sql). O marcador ${DATASET} é preenchido quando você o executa na próxima etapa:

cat > traversal.sql <<'SQL'
SELECT *
FROM GRAPH_TABLE (
  ${DATASET}.agent_decisions_graph
  MATCH
    (req:DecisionRequest) -[eo:evaluatesOption]-> (opt:DecisionOption),
    (req)                 -[ri:resultedIn]->      (out:DecisionOutcome)
  COLUMNS (
    req.request_id   AS request,
    req.request_text AS question,
    opt.option_label AS considered,
    opt.confidence   AS score,
    out.status       AS outcome,
    out.rationale    AS rationale
  )
);
SQL

Execute:

envsubst < traversal.sql | bq query --use_legacy_sql=false --max_rows=20

Você vai ver quinze linhas: três opções por solicitação, cinco solicitações. Cada linha mostra a solicitação, a opção considerada pelo agente, a pontuação de confiança, o resultado final e a justificativa.

Para ter uma visão completa de uma única decisão, filtre por request_id para receber o conjunto de linhas de que uma equipe de auditoria precisa: a pergunta recebida, as opções consideradas (com pontuações) e a justificativa confirmada.

Visualizar o gráfico no BigQuery Studio

O BigQuery Studio também pode renderizar o gráfico visualmente. Abra BigQuery Studio no console do BigQuery, execute a consulta de caminho abaixo e mude o painel de resultados para a guia Gráfico para ver a rede de decisão. Com o corpus de escala realista, você tem um mapa visual de solicitações, opções e resultados:

GRAPH agent_analytics_demo.agent_decisions_graph
MATCH p = (a)-[e]->(b)
RETURN TO_JSON(p) AS path_json

O console do BigQuery não expande variáveis de shell. Portanto, cole o nome do conjunto de dados literal. Essa consulta usa agent_analytics_demo (o valor DATASET de Antes de começar). Mude-o se você usou um conjunto de dados diferente.

Faça a mesma pergunta em inglês

Nem todos os leitores de auditoria escrevem GQL. Com o BigQuery Conversational Analytics (versão prévia), sua equipe de conformidade pode fazer o mesmo tipo de pergunta em linguagem natural e receber um card de resposta estruturado. Não há sintaxe de consulta nem junções para aprender.

Registre o agent_decisions_graph (junto com as tabelas agent_events e de decisão) como uma fonte de dados do Conversational Analytics e faça a pergunta de auditoria diretamente:

Pergunta de auditoria (em inglês): "Which requests never reached a committed outcome?"

O Conversational Analytics raciocina sobre o gráfico, grava o SQL para você e responde em inglês com uma tabela de suporte. Aqui, isso significa que todas as solicitações registradas alcançaram um resultado confirmado:

A resposta acima reflete o corpus de escala realista da etapa opcional dados de escala realista (90 solicitações materializadas, todas confirmadas). Os números exatos dependem de qual corpus você inseriu, e a execução padrão de cinco sessões mostra cinco.

Consulte a documentação do Conversational Analytics para configuração.

9. Levar para produção

A execução local acima usa o comportamento padrão, que já abrange o básico para implantações reais: cada execução deixa uma trilha de auditoria (Cloud Logging estruturado mais uma linha por execução em uma tabela de estado no conjunto de dados), as falhas temporárias são repetidas automaticamente e o progresso só avança em sessões totalmente bem-sucedidas. Portanto, não há contagem dupla.

Os controles de produção (extração determinística (--extraction-mode=compiled-only), detecção de sessões travadas (--max-session-age-hours), repetição única de uma janela anterior (--backfill --from / --to, rastreada separadamente da atualização normal para que não perturbe a programação ativa) e limite de lote por execução (--max-sessions)) são flags opcionais que você usa quando precisa delas. O guia de implantação do gráfico de contexto documenta cada um deles com a matriz completa do IAM e as programações recomendadas.

De "executar isso uma vez" para "executar isso a cada seis horas" : o SDK envia um script de implantação e um módulo do Terraform que envolvem bqaa context-graph como um job do Cloud Run acionado pelo Cloud Scheduler, com contas de serviço de menor privilégio e as concessões do IAM de que o job precisa. Siga o runbook de implantação do gráfico de contexto do agente programado para levar esse gráfico implantado a uma implantação programada com o mesmo --graph fluxo.

10. Limpar

Desfaça o que você criou para não ser cobrado por um conjunto de dados inativo:

bq rm -r -f --dataset "$PROJECT_ID:$DATASET"

Esse único comando remove o conjunto de dados, os eventos do agente, as tabelas de gráficos e a tabela de estado.

11. Parabéns

Parabéns! Você transformou registros de eventos de agentes brutos em um gráfico de contexto de agente consultável e rastreou uma única decisão de ponta a ponta, sem nenhum banco de dados de gráficos externos ou pipeline de ETL.

O mesmo padrão se aplica sempre que um agente toma decisões importantes: subscrição de crédito, autorização prévia, movimentações de orçamento de marketing, compras, atendimento ao cliente e TI interna. Para criar seu próprio gráfico de contexto do agente, copie os artefatos do codelab como ponto de partida, adapte os dois arquivos declarativos (DDL da tabela + o esquema CREATE PROPERTY GRAPH) ao seu domínio e aplique-os ao BigQuery. bqaa context-graph --graph lê o gráfico implantado de INFORMATION_SCHEMA e deriva o restante.

O que você aprendeu

• Como criar um conjunto de dados do BigQuery e aplicar um esquema de gráfico de propriedades que descreve um domínio de decisão do agente.
• Como preencher agent_events com um corpus de eventos sintéticos.
• Como executar bqaa context-graph para extrair os traces de decisão do agente em um gráfico de contexto do agente desses eventos, lendo a definição do gráfico de INFORMATION_SCHEMA.
• Como consultar o gráfico resultante em GQL e ler a resposta no estilo de auditoria.

Documentos de referência

• Repositório do SDK do Analytics do BigQuery Agent
• Artefatos do codelab e guia de adaptação
• Guia de implantação do gráfico de contexto: APIs necessárias, matriz do IAM, programações recomendadas, consultas de alerta do Cloud Monitoring e o módulo do Terraform.
• Documentação do BigQuery Graph (versão prévia).
• Documentação do BigQuery Conversational Analytics (versão prévia).