Suite di valutazione

Nota: Tu definisci le dimensioni del punteggio. Il tuo valutatore può restituire qualsiasi chiave numerica desideri; Observability memorizza, tende alla tendenza e visualizza tutto quello che invii.

​

In sintesi

1. Scrivi uno scorer. Crea un piccolo servizio HTTP che legge una trascrizione della sessione e restituisce i punteggi. Observability fornisce un riferimento funzionante che puoi copiare. Vedi Scrivere un valutatore con l’SDK.
2. Punta Observability su di esso. Imposta EVALUATOR_ENDPOINT (e un EVALUATOR_TOKEN condiviso) sul processo server.
3. Guarda i punteggi arrivare. Ogni sessione completata viene valutata automaticamente; i risultati appaiono nella pagina dei dettagli della sessione, nella griglia delle sessioni e nei dashboard salvati.

​

Come funziona

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

​

Contratto HTTP

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

​

Rotte 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

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 il tuo valutatore

​

Configurare il server

​

Riferimento API

​

Filtrare per intervallo di punteggi: 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..

​

Permessi

​

Visualizzare i risultati

• /sessions/<id>: timeline degli eventi + una barra laterale 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. Il dashboard effettua il poll per il nuovo risultato e aggiorna la barra laterale destra quando arriva.
• /sessions: griglia di sessione filtrabile; la colonna dei punteggi mostra lo stato di valutazione e i punteggi di ogni sessione a colpo d’occhio.
• /dashboards: viste di salute eval salvate (vedi Dashboard sotto).

​

Dashboard

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

​

Risoluzione dei problemi

​

Prossimi passi

• Skill agent valutatore: fai progettare a un agent di codifica le tue dimensioni in base a sessioni reali e costruisci questo servizio per te.
• Python SDK: emetti gli eventi agent_end che attivano lo scoring.
• Chiavi API: i permessi evaluations:read e evaluations:trigger.
• Audit: l’altra funzione di qualità automatizzata di Observability, per la revisione basata su policy.