> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # Evaluator sdk title: "Evaluator SDK" description: "Costruisci un servizio che assegna punteggi alle sessioni di Failproof AI in modo sincrono o asincrono." icon: "gauge" ------------- Un evaluator riceve una sessione agente completata e restituisce i segnali di qualità che ti interessano: punteggi numerici, una spiegazione per ogni punteggio e un riepilogo facoltativo. Failproof AI memorizza questi risultati accanto alla traccia e li traccia su agenti e ambienti. ## Configura un evaluator Installa l'SDK e il server utilizzato per eseguirlo. ```bash theme={null} pip install failproofai-sdk uvicorn ``` Crea `evaluator.py`. Questo esempio verifica se una sessione contiene chiamate a strumenti fallite. ```python theme={null} import os from failproofai.evaluator import Evaluator, EvalResponse app = Evaluator(token=os.environ.get("EVALUATOR_TOKEN")) @app.config def config(): return {"inactivity_timeout_secs": 1800} @app.evaluator def evaluate(req): tool_errors = sum( 1 for item in req.events if item.event_type == "tool_result" and item.payload.get("error") ) return EvalResponse( scores={"tool_reliability": 1.0 if tool_errors == 0 else 0.0}, reasoning={"tool_reliability": f"{tool_errors} tool errors"}, ) ``` Imposta un token condiviso, avvia l'evaluator e conferma che il suo endpoint di salute risponde. ```bash theme={null} export EVALUATOR_TOKEN= uvicorn evaluator:app --host 0.0.0.0 --port 8080 ``` In un altro terminale: ```bash theme={null} curl http://127.0.0.1:8080/health ``` ## Connetti l'evaluator a Failproof AI 1. Distribuisci l'evaluator a un URL HTTPS raggiungibile da Failproof AI Cloud. 2. Configura `EVALUATOR_ENDPOINT` con quell'URL e imposta `EVALUATOR_TOKEN` sullo stesso token utilizzato dall'evaluator. Per Cloud gestito, contatta [support@befailproof.ai](mailto:support@befailproof.ai) per configurare la connessione. 3. Esegui una valutazione e conferma che i suoi punteggi appaiono in Failproof AI. Apri una sessione completata in **Observe → Sessions** e seleziona **Run evaluation** se non è stata valutata automaticamente. Rivedi lo stato, i punteggi, le motivazioni e il riepilogo nel pannello **Evaluation** della sessione. Utilizza **Observe → Evaluations** per confrontare i punteggi tra agenti o ambienti. Utilizza **Observe → Metrics** per latenza, costo, token e altre misurazioni numeriche. Inizia con una sessione per confermare che l'evaluator ha restituito le chiavi di punteggio previste e motivazioni utili per quella specifica esecuzione. Una vista di dettaglio della sessione che mostra punteggi di valutazione e motivazioni accanto alla sua traccia. Una volta che i risultati individuali appaiono corretti, utilizza il dashboard di valutazione per confrontare quei punteggi nel tempo e tra agenti o ambienti. Un dashboard di qualità che traccia i punteggi dell'evaluator nel tempo. Un grafico integro dovrebbe utilizzare nomi di punteggio stabili; modificare una chiave crea una serie separata. ```bash theme={null} fp evals --since 1h --score tool_reliability:0..1 fp evals --since 24h --aggregate ``` Per un'istanza Cloud self-hosted, la valutazione automatica è disabilitata fino a quando `EVALUATOR_ENDPOINT` non viene impostato nel processo del server. Riavvia il server dopo aver modificato le variabili di ambiente dell'evaluator. Il servizio espone `GET /health`, `GET /config`, `POST /evaluate` e facoltativamente `GET /evaluate/{job_id}`. Restituisci `JobPending` per il lavoro asincrono e registra `@app.job_lookup` in modo che Failproof AI possa eseguire il polling. Quando un token è configurato, tutte le rotte ad eccezione di health richiedono lo stesso bearer token che Failproof AI invia come `EVALUATOR_TOKEN`. ## Tipi SDK | Tipo | Campi | | ----------------- | --------------------------------------------------------------------------------------------- | | `AgentEvent` | `id`, `ts`, `event_type`, `payload` | | `EvalRequest` | `schema_version`, `session_id`, `agent_id`, `environment`, `started_at`, `ended_at`, `events` | | `EvalResponse` | `scores`, `reasoning`, `summary` | | `JobPending` | `job_id`, `next_poll_secs` | | `EvaluatorConfig` | `inactivity_timeout_secs`, `default_poll_interval_secs` | ## Decoratori e rotte | Decoratore | Rotta | Obbligatorio | | ----------------- | ------------------------ | ------------------------------- | | `@app.evaluator` | `POST /evaluate` | Sì | | `@app.job_lookup` | `GET /evaluate/{job_id}` | Quando restituisci `JobPending` | | `@app.config` | `GET /config` | No | L'SDK limita i corpi delle richieste di valutazione a 25 MiB. I campi di richiesta sconosciuti vengono ignorati in modo che i servizi rimangono compatibili con la crescita del contratto degli eventi. ## Restituisci lavoro asincrono Utilizza `JobPending` quando la valutazione non può completarsi all'interno di una richiesta. L'ID del lavoro è opaco per Failproof AI e deve rimanere risolvibile dal tuo servizio fino a quando il risultato non viene raccolto o il timeout del server non scade. ```python theme={null} from failproofai.evaluator import EvalRequest, EvalResponse, Evaluator, JobPending app = Evaluator(token="shared-secret") @app.evaluator def start(req: EvalRequest) -> JobPending: job_id = enqueue(req) return JobPending(job_id=job_id, next_poll_secs=30) @app.job_lookup def lookup(job_id: str): result = get_result(job_id) if result is None: return JobPending(job_id=job_id, next_poll_secs=30) return EvalResponse( scores=result.scores, reasoning=result.reasoning, summary=result.summary, ) ``` La cadenza di polling è selezionata in questo ordine: `JobPending.next_poll_secs`, `EvaluatorConfig.default_poll_interval_secs`, poi `EVALUATOR_POLLING_INTERVAL_SECS` del server. I valori sono limitati tra 1 secondo e 1 ora. Il limite di polling a orologio da parete predefinito del server è un'ora. ## Campi di richiesta e risposta | Campo | Tipo | Note | | --------------------------------------- | -------------------------- | ---------------------------------------------------------------------- | | `EvalRequest.schema_version` | `str` | Attualmente `1`. | | `session_id`, `agent_id`, `environment` | `str` | Identità sessione e ambiente. | | `started_at` | `datetime` | Timestamp del primo evento. | | `ended_at` | `datetime \| None` | Presente quando la sessione ha emesso un evento di fine. | | `events` | `list[AgentEvent]` | Flusso di eventi completo e ordinato. | | `AgentEvent.id` | `int` | Identificatore della riga di evento del backend. | | `AgentEvent.ts` | `datetime` | Timestamp dell'evento. | | `AgentEvent.event_type` | `str` | Famiglia di eventi come `tool_use`. | | `AgentEvent.payload` | `dict[str, Any]` | Payload completo dell'evento. | | `EvalResponse.scores` | `dict[str, float] \| None` | Dimensioni numeriche tracciate nelle valutazioni. | | `EvalResponse.reasoning` | `dict[str, str] \| None` | Spiegazioni per punteggio; le chiavi dovrebbero rispecchiare `scores`. | | `EvalResponse.summary` | `str \| None` | Narrazione di valutazione complessiva. | ## Impostazioni dell'operatore del server La valutazione automatica è valida a livello di distribuzione e rimane disabilitata quando `EVALUATOR_ENDPOINT` è assente. | Variabile | Predefinito | Scopo | | ---------------------------------- | ------------- | -------------------------------------------------------- | | `EVALUATOR_ENDPOINT` | non impostato | URL di base del servizio evaluator. | | `EVALUATOR_TOKEN` | non impostato | Bearer token condiviso con `Evaluator(token=...)`. | | `EVALUATOR_WORKERS` | `2` | Worker dispatcher concorrenti. | | `EVALUATOR_CLAIM_BATCH` | `4` | Sessioni rivendicate per passaggio del dispatcher. | | `EVALUATOR_POLLING_INTERVAL_SECS` | `10` | Cadenza di polling asincrono di fallback. | | `EVALUATOR_REQUEST_TIMEOUT_MS` | `30000` | Timeout dell'evaluator per richiesta. | | `EVALUATOR_MAX_ATTEMPTS` | `5` | Tentativi di consegna prima dell'errore terminale. | | `EVALUATOR_CONFIG_REFRESH_SECS` | `300` | Cadenza di aggiornamento per `/config`. | | `EVALUATOR_MAX_POLL_DURATION_SECS` | `3600` | Tempo massimo di polling asincrono a orologio da parete. | Il server può anche vincolare quali organizzazioni utilizzano l'evaluator globale a livello di distribuzione. Considerare le modifiche all'endpoint, token, retry e organizzazione come configurazione dell'operatore e riavviare o ridistribuire il server dopo aver modificarle. ## Sicurezza e operazioni * Metti l'evaluator dietro HTTPS quando il traffico attraversa un confine di rete attendibile. * Configura un bearer token non vuoto e mantienilo identico su entrambi i servizi. * Non registrare il token o i prompt sensibili completi dai payload delle richieste. * Rendi gli handler sincroni idempotenti; i tentativi possono ripetere una richiesta. * Persisti lo stato del lavoro asincrono al di fuori della memoria del processo in produzione. * Restituisci chiavi di punteggio stabili. Rinominare una chiave crea una nuova serie di grafici piuttosto che modificare quella vecchia. L'SDK emette log del ciclo di vita strutturati come `eval received`, `eval responded`, `job lookup`, `config returned`, `auth rejected` e eccezioni del gestore. Non configura gestori di logging; utilizza la configurazione di logging dell'applicazione host.