Usar a análise de agentes do BigQuery

A análise de agentes do BigQuery é uma solução de código aberto que permite capturar, analisar e visualizar dados de interação de agentes multimodais em escala, transmitindo interações brutas de agentes, como solicitações, respostas, chamadas de ferramentas e erros, diretamente para o BigQuery. Essa solução permite realizar avaliações com tecnologia de IA, otimizar comandos de agentes e extrair memória de longo prazo para melhorar as interações futuras. A análise de agentes do BigQuery é compatível com o Kit de Desenvolvimento de Agente (ADK) e o LangGraph (pré-lançamento).

Arquitetura

A análise de agentes do BigQuery transmite dados de atividade do agente para o BigQuery usando a API BigQuery Storage Write (gRPC), que fornece streaming de registros de alta capacidade e baixa latência sem bloquear a execução do agente.

O fluxo de dados consiste nestas etapas:

  1. Captura. Use plug-ins no Kit de Desenvolvimento de Agente (ADK) ou callbacks no LangGraph para interceptar eventos de interação e capturar eventos do agente.
  2. Stream. Os eventos de interação são enviados ao BigQuery pela API Storage Write (gRPC). Se não houver um esquema padronizado, o agente vai criar um automaticamente.
  3. Consumir. Analisar e avaliar os dados registrados do agente. É possível consultar dados brutos com SQL, acompanhar métricas em painéis personalizados ou usar o SDK de análise de agentes do BigQuery para reconstruir e avaliar traces complexos de execução de agentes com várias interações.

Diagrama mostrando os dados de atividade do agente fluindo de frameworks de orquestração para o BigQuery para análise.

Benefícios da análise de agentes

  • Ative a geração de registros abrangente com uma única linha de código e automatize o gerenciamento de esquemas.
  • Registre e analise dados multimodais, como texto, imagens, vídeo e áudio, usando tabelas de objetos.
  • Monitore métricas operacionais, como consumo de tokens e latência, em um esquema robusto e predefinido.
  • Identificar oportunidades de otimização usando as funções de IA generativa e a busca vetorial do BigQuery.
  • Proteja os registros agênticos com controles de acesso granulares, mascaramento de dados e criptografia.

Maneiras de capturar dados de registro agêntico

Para capturar a telemetria de interação do agente (solicitações, respostas, chamadas de ferramentas e registros de erros) de forma nativa no BigQuery, é possível registrar dados de eventos de várias maneiras:

  • Plug-ins de framework de orquestração: use plug-ins de geração de registros padrão fornecidos pelo kit de ferramentas de orquestração de agentes. Por exemplo, o BigQueryAgentAnalyticsPlugin no Kit de Desenvolvimento de Agente (ADK) se conecta ao executor do agente para interceptar, serializar e transmitir eventos automaticamente.
  • Gerenciadores de callback de framework: integre callbacks padrão em ambientes de agentes conhecidos. Por exemplo, é possível usar o gerenciador integrado do BigQuery no LangGraph e no LangChain para interceptar e encaminhar traces.
  • Ingestão direta de API: para frameworks personalizados ou proprietários, use as bibliotecas de cliente doGoogle Cloud para transmitir eventos estruturados diretamente para a tabela de eventos usando a API Storage Write (gRPC).
  • Agentes de dados de análise de conversação: ative a geração de registros de conversas integrada ao definir as configurações de um agente de dados do BigQuery no BigQuery Studio ou pela API Conversational Analytics para transmitir automaticamente eventos de conversa para uma tabela do BigQuery de destino e analisar os registros de conversa.

Independentemente do método, todas as opções de geração de registros usam a API BigQuery Storage Write (gRPC), que tem baixa latência e alta capacidade de processamento. Essa API oferece um endpoint de streaming robusto que armazena em buffer e serializa linhas (usando o mecanismo PyArrow) de forma assíncrona na memória antes de confirmá-las, garantindo que as tarefas do pipeline de observabilidade não bloqueiem as execuções do agente voltadas ao usuário.

Maneiras de analisar dados de registro agêntico

Para entender e otimizar o desempenho do agente, analise e avalie os registros de interação das seguintes maneiras:

  • Consultas SQL diretas: execute consultas personalizadas no BigQuery para calcular métricas como consumo de tokens e latência de execução. Também é possível usar o AI.GENERATE para análise automatizada de causa raiz de erros ou realizar mesclagens com tabelas de negócios para medir o impacto nos negócios.
  • Painéis interativos: conecte ferramentas de visualização, como o Data Studio, a visualizações pré-criadas ou personalizadas do BigQuery para acompanhar a integridade do agente, as taxas de erro e as tendências de uso ao longo do tempo. Os clientes do Looker também podem usar um modelo de painel de análise de agentes do BigQuery pré-criado (Looker Block) no Marketplace do Looker.
  • Notebooks do Jupyter: explore e teste dados de registro usando bibliotecas Python, pandas ou BigFrames em ambientes interativos.
  • SDK para Python: consulte, reconstrua e audite de forma programática os traces de execução do agente diretamente no código do aplicativo ou nos pipelines de avaliação automatizados.

Exemplos de como trabalhar com dados de registro agêntico

Veja a seguir casos de uso comuns e exemplos de como trabalhar com dados de registro agêntico no BigQuery.

Observabilidade e métricas operacionais

  • Consulte os dados para detalhar os custos por fluxos de agentes e determinar se um agente específico, como um agente de refinamento, consome uma quantidade desproporcional de tokens em comparação com a contribuição dele para as respostas finais.
  • Use o agente de análise de dados conversacional do BigQuery para análise de causa raiz com tecnologia de IA executando consultas com a função AI.GENERATE. Por exemplo, "Analise este registro de conversa e explique a causa raiz da falha".

Avaliação de agentes e análise de qualidade

  • Classifique as conversas e meça a classificação do agente ao longo do tempo usando a função AI.SCORE.
  • Identifique clusters de conversa em que o agente não conseguiu ajudar os usuários usando uma consulta SQL com a Pesquisa Vetorial e, em seguida, compare-os com a intenção original do usuário. Isso ajuda a identificar lacunas nas ferramentas ou na base de conhecimento do agente.

Insights e contextualização de negócios

Para contextualizar os dados do agente, mescle a tabela agent_events com outras tabelas de negócios . Por exemplo, mostre o valor médio do pedido (VMP) dos clientes que interagiram com o agente de IA em comparação com os clientes que usaram a barra de pesquisa.

Para mais exemplos, consulte Consultas de análise avançada.

Usar um notebook do Jupyter para trabalhar com registros agênticos

Use este exemplo de notebook do Jupyter no Colab para consultar, visualizar e avaliar registros agênticos de forma interativa.

Usar o SDK de análise de agentes do BigQuery

O SDK do Analytics de agentes do BigQuery é uma biblioteca Python de código aberto que fornece uma camada de consumo e avaliação para observabilidade do agente de longo prazo. Os painéis e notebooks são excelentes para exploração ad hoc, e o SDK oferece uma maneira de analisar e auditar sistematicamente o comportamento do agente em grande escala.

O que você pode fazer com o SDK

É possível realizar as seguintes tarefas usando o SDK do Analytics de agentes do BigQuery. Para exemplos detalhados de análise de registros, consulte o repositório do GitHub para o SDK.

  • Reconstrução de traces: reconstrua logs de eventos polimórficos em cadeias causais de eventos para depurar sessões em vários turnos, incluindo chamadas aninhadas de ferramentas e LLMs.
  • Avaliação determinística e semântica: avalie a qualidade do agente com base em critérios baseados em regras, como latência, contagem de turnos e taxas de erro, além de critérios semânticos, como correção, sentimento e alucinação.
  • Correspondência de trajetória: compare os caminhos de execução reais do agente com as trajetórias ideais esperadas para verificar a eficiência das etapas e se as ferramentas foram usadas na ordem correta.
  • Monitoramento comportamental e detecção de desvios: realize análises estatísticas em saídas de agentes não determinísticas, monitore as distribuições de solicitações de usuários e detecte regressão de produção ou desvio semântico.
  • Memória de agente de longo alcance: forneça aos agentes contexto entre sessões, recuperação semântica de perfil de usuário e memória episódica com reconhecimento de orçamento de tokens armazenada nativamente no BigQuery.

Registrar e analisar a atividade do agente

A integração do SDK aos fluxos de trabalho do agente geralmente envolve as seguintes etapas:

  1. Registrar interações: anexe um plug-in de registro (como o BigQueryAgentAnalyticsPlugin no ADK) ou um gerenciador de callback no framework de orquestração do agente. Quando os usuários interagem com seu agente, os registros são transmitidos de forma assíncrona para o BigQuery usando a API Storage Write de alta capacidade de processamento (gRPC).

  2. Inicialize o cliente: conecte-se ao conjunto de dados de registro pelo SDK do Python:

    from google.cloud import bigquery
from bigquery_agent_analytics import Client

client = Client(
    project_id="YOUR_PROJECT_ID",
    dataset_id="YOUR_DATASET_ID",
    table_id="agent_events",
)

    O snippet usa os seguintes componentes:

    • client: a instância pai Client que encaminha consultas de maneira programática e gerencia conexões de banco de dados ativas.
    • project_id: o ID do projeto do Google Cloud que abriga o conjunto de dados de destino.
    • dataset_id: o nome do conjunto de dados do BigQuery que armazena os registros.
    • table_id: a tabela específica que armazena eventos de telemetria (agent_events por padrão).

  3. Reconstruir um rastro de sessão: busque uma sessão de conversa específica para visualizar e analisar a sequência exata de eventos:

    trace = client.get_session_trace(
    session_id="YOUR_SESSION_ID"
)
trace.render()

    O snippet usa os seguintes componentes:

    • trace: o objeto Trace hidratado que abriga a árvore de abrangência do DAG hierárquico reconstruída e vinculada causalmente de todas as ações do usuário e do agente.
    • YOUR_SESSION_ID: o ID exclusivo da sessão que você quer inspecionar.

  4. Executar avaliações automatizadas: pontue de forma programática as trajetórias de sessão ou verifique se há regressão em um pacote de testes de referência:

    from bigquery_agent_analytics import (
    LLMAsJudge,
    TraceFilter,
)

# Run semantic evaluations across target sessions
evaluator = LLMAsJudge.correctness()
filters = TraceFilter(session_ids=["session_1", "session_2"])

report = client.evaluate(evaluator, filters=filters)
print(f"Evaluation Pass Rate: {report.pass_rate:.2%}")

    O snippet usa os seguintes componentes:

    • evaluator: o avaliador semântico (LLMAsJudge) usado para pontuar sessões. Também é possível executar verificações SystemEvaluator baseadas em regras ou combinar avaliadores em um GraderPipeline ponderado.
    • filters: a instância TraceFilter que especifica a lista session_ids (ou janela de tempo e filtros de agente) para executar avaliações em lote no BigQuery.
    • report: o objeto EvaluationReport resultante que contém notas brutas da sessão, resumos de métricas e feedback do avaliador automático.

Integrar a análise de agentes do BigQuery ao seu fluxo de trabalho

Para integrar a análise de agentes do BigQuery ao seu fluxo de trabalho, consulte a documentação do seu framework:

A seguir