Avaliação contínua com monitores on-line

Com o monitoramento on-line, você pode avaliar continuamente a qualidade dos seus agentes em produção. Essa abordagem proativa ajuda a identificar o desvio de qualidade, uma diminuição observável no desempenho do agente ao longo do tempo, causada por mudanças no comportamento do usuário ou em dados externos. Ao configurar os Monitores on-line, é possível pontuar traces em tempo real de forma assíncrona usando métricas predefinidas e personalizadas, garantindo que o agente permaneça confiável e alinhado aos seus padrões de desempenho.

Antes de começar

Para ativar o monitoramento on-line dos seus agentes, verifique se os seguintes requisitos foram atendidos:

  • Implante o agente conforme descrito em Implantar um agente.
  • Verifique se o Cloud Trace está ativado no projeto.
  • (Opcional) Se você planeja criar monitores de forma programática, consulte a página Avaliar seus agentes para ver as instruções de inicialização do SDK da plataforma de agentes.

Requisitos de telemetria

O monitoramento on-line exige que o agente exporte sinais específicos do OpenTelemetry para fornecer o contexto necessário para a avaliação:

  1. Período de invocação do agente: precisa incluir os seguintes atributos:

    • gen_ai.agent.name: o identificador do agente.
    • gen_ai.agent.description: uma breve descrição do propósito do agente.
    • gen_ai.conversation.id: um identificador exclusivo da sessão de conversa específica.

  2. Eventos de inferência: o evento gen_ai.client.inference.operation.details precisa capturar:

    • gen_ai.input.messages: os comandos enviados ao agente.
    • gen_ai.output.messages: as respostas geradas pelo agente.
    • gen_ai.system_instructions: os comandos do sistema.
    • gen_ai.tool.definitions: metadados sobre as ferramentas disponíveis para o agente.

Se você estiver usando o Kit de Desenvolvimento de Agente, ative esses recursos de telemetria definindo as seguintes variáveis de ambiente:

OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'

Gravação de mídia no Cloud Storage

Se o agente usa dados multimodais, como imagens ou documentos grandes, recomendamos registrar as entradas e saídas em um bucket do Cloud Storage em vez de incorporá-las diretamente em períodos de trace. Configure as seguintes variáveis de ambiente para ativar esse recurso:

OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl'
OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK='upload'
OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH='gs://STORAGE_BUCKET_NAME/PATH'

Para mais informações, consulte Coletar comandos multimodais e respostas.

Como funcionam os monitores on-line

Os monitores on-line são executados em um loop de avaliação programado, geralmente a cada 10 minutos. O loop segue estas etapas:

  1. Consulta:coleta dados de amostra do Cloud Trace e do Cloud Logging com base nos seus filtros.
  2. Avaliar:executa métricas configuradas usando o serviço de avaliação da Gemini Enterprise Agent Platform.
  3. Relatório:grava os resultados de volta no Cloud Logging e exporta pontuações numéricas para o Cloud Monitoring.

Criar um monitor on-line

  1. No console do Cloud de Confiance , acesse a página Plataforma de agentes > Agentes > Avaliação.

    Acessar a avaliação

  2. Selecione a guia Monitores on-line e clique em Novo monitor.

  3. Especificar traces de filtro:

    • Mecanismo do agente:selecione no menu suspenso o agente que você quer monitorar.
    • Critérios de filtro:escolha se quer avaliar Todos os traces do agente ou aplicar Critérios de filtro específicos.

  4. Defina os critérios de filtro (se estiver usando traces filtrados):

    • Inspeção inicial:selecione um período (por exemplo, Último dia) para visualizar os traces de produção que correspondem ao filtro.
    • Filtros:insira critérios para segmentar um tráfego específico. É possível filtrar por propriedades como Duration (por exemplo, Duration > 2) ou Token usage.

  5. Configurar métricas:adicione as métricas que você quer monitorar continuamente, como Segurança.

  6. Definir amostragem:

    • Porcentagem de amostragem:defina qual porcentagem do tráfego ativo precisa ser avaliada.
    • Máximo de amostras por execução:defina um limite para gerenciar os custos de avaliação.

  7. Clique em Criar.

Gerenciar monitores

Depois de criar um monitor, você pode gerenciá-lo na lista Monitores on-line:

  • Alternância de status:clique em Mais opções e selecione Ativar ou Desativar para pausar a avaliação sem excluir a configuração.
  • Pausar e retomar:use Mais opções para interromper temporariamente a avaliação.
  • Duplicar:crie um novo monitor com as configurações preenchidas automaticamente de um monitor atual.
  • Ver traces:clique no link Ver traces na coluna Traces de amostra de um monitor para navegar diretamente para os traces filtrados na guia Traces do agente.

Ver resultados no painel de observabilidade

Para conferir as métricas de avaliação com outros indicadores de performance:

  1. No console do Cloud de Confiance , acesse a página Agent Platform > Agentes.
  2. No menu de navegação à esquerda, selecione Implantações.

  3. Selecione seu agente.

    Acessar "Implantações"

  4. Na visualização Painel, selecione a subseção Avaliação para conferir gráficos de séries temporais das métricas configuradas, como qualidade da resposta, segurança e taxas de alucinação.

Ver resultados de traces individuais

Também é possível inspecionar os resultados da avaliação de conversas específicas diretamente na visualização de traces:

  1. No console do Cloud de Confiance , acesse a guia Traces do agente.
  2. Selecione uma sessão ou um trace na tabela para abrir o painel de detalhes.
  3. Selecione a guia Avaliação para ver as pontuações e as justificativas dessa interação específica.

Resolver problemas de monitores on-line

Se o Monitor Online estiver ativo, mas nenhum resultado aparecer no painel:

  1. Verifique a telemetria:confira se o agente está exportando corretamente os períodos e eventos necessários do OpenTelemetry. Verifique o Cloud Trace para ver se os traces ao vivo contêm os atributos gen_ai..
  2. Verifique os filtros:revise os critérios de filtro do monitor. Use o recurso Inspeção inicial para confirmar se os filtros correspondem ao tráfego de produção.

  3. Verifique os registros internos:os monitores on-line gravam informações de diagnóstico no Cloud Logging. Se uma avaliação falhar, um registro de erro será gerado. Para encontrar esses registros na Análise de registros, pesquise o ID do monitor ou traces e agentes específicos:

    resource.labels.online_evaluator="projects/YOUR_PROJECT_ID/locations/YOUR_REGION/onlineEvaluators/YOUR_MONITOR_ID"
# Or search by trace or agent
labels.trace="YOUR_TRACE_ID"
labels.reasoning_engine_id="YOUR_AGENT_ID"