Suite de Avaliação

Nota: Você define as dimensões de pontuação. Seu avaliador pode retornar quaisquer chaves numéricas que desejar; o Observability armazena, acompanha tendências e exibe tudo o que você enviar.

​

Resumo

1. Escreva um avaliador. Suba um pequeno serviço HTTP que leia a transcrição de uma sessão e retorne pontuações. O Observability inclui um exemplo funcional que você pode copiar. Veja Escrevendo um avaliador com o SDK.
2. Aponte o Observability para ele. Defina EVALUATOR_ENDPOINT (e um EVALUATOR_TOKEN compartilhado) no processo do servidor.
3. Acompanhe as pontuações. Cada sessão concluída é pontuada automaticamente; os resultados aparecem na página de detalhes da sessão, na grade de sessões e nos dashboards salvos.

​

Como funciona

• Retornar o resultado inline com {"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}. O resultado é anexado à linha do tempo de avaliações da sessão. reasoning e summary são opcionais.
• Adiar com {"status":"pending", "job_id":"abc-123"}. O Observability então chama GET {EVALUATOR_ENDPOINT}/evaluate/abc-123 até que seu avaliador retorne {"status":"done", ...} ou {"status":"error", "error":"..."}. O intervalo de polling é por job: uma resposta pending pode incluir next_poll_secs para sobrescrever o valor padrão; caso contrário, o Observability usa o valor default_poll_interval_secs de GET /config; caso contrário, o servidor recorre a EVALUATOR_POLLING_INTERVAL_SECS (padrão: 10s). Todos os valores são limitados ao intervalo [1s, 1h].

​

Contrato HTTP

• Servidor do Observability: variável de ambiente EVALUATOR_TOKEN
• Serviço avaliador: configurado da mesma forma (o SDK agenteye-evaluator lê EVALUATOR_TOKEN por convenção)

​

Rotas que o avaliador deve servir

​

Corpo EvalRequest enviado pelo servidor

{
  "schema_version": "1",
  "session_id":     "session-abc123",
  "agent_id":       "planner",
  "environment":    "production",
  "started_at":     "2026-05-10T12:00:00Z",
  "ended_at":       "2026-05-10T12:05:00Z",
  "events": [
    { "id": 1234, "ts": "...", "event_type": "agent_start", "payload": { ... } },
    ...
  ]
}

​

Formatos de resposta

{
  "status": "done",
  "scores": { "helpfulness": 0.85, "tool_efficiency": 0.6 },
  "reasoning": {
    "helpfulness": "answered the question directly with citations",
    "tool_efficiency": "called list_files three times when one would have done"
  },
  "summary": "strong answer quality, weak tool selection"
}

{ "status": "pending", "job_id": "abc-123", "next_poll_secs": 30 }

{ "status": "error", "error": "model service unavailable" }

​

Escrevendo um avaliador com o SDK

import os
from agenteye_evaluator import Evaluator, EvalRequest, EvalResponse

app = Evaluator(token=os.environ["EVALUATOR_TOKEN"])

@app.evaluator
def run(req: EvalRequest) -> EvalResponse:
    # Inspect req.events (the full session transcript) and return scores.
    tool_calls = sum(1 for e in req.events if e.event_type == "tool_use")
    return EvalResponse(
        scores={"tool_calls": float(tool_calls)},
        reasoning={"tool_calls": f"{tool_calls} tool invocations in the transcript"},
        summary="tight tool loop" if tool_calls < 5 else "agent looped on tools",
    )

​

Executando seu avaliador

​

Configurando o servidor

​

Referência da API

​

Filtragem por intervalo de pontuação: score_filters

# helpfulness em [0.5, 0.8]
GET /evaluations?score_filters=helpfulness:0.5..0.8

# tool_efficiency no máximo 0.3 (sem limite inferior)
GET /evaluations?score_filters=tool_efficiency:..0.3

# helpfulness >= 0.5 E factuality >= 0.9
GET /evaluations?score_filters=helpfulness:0.5..,factuality:0.9..

​

Permissões

​

Visualizando resultados

• /sessions/<id>: linha do tempo de eventos + painel direito exibindo as pontuações da sessão e qualquer erro da tentativa de despacho. Se sua chave tiver evaluations:trigger, um botão de re-avaliar aparece ao lado do botão de exportar, útil para sessões que nunca emitiram agent_end ou para atualizar pontuações após implantar um novo avaliador. O dashboard faz polling pelo novo resultado e atualiza o painel direito quando ele chegar.
• /sessions: grade de sessões filtráveis; a coluna de pontuação exibe o status de avaliação e as pontuações de cada sessão de forma rápida.
• /dashboards: visualizações salvas de saúde de avaliação (veja Dashboards abaixo).

​

Dashboards

• Filtros: os mesmos controles da página de sessões: ambiente, status, agente, uma janela de tempo rolante e filtros de intervalo de pontuação (chave:mín..máx).
• Uma configuração de exibição: quais chaves de pontuação destacar, os limites de saúde verde/âmbar/vermelho, quais painéis exibir e se deve condensar à avaliação mais recente por sessão.

​

Solução de problemas

​

Próximos passos

• Habilidade de agente avaliador: tenha um agente de código projetando suas dimensões a partir de sessões reais e construindo este serviço para você.
• SDK Python: emita os eventos agent_end que acionam a pontuação.
• Chaves de API: as permissões evaluations:read e evaluations:trigger.
• Auditorias: o outro recurso de qualidade automatizado do Observability, para revisão baseada em políticas.