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

O monitoramento on-line permite 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 na performance do agente ao longo do tempo) causado por mudanças no comportamento do usuário ou em dados externos. Ao configurar monitores on-line, é possível pontuar traces ativos 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 performance.

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 seu projeto.
  • (Opcional) Se você planeja criar monitores de forma programática, consulte a página Avaliar seus agentes para instruções de inicialização do Agent Platform SDK.

Requisitos de telemetria

O monitoramento on-line exige que o agente exporte indicadores 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 da finalidade do agente.
    • gen_ai.conversation.id: um identificador exclusivo para a 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 subjacentes.
    • gen_ai.tool.definitions: metadados sobre as ferramentas disponíveis para o agente.

Se você estiver usando o Kit de desenvolvimento de agentes, será necessário ativar 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 usar dados multimodais, como imagens ou documentos grandes, recomendamos gravar 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 isso:

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 e respostas multimodais.

Como os monitores on-line funcionam

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:amostra dados do Cloud Trace e do Cloud Logging com base nos seus filtros.
  2. Avaliação: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 Google Cloud console, acesse a página Agent Platform > 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 o agente que você quer monitorar no menu suspenso.
    • Critérios de filtro:escolha se quer avaliar todos os traces do agente ou aplicar critérios de filtro específicos.

  4. Definir 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 seu 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 acompanhar continuamente, como Segurança.

  6. Definir amostragem :

    • Porcentagem de amostragem:defina qual porcentagem do seu tráfego ativo precisa ser avaliada.
    • Amostras máximas 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 configurações preenchidas de um já existente.
  • Ver traces:clique no link Ver traces na coluna Traces amostrados de um monitor para navegar diretamente até os traces filtrados na guia Traces do agente.

Conferir resultados no painel de observabilidade

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

  1. No Google Cloud console, 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 de resposta, segurança e taxas de alucinação.

Conferir 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 Google Cloud console, acesse a guia Traces do agente.
  2. Selecione uma sessão ou trace na tabela para abrir o painel de detalhes.
  3. Selecione a guia Avaliação para conferir as pontuações e justificativas dessa interação específica.

Resolver problemas de monitores on-line

Se o monitor on-line estiver ativo, mas nenhum resultado aparecer no painel:

  1. Verificar a telemetria:verifique se o agente está exportando corretamente os períodos e eventos necessários do OpenTelemetry. Confira o Cloud Trace para saber se os traces ativos contêm os atributos gen_ai..
  2. Verificar 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. Verificar registros internos:os monitores on-line gravam informações de diagnóstico no Cloud Logging. Se uma avaliação falhar, um registro de erros será produzido. É possível encontrar esses registros na Análise de registros pesquisando 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"