Evaluation Suite

1. Como a conclusão de sessão é detectada.
2. O contrato HTTP que o avaliador deve implementar.
3. Como configurar o servidor AgentEye.
4. Como visualizar os resultados.
5. Solução de problemas.

​

Como funciona

ingest /events  ──▶  AgentEye  ──── POST /evaluate ────▶  Serviço avaliador
   (agent_end)        server   ◀──── done | pending ────
                          │
                          │     GET /evaluate/{job_id} ─────▶
                          │     ◀──── done ──────────────
                          ▼
                     evaluations  (resultados terminais)

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

​

Contrato HTTP

• Servidor AgentEye: 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 disponibilizar

​

Body 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

pip install agenteye-evaluator

import os
from agenteye_evaluator import Evaluator, EvalRequest, EvalResponse

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

@app.evaluator
def run(req: EvalRequest) -> EvalResponse:
    # Inspecione req.events (a transcrição completa da sessão) e retorne pontuações.
    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 um avaliador no Kubernetes

​

1. Containerize seu avaliador

FROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir agenteye-evaluator uvicorn
COPY my_evaluator.py .
RUN useradd --uid 10001 --create-home --shell /usr/sbin/nologin evaluator \
    && chown -R evaluator:evaluator /app
USER evaluator
EXPOSE 9000
CMD ["uvicorn", "my_evaluator:app", "--host", "0.0.0.0", "--port", "9000"]

​

2. Crie o bearer token compartilhado

kubectl -n agenteye create secret generic evaluator-token \
  --from-literal=token="$(openssl rand -hex 32)"

​

3. Aplique os manifests de exemplo

# Edite deploy/examples/evaluator/deployment.yaml primeiro para apontar
# `image:` para o seu registry, depois:
kubectl apply -k deploy/examples/evaluator/

• Um Deployment de 2 réplicas com runAsNonRoot, sistema de arquivos raiz somente leitura, todas as capabilities removidas, liveness + readiness em /health
• Um Service ClusterIP na porta 9000
• Um template secret.example.yaml (intencionalmente excluído da Kustomization; crie o secret real fora do processo para que nenhum token vá parar no git)

​

4. Configure o AgentEye para usá-lo

EVALUATOR_ENDPOINT=http://evaluator:9000
EVALUATOR_TOKEN=<o valor gerado acima>

​

Verificação

kubectl -n agenteye port-forward svc/evaluator 9000:9000
curl -s http://localhost:9000/health   # → {"status":"ok"}

​

Configurando o servidor AgentEye

​

Referência da API

​

Filtrando 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 + um painel lateral direito mostrando as pontuações da sessão e qualquer erro da tentativa de despacho. Se sua chave tem 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 lateral quando ele chegar.
• /sessions: grade de sessões filtrável; a coluna de pontuação mostra o status de avaliação e as pontuações de cada sessão rapidamente.
• /dashboards: visualizações salvas de saúde de avaliação (veja Dashboards abaixo).

​

Dashboards

• Filtros: os mesmos controles da página de sessões: environment, status, agente, uma janela de tempo contínua e filtros de intervalo de pontuação (key:min..max).
• Uma configuração de exibição: quais chaves de pontuação destacar, os limites de saúde verde/âmbar/vermelho, quais painéis mostrar e se colapsar para a avaliação mais recente por sessão.

​

Solução de problemas