कस्टम agents

हर सेटिंग, मेथड और फील्ड क्या करता है। यदि आप पहली बार instrumentation कर रहे हैं, तो गाइड से शुरू करें — यह पृष्ठ चीजों को देखने के लिए है।

कस्टम agents गाइड

इंस्टॉल, instrumentation, इवेंट मेथड, एक व्यावहारिक उदाहरण, और सामान्य समस्याएं।

कोई फ्रेमवर्क उपयोग कर रहे हैं?

LangChain, CrewAI, LlamaIndex और Pydantic AI एक कॉल के साथ खुद को instrument करते हैं।

Python 3.10 या नया। कोई runtime dependency नहीं।

इंस्टॉल करें

pip install failproofai-sdk

पैकेज को failproofai-sdk के रूप में इंस्टॉल किया जाता है और Python में failproofai_sdk के रूप में आयात किया जाता है। फ्रेमवर्क extras जैसे failproofai-sdk[langgraph] फ्रेमवर्क को ही इंस्टॉल करते हैं; adapters हमेशा base wheel में शिप होते हैं।

Failproof daemon को कनेक्ट करें

डैशबोर्ड
CLI

Admin → Keys पर जाएं और events:add के साथ एक key बनाएं।
Failproof daemon को Cloud से कनेक्ट करें agent मशीन पर।
एक instrumented सेशन चलाएं, फिर Observe → Events के तहत इसकी सटीक ID खोजें।
Observe → Sessions पर जाएं, एक ही environment चुनें, और पुनर्निर्मित trace खोलें।

events:add key को shell में पढ़ें। read -s इसे एक प्रॉम्प्ट पर लेता है जो echo नहीं करता, इसलिए यह कभी command में या shell history में दिखाई नहीं देता:

read -rs FAILPROOFAI_CLOUD_TOKEN && export FAILPROOFAI_CLOUD_TOKEN

फिर मशीन को सेट अप करें और जांचें कि यह कनेक्ट हुआ:

failproofai config
failproofai config --status

कॉन्फ़िगरेशन

import failproofai_sdk

failproofai_sdk.configure(
    base_dir=None,
    flush_interval=0.5,
    environment="production",
)

Argument	यह क्या करता है
`environment`	हर event पर लेबल — `production`, `staging`, `prod-eu`। डिफ़ॉल्ट `dev` है।
`flush_interval`	बैकग्राउंड thread कितनी बार disk में लिखता है, सेकंड में। डिफ़ॉल्ट `0.5` है।
`base_dir`	कहाँ लिखना है। डिफ़ॉल्ट daemon का spool है, जो आप चाहते हैं जब तक आप अन्यथा न जानते हों।

इसके बजाय environment variable द्वारा सेट करें:

Variable	यह क्या करता है
`AGENTEYE_ENVIRONMENT`	कोड परिवर्तन के बिना `environment` सेट करता है, जब लेबल deployment के बजाय app से संबंधित हो। एक `configure()` argument इसे ओवरराइड करता है।
`FAILPROOFAI_HOME`	Failproof AI root को स्थानांतरित करता है जो spool रखता है।
`FAILPROOFAI_SDK_STRICT`	`1` instrumentation errors को log किए जाने की जगह raise करता है।
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1` एक framework-compatibility समस्या को warn करने और जारी रखने की जगह raise करता है।

environment में कोई comma नहीं। Ingest उस फील्ड को commas पर split करता है इसके filters बनाने के लिए, और किसी भी event को skip करता है जिसके लेबल में एक है — इसलिए एक पूरा run चुप चाप गायब हो जाता है। prod,eu नहीं, prod-eu लिखें।configure(environment="prod,eu") raise करता है इसलिए आप तुरंत पता चलता है। AGENTEYE_ENVIRONMENT raise नहीं कर सकता — कोई आपको कॉल नहीं कर रहा — इसलिए यह एक बार warn करता है और dev पर वापस जाता है।

Events को memory में queue किया जाता है और हर flush_interval सेकंड में बैकग्राउंड में लिखा जाता है, interpreter exit पर एक final flush के साथ। एक प्रक्रिया जो सीधे kill की जाती है, वह कुछ खो देती है जो अभी तक लिखी नहीं गई थी।

Identity

हर event एक session और एक agent से संबंधित है। Scopes दोनों को भरते हैं, इसलिए आप शायद ही कभी उन्हें pass करते हैं:

with failproofai_sdk.session():
    with failproofai_sdk.agent("planner"):
        failproofai_sdk.event.tool_use(tool_name="search", tool_call_id="c1")

session_id या agent_id को explicitly pass करना अभी भी काम करता है और जीतता है। न bound और न ही passed के साथ, कॉल TypeError raise करता है, न कि एक event emit करता है जो Cloud quietly discard करेगा।

Identity context variables पर सवार होती है। यह asyncio tasks को automatically follow करता है, लेकिन नहीं नए threads को — एक worker को failproofai_sdk.propagate() में wrap करें या इसके events unattached land करते हैं।

Event कैटलॉग

पंद्रह मेथड। अधिकांश pairs में आते हैं — आप opener को कॉल करते हैं, फिर closer को, और SDK gap को time करता है।

	Opens	Closes
Agents	`agent_start`	`agent_end`
	`agent_pause`	`agent_resume`
Models	`model_request`	`model_response`
Tools	`tool_use`	`tool_result`
Hooks	`hook_triggered`	`hook_completed`
Humans	`human_wait`	`human_input`

तीन standalone हैं: error, human_pause, human_interrupt।

हर फील्ड, प्रति मेथड

हर मेथड session_id और agent_id भी लेता है, जो scopes आपके लिए भरते हैं। कुछ भी None के रूप में छोड़ा गया JSON null के रूप में भेजे जाने की जगह dropped है, और हर मेथड None return करता है।

Method	आवश्यक	Optional
`agent_start`	—	`goal`, `parent_id`
`agent_end`	—	`outcome`, `summary`
`agent_pause`	`pause_id`	`reason`, `user_id`
`agent_resume`	`pause_id`	`reason`, `user_id`
`model_request`	—	`model`, `messages`, `system`, `tools`, `request_id`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`, `request_id`, `duration_ms`
`tool_use`	`tool_name`, `tool_call_id`	`input`
`tool_result`	`tool_name`, `tool_call_id`	`output`, `error`
`hook_triggered`	`hook_name`, `hook_id`	`trigger_event`, `input`
`hook_completed`	`hook_name`, `hook_id`	`outcome`, `output`, `error`
`error`	`error_type`, `message`	`traceback`
`human_wait`	`input_id`	`prompt`, `options`, `reason`
`human_input`	`input_id`	`response`
`human_pause`	—	`reason`, `user_id`
`human_interrupt`	—	`reason`, `user_id`, `at_step`

एक run को failed के रूप में चिह्नित करने के लिए, outcome को failed, error, timeout या rejected में से एक होना चाहिए। कुछ भी और — near-miss "failure" सहित — एक success के रूप में counts करता है।

Pairing और duration

एक नियम: closing event को अपने opener के समान id दें। वह क्या उन्हें pairs करता है, और क्या SDK को gap को time करने देता है।

Pair	Matched on
`tool_use` → `tool_result`	`tool_call_id`
`hook_triggered` → `hook_completed`	`hook_id`
`agent_pause` → `agent_resume`	`pause_id`
`human_wait` → `human_input`	`input_id`
`model_request` → `model_response`	`request_id`

duration_ms को yourself pass न करें। SDK इसे measure करता है, और इसे pass करना ValueError raise करता है। एक अपवाद model_response है, जहां केवल आप real provider latency को जानते हैं। milliseconds की एक पूरी संख्या pass करें — एक float raise करता है, क्योंकि column एक 32-bit integer है और अन्यथा empty land करेगी।

सीमांत स्थितियां

Ids केवल kind per, per session के लिए unique होना चाहिए। एक tool call और एक hook एक share कर सकते हैं; दो sessions एक साथ चल सकते हैं एक ही ids को reuse कर सकते हैं बिना colliding के।
वे agent को scoped नहीं हैं। एक pair एक agent के तहत open किया गया और दूसरे agent के तहत close किया गया अभी भी match करता है — जो multi-agent code में सामान्य case है।
request_id optional है लेकिन अनुशंसित है। इसके बिना, model events उनके आने के क्रम में pair up करते हैं, इसलिए एक ही agent में दो concurrent calls mispair कर सकते हैं।
एक pair processes में split अभी भी Cloud में match करता है, लेकिन SDK इसे time नहीं कर सकता — दोनों processes में कुछ भी दोनों halves नहीं देखा।
अधिकतम 10,000 openers एक बार में एक closer के लिए wait करते हैं। उसके बाद oldest को drop किया जाता है, इसलिए एक leak बिना bound के grow नहीं कर सकता।

अपने स्वयं के फील्ड

कोई भी extra keyword जो आप pass करते हैं event के साथ stored है:

failproofai_sdk.event.tool_use(
    tool_name="search", tool_call_id="c1",
    fw_tenant="acme", fw_region="eu-west-1",     # आपके अपने
)

यदि आप बाद में query करना चाहते हैं तो JSON types को prefer करें। कुछ भी और — एक UUID, एक datetime, एक Decimal, एक set, bytes, एक model object — एक string के रूप में stored है।

अपने फील्ड names को prefix करें। Extras अंत में apply किए जाते हैं, इसलिए एक field model, tool_name या outcome को called करना silently real one को overwrite करता है। Framework adapters fw_ उपयोग करते हैं; वही करें और कुछ भी collide नहीं कर सकता।यह भी है क्यों एक misspelled optional field कभी errors नहीं करता — यह बस एक नया custom field बन जाता है। यदि एक standard field Cloud में missing है, तो पहले spelling check करें।

ये पाँच names reserved हैं और सीधे rejected हैं: timestamp, session_id, agent_id, type, environment।

Deliver और verify करें

डैशबोर्ड
CLI

Observe → Events में, पहले verify करें agent_start exists है और agent_end exists अंत में है। फिर Observe → Sessions खोलें और confirm करें model, tool, human, hook, और error events intended order में दिखाई देते हैं। Session ID को primary troubleshooting key के रूप में उपयोग करें।

failproofai flush --wait --timeout 60
failproofai config --status
fp sessions --since 1h --env production --session-id <session-id>
fp events --since 1h --session-id <session-id> --full

यदि Cloud खाली है, तो $FAILPROOFAI_HOME/custom-agents/events inspect करें, अन्यथा ~/.failproofai/custom-agents/events। JSONL files SDK emission को prove करती हैं; एक growing spool daemon configuration या delivery को point करता है, जबकि एक empty spool instrumentation या process lifetime को point करता है।

Spool को केवल तब inspect करें जब daemon बंद हो। जबकि यह चलता है, यह collects करता है और हर batch को milliseconds में delete करता है, इसलिए एक directory listing races करता है collector के साथ और emit किए गए events से far fewer दिखाता है।

कस्टम runtime में failures को prevent करें

Audit findings और linked traces का use करके unsafe action, required evidence, और intended response को define करें। एक custom enforcement integration को execution से पहले action को expose करना चाहिए, इसके structured input को policy engine में pass करना चाहिए, और resulting allow, instruct, या deny decision को apply करना चाहिए। Failproof AI से contact करें और हम आपके runtime के model, tool और lifecycle boundaries को policy hooks से map करने में मदद करेंगे, फिर integration को आपके साथ validate करेंगे।

Connect your agents

Reference