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 interações futuras. A análise de agentes do BigQuery é compatível com o Kit de Desenvolvimento de Agentes (ADK) e o LangGraph (versão prévia).

Arquitetura

A análise de agentes do BigQuery transmite dados de atividade de agentes para o BigQuery usando a API BigQuery Storage Write, que oferece 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 Agentes (ADK) ou callbacks no LangGraph para interceptar eventos de interação e capturar eventos de agentes.
  2. Stream. Os eventos de interação são enviados ao BigQuery pela API Storage Write. Se um esquema padronizado não existir, o agente vai criar um automaticamente.
  3. Efetivar. Analise e avalie os dados de agentes registrados. É 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 rastros complexos de execução de agentes de várias rodadas.

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

Benefícios da análise de agentes

  • Ative o registro 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.
  • Acompanhe métricas operacionais, como consumo de tokens e latência, em um esquema robusto e predefinido.
  • Identifique oportunidades de otimização usando as funções de IA generativa e a pesquisa vetorial do BigQuery.
  • Proteja os registros de agentes com controles de acesso refinados, mascaramento de dados e criptografia.

Maneiras de capturar dados de registro de agentes

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 registro padrão fornecidos pelo kit de ferramentas de orquestração de agentes. Por exemplo, o BigQueryAgentAnalyticsPlugin no Kit de Desenvolvimento de Agentes (ADK) se conecta ao executor de agentes para interceptar, serializar e transmitir eventos automaticamente.
  • Handlers de callback de framework: integre callbacks padrão em ambientes de agentes populares. Por exemplo, é possível usar o handler integrado do BigQuery no LangGraph e no LangChain para interceptar e encaminhar rastros.
  • Ingestão direta de API: para frameworks personalizados ou proprietários, use as Cloud de Confiance by S3NS bibliotecas de cliente para transmitir eventos estruturados diretamente para a tabela de eventos usando a API Storage Write.

Independentemente do método, todas as opções de registro usam a API BigQuery Storage Write de baixa latência e alta capacidade. Essa API fornece 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 rodadas de execução do agente voltadas para o usuário.

Maneiras de analisar dados de registro de agentes

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

Exemplos de como trabalhar com dados de registro de agentes

A seguir, apresentamos casos de uso comuns e exemplos de como trabalhar com dados de registro de agentes no BigQuery.

Observabilidade e métricas operacionais

  • Consulte 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 para as respostas finais.
  • Use o agente de análise conversacional do BigQuery para análise de causa raiz com tecnologia de IA executando consultas com a AI.GENERATE função. Por exemplo: "Analise este registro de conversa e explique a causa raiz da falha".

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

  • Classifique conversas e meça a classificação do agente ao longo do tempo usando a AI.SCORE função.
  • Identifique clusters de conversas em que o agente não conseguiu ajudar os usuários usando uma consulta SQL com a pesquisa vetoriale 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 de negócios e contextualização

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 (AOV, na sigla em inglês) para clientes que interagiram com o agente de IA em comparação com clientes que usaram a barra de pesquisa.

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

Usar um notebook Jupyter para trabalhar com registros de agentes

Use este exemplo de notebook Jupyter do Colab para consultar, visualizar e avaliar registros de agentes de forma interativa.

Usar o SDK de análise de agentes do BigQuery

O SDK de análise de agentes do BigQuery é uma biblioteca Python de código aberto que fornece uma camada de consumo e avaliação para observabilidade de agentes 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 escala.

O que é possível fazer com o SDK

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

  • Reconstrução de rastros: reconstrua registros de eventos polimórficos em cadeias causais de eventos para depurar sessões em várias rodadas, incluindo chamadas aninhadas de ferramentas e LLM.
  • Avaliação determinística e semântica: avalie a qualidade do agente em relação a critérios baseados em regras, como latência, contagem de rodadas e taxas de erro, bem como 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 douradas esperadas para verificar a eficiência da etapa e se as ferramentas foram usadas na ordem correta.
  • Monitoramento comportamental e detecção de desvio: realize análises estatísticas em saídas de agentes não determinísticas, monitore 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 prazo: 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 registrador de eventos (como o BigQueryAgentAnalyticsPlugin no ADK) ou um gerenciador de callback no framework de orquestração de agentes. Quando os usuários interagem com o agente, os registros são transmitidos de forma assíncrona para o BigQuery usando a API Storage Write de alta capacidade.

  2. Inicializar o cliente: conecte-se ao conjunto de dados de registro do 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 forma programática e gerencia conexões de banco de dados ativas.
    • project_id: o Cloud de Confiance by S3NS ID do projeto que hospeda o conjunto de dados de destino.
    • dataset_id: o nome do conjunto de dados do BigQuery que armazena 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 revisar a sequência exata de eventos:

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

    O snippet usa os seguintes componentes:

    • trace: o objeto Trace hidratado que hospeda a árvore de extensão DAG hierárquica vinculada causalmente reconstruída 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 trajetórias de sessão de forma programática ou verifique a regressão em relação a um conjunto de testes dourado:

    from bigquery_agent_analytics.evaluators import CodeEvaluator, LLMAsJudge
from bigquery_agent_analytics.grader_pipeline import GraderPipeline

# Create a grader pipeline with deterministic and semantic metrics
evaluator = GraderPipeline(
    graders=[
        CodeEvaluator.latency(threshold_ms=5000),
        LLMAsJudge.correctness(),
    ]
)
report = client.evaluate(evaluator, session_ids=["session_1", "session_2"])
print(f"Evaluation Pass Rate: {report.pass_rate:.2%}")

    O snippet usa os seguintes componentes:

    • evaluator: a lógica compilada GraderPipeline estruturada que compõe métricas de avaliação semântica e baseada em regras heterogêneas.
    • session_ids: a lista de strings de ID de sessão para executar avaliações em lote no BigQuery.
    • report: o objeto EvaluationReport resultante que contém notas de sessão brutas, resumos de métricas, estatísticas de teste e feedback do avaliador automático.

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

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

A seguir