Skip to main content
Failproof AI Observability प्रत्येक पूर्ण agent run को गुणवत्ता के लिए स्वचालित रूप से स्कोर कर सकता है: आप एक छोटी स्कोरिंग सेवा प्रदान करते हैं, और Observability बाकी को संभालता है। इसका उपयोग उन आयामों को ट्रैक करने के लिए करें जिनकी आपको परवाह है (सहायकता, tool efficiency, तथ्यात्मकता, सुरक्षा; आप चुनते हैं), regression को जल्दी पकड़ें, और agents या environments की तुलना एक नज़र में करें। स्कोरिंग opt-in है: pipeline तब तक कुछ नहीं करता जब तक आप server पर EVALUATOR_ENDPOINT सेट नहीं करते।
नोट: आप स्कोर आयाम परिभाषित करते हैं। आपका evaluator किसी भी संख्यात्मक keys को return कर सकता है; Observability जो भी आप भेजते हैं उसे store, trend, और display करता है।

एक नज़र में

  1. एक scorer लिखें। एक छोटी HTTP सेवा स्थापित करें जो एक session transcript पढ़ता है और scores return करता है। Observability एक कार्यशील reference ships करता है जिसे आप copy कर सकते हैं। SDK के साथ एक evaluator लिखना देखें।
  2. Observability को इसकी ओर निर्देशित करें। Server process पर EVALUATOR_ENDPOINT (और एक साझा EVALUATOR_TOKEN) सेट करें।
  3. Scores को उतरते देखें। प्रत्येक पूर्ण session स्वचालित रूप से स्कोर किया जाता है; results session detail page, sessions grid, और saved dashboards पर दिखाई देते हैं।
एक session detail view जिसमें evaluation summary, per-dimension score bars, और right rail में reasoning text है एक बार evaluator configure हो जाने के बाद, प्रत्येक पूर्ण run को स्कोर किया जाता है और results session के right rail में दिखाई देते हैं: शीर्ष पर summary, फिर reasoning के साथ per-dimension score bars।

यह कैसे काम करता है

जब 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 और summary optional हैं।
  • 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 है: एक pending response में next_poll_secs शामिल हो सकता है को override करने के लिए; अन्यथा Observability GET /config से default_poll_interval_secs value का उपयोग करता है; अन्यथा server EVALUATOR_POLLING_INTERVAL_SECS (default 10s) पर fallback करता है। सभी values को [1s, 1h] में clamp किया जाता है।
जो sessions कभी 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-evaluator SDK 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:
Server किसी अन्य 2xx body को protocol error के रूप में treat करता है और session के लिए एक terminal 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_end emit नहीं किया, या एक नए 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 नीचे)।
Sessions grid per-session evaluation status pills और colour-coded score badges (helpfulness, factuality, tool_efficiency, safety, coherence) के साथ Sessions grid प्रत्येक run की evaluation status और scores को एक नज़र में दिखाता है; red/amber/green badges low scores को jump out करते हैं।

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 करना है या नहीं।
प्रत्येक card matching sessions की संख्या दिखाता है, एक done/error/timeout breakdown, प्रत्येक featured score का average, और एक छोटा trend sparkline। एक dashboard को open करने से full-size panels दिखते हैं; “open in sessions” आपको sessions page में drop करता है उसी slice के लिए pre-filtered। Metrics को server-side पर पूरे matching set पर compute किया जाता है (GET /evaluations/aggregate के माध्यम से), इसलिए numbers exact हैं rather than sampled। एक eval-health dashboard जिसमें evaluator dimension per average-score bars, एक tool ok-vs-error breakdown, top tools, और एक events-per-hour trend है Permissions: viewing के लिए 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_end events emit करें जो scoring को trigger करते हैं।
  • API keys: the evaluations:read और evaluations:trigger permissions।
  • Audits: Observability का अन्य automated quality feature, policy-based review के लिए।