EVALUATOR_ENDPOINT सेट नहीं करते।
नोट: आप स्कोर आयाम परिभाषित करते हैं। आपका evaluator किसी भी संख्यात्मक keys को return कर सकता है; Observability जो भी आप भेजते हैं उसे store, trend, और display करता है।
एक नज़र में
- एक scorer लिखें। एक छोटी HTTP सेवा स्थापित करें जो एक session transcript पढ़ता है और scores return करता है। Observability एक कार्यशील reference ships करता है जिसे आप copy कर सकते हैं। SDK के साथ एक evaluator लिखना देखें।
- Observability को इसकी ओर निर्देशित करें। Server process पर
EVALUATOR_ENDPOINT(और एक साझाEVALUATOR_TOKEN) सेट करें। - Scores को उतरते देखें। प्रत्येक पूर्ण session स्वचालित रूप से स्कोर किया जाता है; results session detail page, sessions grid, और saved dashboards पर दिखाई देते हैं।

यह कैसे काम करता है
जब Observability SDK एक session के लिएagent_end event emit करता है, server एक evaluation को schedule करता है। फिर यह full event transcript को आपकी evaluator सेवा में POST करता है, जो निम्नलिखित में से कर सकता है:
-
Inline result return करें
{"status":"done", "scores":{...}, "reasoning":{...}, "summary":"..."}के साथ। Result को session के evaluation timeline में append किया जाता है।reasoningऔरsummaryoptional हैं। -
Defer करें
{"status":"pending", "job_id":"abc-123"}के साथ। Observability फिरGET {EVALUATOR_ENDPOINT}/evaluate/abc-123को तब तक call करता है जब तक आपका evaluator{"status":"done", ...}या{"status":"error", "error":"..."}return नहीं करता। Polling cadence per-job है: एकpendingresponse मेंnext_poll_secsशामिल हो सकता है को override करने के लिए; अन्यथा ObservabilityGET /configसेdefault_poll_interval_secsvalue का उपयोग करता है; अन्यथा serverEVALUATOR_POLLING_INTERVAL_SECS(default 10s) पर fallback करता है। सभी values को [1s, 1h] में clamp किया जाता है।
agent_end emit नहीं करते (उदाहरण के लिए, एक crashed agent process) को भी pick up किया जा सकता है: evaluator का GET /config {"inactivity_timeout_secs": 1800} return कर सकता है, और Observability किसी भी session को evaluate करेगा जो उतने समय के लिए idle गया हो। इस fallback को disable करने के लिए field को null सेट करें या इसे omit करें।
EVALUATOR_ENDPOINT unset होने पर pipeline पूरी तरह no-op है।
एक session समय के साथ multiple terminal evaluations को accumulate कर सकता है: प्रत्येक agent_end event (और dashboard से प्रत्येक manual re-eval) एक fresh evaluation row को append करता है। यह एक resumed conversation को evaluate करने का supported तरीका है: एक user एक agent को end करता है, बाद में वापस आता है, अधिक events भेजता है, agent को फिर से end करता है, और एक दूसरा evaluation पूरे updated transcript के विरुद्ध चलता है। Dashboard सबसे हाल के evaluation को headline के रूप में render करता है और prior evaluations को एक collapsible timeline के रूप में। जब एक session के लिए एक evaluation चल रहा होता है, उस session के लिए अतिरिक्त agent_end events को ignore किया जाता है; चलाए गए evaluation के complete होने के बाद अगला एक fresh evaluation को queue करेगा जैसा कि usual है।
Inactivity fallback भी resumed sessions पर re-engages करता है: यदि नए events पहले के terminal evaluation के बाद आते हैं और session फिर inactivity_timeout_secs के पिछले idle जाता है, तो एक fresh evaluation को enqueue किया जाता है।
Transient failures (5xx, 429, timeouts, network errors) को EVALUATOR_MAX_ATTEMPTS तक exponential backoff के साथ retry किया जाता है; 4xx responses terminal होते हैं। Observability multiple horizontally-scaled server instances के साथ चलाने के लिए safe है; work को partition किया जाता है इसलिए एक ही session को कभी concurrently दो बार dispatch नहीं किया जाता।
HTTP contract
प्रत्येक authenticated route bearer token auth का उपयोग करता है। एक ही value दोनों sides पर configure की जानी चाहिए:- Observability server: env var
EVALUATOR_TOKEN - Evaluator service: एक ही तरीके से configure किया गया (the
agenteye-evaluatorSDK convention के अनुसारEVALUATOR_TOKENको read करता है)
EVALUATOR_TOKEN unset है, तो server कोई Authorization header नहीं भेजता है; evaluator फिर anonymous requests को accept कर सकता है, जो internal-only network के लिए ठीक है लेकिन public internet पर discouraged है।
Routes जो evaluator को serve करना चाहिए
Server द्वारा भेजा गया EvalRequest body
Response shapes
Sync (done):reasoning (एक per-score justification map) और summary (एक overall one-paragraph narrative) दोनों optional हैं। reasoning में keys को scores में keys को mirror करना चाहिए; dashboard प्रत्येक entry को अपने score bar के अंतर्गत render करता है। Older evaluators जो केवल scores return करते हैं वह unchanged continue करते हैं; reasoning और summary बस null के रूप में read करते हैं और corresponding UI affordances को omit किया जाता है।
Async (deferred):
next_poll_secs optional है; यदि omitted है तो server /config से evaluator के default_poll_interval_secs पर fallback करता है, फिर अपने EVALUATOR_POLLING_INTERVAL_SECS env var पर।
Terminal evaluator-side error:
error को record करता है।
SDK के साथ एक evaluator लिखना
आपको HTTP contract को manually implement नहीं करना है।agenteye-evaluator Python package आपको एक typed FastAPI wrapper देता है जो auth, routing, और request/response shapes को आपके लिए handle करता है।
Failproof AI Observability एक कार्यशील reference evaluator भी ships करता है जो transcript के shape से helpfulness, tool_efficiency, और factuality को score करता है। इसे starting point के रूप में copy करें और अपने स्वयं के logic को swap करें: एक LLM judge, एक rule engine, कुछ भी जो आपकी quality bar को fit करता है।
Minimum viable evaluator:
app instance किसी भी ASGI server के अंतर्गत चलता है, इसलिए uvicorn module:app इसे start करता है।
उन evaluators के लिए जिन्हें expensive work को defer करने की आवश्यकता है, JobPending को instead return करें और एक @app.job_lookup handler को register करें; Observability server GET /evaluate/{job_id} को तब तक poll करता है जब तक आप एक terminal status return नहीं करते या EVALUATOR_MAX_POLL_DURATION_SECS cap (default 1 h) elapse न हो।
Full API reference, async pattern, और event schema को agenteye-evaluator SDK के README में document किया गया है।
अपने evaluator को चलाना
Evaluator आपकी सेवा है — Failproof AI Observability एक default evaluator ship नहीं करता है, इसलिए आप इसे जहां अपनी सेवाओं को चलाते हैं वहां build और run करते हैं। यह किसी भी ASGI server के अंतर्गत चलता है (उदाहरण के लिएuvicorn my_evaluator:app); HTTP contract से /health, /config, और /evaluate routes को serve करें, फिर server को इसकी ओर निर्देशित करें (देखें Server को configure करना)।
एक बार evaluator reachable हो जाने के बाद, GET /health {"status":"ok"} return करता है। एक agent को end-to-end चलाने के बाद, server पर GET /evaluations एक row return करता है status: "done" के साथ और scores जो आपका evaluator produce किया।
Server को configure करना
Server process पर सेट करें:
Automatic scoring को turn on करने के लिए, server पर
EVALUATOR_ENDPOINT और EVALUATOR_TOKEN दोनों सेट करें, फिर change को pick up करने के लिए इसे restart करें। EVALUATOR_ENDPOINT unset होने पर pipeline एक no-op रहता है।
ऊपर की tuning knobs optional हैं; केवल यदि आप defaults को override करना चाहते हैं तो server पर corresponding environment variables सेट करें।
API reference
Score range के अनुसार filtering: score_filters
GET /evaluations एक optional score_filters parameter accept करता है जो results को scores object के अंदर numeric values के अनुसार narrow करता है। Parameter एक comma-separated list है key:min..max entries का; किसी भी bound को omit किया जा सकता है। Multiple entries logical AND के साथ combine होते हैं। Rows जहां named key absent या non-numeric है को exclude किया जाता है। एक request में अधिकतम 20 filter entries हो सकते हैं; exceeding that HTTP 400 return करता है।
उदाहरण:
/evaluations response object के ये fields हैं:
Permissions
Bootstrap admin (
ADMIN_KEY, ADMIN_EMAIL) स्वचालित रूप से ये सभी receive करता है।
Results को देखना
/sessions/<id>: events timeline + एक right rail जो session के scores और dispatch attempt से कोई error दिखाता है। यदि आपकी key के पासevaluations:triggerहै, तो एक re-evaluate button export button के आगे दिखाई देता है, उन sessions के लिए उपयोगी जिन्होंने कभीagent_endemit नहीं किया, या एक नए evaluator को deploy करने के बाद scores को refresh करने के लिए। Dashboard नए result के लिए polls करता है और इसे जब land करता है तो right rail को update करता है।/sessions: filterable session grid; score column प्रत्येक session की evaluation status और scores को एक नज़र में दिखाता है।/dashboards: saved eval-health views (देखें Dashboards नीचे)।

Dashboards
Dashboards page (/dashboards) आपको evaluation filters के एक combination को एक named, reusable view के रूप में save करने देता है और watch करता है कि evaluations का यह slice एक नज़र में कैसे कर रहा है। Dashboards आपके पूरे organization में shared हैं; dashboards:read के साथ सभी को same set दिखाई देता है।
प्रत्येक dashboard pins करता है:
- Filters: sessions page के समान controls: environment, status, agent, एक rolling time window, और score-range filters (
key:min..max)। - एक display configuration: कौन से score keys feature करें, green/amber/red health thresholds, कौन से panels दिखाएं, और latest evaluation per session को collapse करना है या नहीं।
GET /evaluations/aggregate के माध्यम से), इसलिए numbers exact हैं rather than sampled।

dashboards:read और evaluations:read दोनों चाहिए; creating और editing के लिए dashboards:write चाहिए; deleting के लिए dashboards:delete चाहिए। Bootstrap admin को automatically ये सभी मिलते हैं।
Troubleshooting
Sessions exist लेकिन कोई evaluations create नहीं हो रहे। Confirm करें किEVALUATOR_ENDPOINT server process पर set है, कि server और evaluator same EVALUATOR_TOKEN value share करते हैं, और कि evaluator का /health endpoint server से reachable है। EVALUATOR_ENDPOINT unset होने पर pipeline एक no-op है।
In-flight evaluations pile up होते हैं। GET /evaluation-jobs को query करें in-flight queue को देखने के लिए। प्रत्येक row पर attempt_count, next_attempt_at, और last_error को inspect करें। Common causes: evaluator सेवा unreachable या 5xx return कर रही है (backoff के साथ retry), गलत EVALUATOR_TOKEN (401 terminal है), या एक async evaluator जो pending को indefinitely return करता है (नीचे देखें)।
Sessions completed लेकिन कोई terminal evaluation नहीं। GET /evaluation-jobs?status=polling को query करें; result अभी भी in flight हो सकता है। यदि एक job pending में stuck है, तो server को evaluator तक पहुंचने में trouble है; check करें कि evaluator up है और कि EVALUATOR_TOKEN matches है।
HTTP 401 from evaluator: invalid bearer token। Server पर EVALUATOR_TOKEN evaluator सेवा को configure किए गए value से match नहीं करता। उन्हें identical होना चाहिए।
Async evaluator pending को forever return करता है। Server GET /evaluate/{job_id} को तब तक poll करता है जब तक evaluator done या error return नहीं करता, या जब तक EVALUATOR_MAX_POLL_DURATION_SECS (default 1 h) elapse नहीं हो। Cap के बाद evaluation को timeout के रूप में record किया जाता है और in-flight queue से remove किया जाता है। यदि आपका evaluator legitimate रूप से default से लंबे समय की आवश्यकता है तो EVALUATOR_MAX_POLL_DURATION_SECS को raise करें।
अगले कदम
- Evaluator agent skill: एक coding agent को real sessions के विरुद्ध आपके dimensions को design करने और यह सेवा build करने दें।
- Python SDK:
agent_endevents emit करें जो scoring को trigger करते हैं। - API keys: the
evaluations:readऔरevaluations:triggerpermissions। - Audits: Observability का अन्य automated quality feature, policy-based review के लिए।

