Suite di Valutazione

1. Come viene rilevato il completamento della sessione.
2. Il contratto HTTP che il valutatore deve implementare.
3. Configurazione del server AgentEye.
4. Visualizzazione dei risultati.
5. Risoluzione dei problemi.

​

Come funziona

ingest /events  ──▶  AgentEye  ──── POST /evaluate ────▶  Servizio valutatore
   (agent_end)        server   ◀──── done | pending ────
                          │
                          │     GET /evaluate/{job_id} ─────▶
                          │     ◀──── done ──────────────
                          ▼
                     evaluations  (risultati terminali)

• Restituire il risultato in linea con {"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}. Il risultato viene aggiunto alla timeline di valutazione della sessione. reasoning e summary sono facoltativi.
• Rinviare con {"status":"pending", "job_id":"abc-123"}. AgentEye quindi chiama GET {EVALUATOR_ENDPOINT}/evaluate/abc-123 finché il tuo valutatore non restituisce {"status":"done", ...} o {"status":"error", "error":"..."}. La cadenza del polling è per-job: una risposta pending può includere next_poll_secs per escludere; altrimenti AgentEye utilizza il valore default_poll_interval_secs da GET /config; altrimenti il server ricade su EVALUATOR_POLLING_INTERVAL_SECS (predefinito 10s). Tutti i valori sono vincolati a [1s, 1h].

​

Contratto HTTP

• Server AgentEye: variabile di ambiente EVALUATOR_TOKEN
• Servizio valutatore: configurato allo stesso modo (l’SDK agenteye-evaluator legge EVALUATOR_TOKEN per convenzione)

​

Route che il valutatore deve servire

​

Body EvalRequest inviato dal server

{
  "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": { ... } },
    ...
  ]
}

​

Forme di risposta

{
  "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" }

​

Scrivere un valutatore con l’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:
    # 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",
    )

​

Eseguire un valutatore su Kubernetes

​

1. Containerizzare il tuo valutatore

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. Creare il token bearer condiviso

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

​

3. Applicare i manifesti di esempio

# Edit deploy/examples/evaluator/deployment.yaml first to point
# `image:` at your registry, then:
kubectl apply -k deploy/examples/evaluator/

• Un Deployment con 2 repliche con runAsNonRoot, filesystem radice di sola lettura, tutte le capacità rimosse, liveness + readiness su /health
• Un servizio ClusterIP sulla porta 9000
• Un template secret.example.yaml (intenzionalmente escluso da Kustomization; crea il vero segreto out-of-band in modo che nessun token finisca in git)

​

4. Collegare AgentEye a esso

EVALUATOR_ENDPOINT=http://evaluator:9000
EVALUATOR_TOKEN=<il valore generato sopra>

​

Verifica

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

​

Configurazione del server AgentEye

​

Riferimento API

​

Filtro per intervallo di punteggio: score_filters

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

# tool_efficiency at most 0.3 (no lower bound)
GET /evaluations?score_filters=tool_efficiency:..0.3

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

​

Autorizzazioni

​

Visualizzazione dei risultati

• /sessions/<id>: timeline degli eventi + una barra destra che mostra i punteggi della sessione e qualsiasi errore dal tentativo di invio. Se la tua chiave ha evaluations:trigger, appare un pulsante re-evaluate accanto al pulsante di esportazione, utile per sessioni che non hanno mai emesso agent_end, o per aggiornare i punteggi dopo aver distribuito un nuovo valutatore. La dashboard esegue il polling del nuovo risultato e aggiorna la barra destra quando arriva.
• /sessions: griglia delle sessioni filtrabile; la colonna dei punteggi mostra lo stato della valutazione di ogni sessione e i punteggi a colpo d’occhio.
• /dashboards: viste di salute eval salvate (vedi Dashboards sotto).

​

Dashboard

• Filtri: gli stessi controlli della pagina delle sessioni: ambiente, stato, agente, una finestra temporale mobile, e filtri di intervallo di punteggio (key:min..max).
• Una configurazione di visualizzazione: quali chiavi di punteggio presentare, le soglie di salute verde/ambra/rossa, quali pannelli mostrare, e se comprimere alla valutazione più recente per sessione.

​

Risoluzione dei problemi