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

Com o monitoramento on-line, é possível 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 Monitores on-line, você pode pontuar traces ativos de forma assíncrona usando métricas predefinidas e personalizadas, garantindo que seu 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 são 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 SDK da plataforma de agentes.

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 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 subjacente.
    • gen_ai.tool.definitions: metadados sobre as ferramentas disponíveis para o agente.

Se você estiver usando o Kit de desenvolvimento de agentes, 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'

Como gravar 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 nos intervalos de rastreamento. 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 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 as métricas configuradas usando o serviço de avaliação da plataforma de agentes do Gemini Enterprise.
  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 Google Cloud , navegue até a página Plataforma de agente > Agentes > Avaliação.

    Acessar "Avaliação"

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

  3. Especificar rastreamentos de filtro:

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

  4. Definir critérios de filtro (se estiver usando rastreamentos filtrados):

    • Inspeção inicial:selecione um período (por exemplo, Último dia) para visualizar os rastreamentos 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 em tempo real 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:

  • Botão de 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 pré-preenchidas de um monitor existente.
  • Ver rastreamentos:clique no link Ver rastreamentos na coluna Rastreamentos coletados por amostragem de um monitor para navegar diretamente até os rastreamentos filtrados na guia Rastreamentos do agente.

Ver resultados no painel de observabilidade

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

  1. No console Google Cloud , navegue até a página Plataforma de agente > 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érie temporal 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 rastreamentos:

  1. No console Google Cloud , acesse a guia Rastreamentos do agente.
  2. Selecione uma sessão ou um rastreamento 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:confira se o agente está exportando corretamente os intervalos e eventos necessários do OpenTelemetry. Verifique o Cloud Trace para saber se os rastreamentos ativos contêm os atributos gen_ai..
  2. Verificar filtros:revise os critérios de filtro do seu 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á 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"