कस्टम एजेंट्स

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

कस्टम एजेंट्स गाइड

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

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

LangChain, CrewAI, LlamaIndex और Pydantic AI एक कॉल से खुद को इंस्ट्रूमेंट करते हैं।

Python 3.10 या नवीनतर। कोई रनटाइम निर्भरताएं नहीं।

इंस्टॉल करें

pip install failproofai-sdk

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

Failproof डेमॉन कनेक्ट करें

डैशबोर्ड
CLI

Admin → Keys पर जाएं और events:add के साथ एक कुंजी बनाएं।
Failproof डेमॉन को Cloud से कनेक्ट करें एजेंट मशीन पर।
एक इंस्ट्रूमेंटेड सेशन चलाएं, फिर Observe → Events के तहत इसकी सटीक ID खोजें।
Observe → Sessions पर जाएं, वही वातावरण चुनें, और पुनर्निर्मित ट्रेस खोलें।

failproofai config \
  --connect https://app.befailproof.ai \
  --token <events-add-key>
failproofai config --status

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

import failproofai_sdk

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

तर्क	यह क्या करता है
`environment`	हर इवेंट पर लेबल — `production`, `staging`, `prod-eu`। डिफ़ॉल्ट `dev`।
`flush_interval`	पृष्ठभूमि थ्रेड कितनी बार डिस्क पर लिखता है, सेकंड में। डिफ़ॉल्ट `0.5`।
`base_dir`	कहाँ लिखें। डिफ़ॉल्ट डेमॉन का स्पूल है, जो आप चाहते हैं जब तक कि आप अन्यथा न जानते हों।

इसके बजाय वातावरण चर द्वारा सेट करें:

चर	यह क्या करता है
`AGENTEYE_ENVIRONMENT`	कोड परिवर्तन के बिना `environment` सेट करता है, जब लेबल डिप्लॉयमेंट के बजाय ऐप से संबंधित हो। एक `configure()` तर्क इसे ओवरराइड करता है।
`FAILPROOFAI_HOME`	Failproof AI रूट को स्थानांतरित करता है जो स्पूल रखता है।
`FAILPROOFAI_SDK_STRICT`	`1` इंस्ट्रूमेंटेशन त्रुटियों को लॉग करने के बजाय बढ़ाता है।
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1` एक फ्रेमवर्क-संगतता समस्या को चेतावनी और जारी रखने के बजाय बढ़ाता है।

environment में कोई अल्पविराम नहीं। Ingest उस फील्ड को कोमा पर विभाजित करता है अपने फ़िल्टर बनाने के लिए, और कोई भी इवेंट जिसमें एक हो स्किप करता है — इसलिए एक पूरा रन चुपचाप गायब हो जाता है। prod,eu नहीं, prod-eu लिखें।configure(environment="prod,eu") बढ़ाता है इसलिए आप तुरंत पता लगा सकते हैं। AGENTEYE_ENVIRONMENT नहीं बढ़ा सकता — कोई आपको कॉल नहीं कर रहा — इसलिए यह एक बार चेतावनी देता है और dev पर फॉल बैक करता है।

इवेंट्स मेमोरी में कतारबद्ध होते हैं और हर flush_interval सेकंड में पृष्ठभूमि में लिखे जाते हैं, इंटरप्रेटर एक्जिट पर एक अंतिम फ्लश के साथ। एक प्रक्रिया जो सीधे मार दी जाती है वह जो अभी तक नहीं लिखा गया था उसे खो देता है।

पहचान

हर इवेंट एक सेशन और एक एजेंट से संबंधित है। स्कोप दोनों को भरते हैं, इसलिए आप शायद ही कभी उन्हें पास करते हैं:

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 को स्पष्ट रूप से पास करना अभी भी काम करता है और जीत जाता है। न तो बाउंड और न ही पास के साथ, कॉल TypeError बढ़ाता है बजाय एक इवेंट उत्सर्जित करने के जो Cloud चुपचाप छोड़ देता।

पहचान कॉन्टेक्स्ट चर पर चलती है। यह asyncio कार्यों को स्वचालित रूप से अनुसरण करता है, लेकिन नई थ्रेड्स नहीं — एक कार्यकर्ता को failproofai_sdk.propagate() में लपेटें या इसके इवेंट्स अनलगा रहते हैं।

इवेंट कैटलॉग

पंद्रह मेथड्स। अधिकांश जोड़े में आते हैं — आप ओपनर को कॉल करते हैं, फिर क्लोजर को, और SDK ने अंतराल को समय दिया।

	खोलता है	बंद करता है
एजेंट्स	`agent_start`	`agent_end`
	`agent_pause`	`agent_resume`
मॉडल्स	`model_request`	`model_response`
टूल्स	`tool_use`	`tool_result`
हुक्स	`hook_triggered`	`hook_completed`
ह्यूमन्स	`human_wait`	`human_input`

तीन अलग खड़े हैं: error, human_pause, human_interrupt।

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

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

मेथड	आवश्यक	वैकल्पिक
`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`

एक रन को विफल के रूप में चिह्नित करने के लिए, outcome निम्नलिखित में से एक होना चाहिए failed, error, timeout या rejected। कुछ भी अन्य — निकट-मिस "failure" सहित — एक सफलता के रूप में गिना जाता है।

जोड़ी और अवधि

एक नियम: क्लोजिंग इवेंट को अपने ओपनर के समान ID दें। यही है जो उन्हें जोड़ता है, और यही है जो SDK को अंतराल को समय देता है।

जोड़ी	मिलान किया गया
`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 पास न करें। SDK इसे मापता है, और इसे पास करना ValueError बढ़ाता है। एक अपवाद model_response है, जहां केवल आप वास्तविक प्रदाता विलंब जानते हैं। मिलीसेकंड की एक पूरी संख्या पास करें — एक फ्लोट बढ़ाता है, क्योंकि कॉलम एक 32-बिट पूर्णांक है और अन्यथा खाली हो जाएगा।

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

आईडीज को केवल प्रति प्रकार, प्रति सेशन अद्वितीय होने की आवश्यकता है। एक टूल कॉल और एक हुक एक को साझा कर सकते हैं; एक साथ दो सेशन एक ही आईडीज को बिना टकराए पुन: उपयोग कर सकते हैं।
वे एक एजेंट को स्कोप नहीं किए जाते हैं। एक जोड़ी जो एक एजेंट के तहत खोली जाती है और दूसरे के तहत बंद हो जाती है अभी भी मेल खाती है — जो बहु-एजेंट कोड में सामान्य स्थिति है।
request_id वैकल्पिक लेकिन अनुशंसित है। इसके बिना, मॉडल इवेंट्स उस क्रम में जोड़े जाते हैं जिसमें वे आते हैं, इसलिए एक ही एजेंट में दो समवर्ती कॉल गलत जोड़ी कर सकते हैं।
एक जोड़ी जो प्रक्रियाओं में विभाजित है Cloud में अभी भी मेल खाती है, लेकिन SDK इसे समय नहीं दे सकता — कुछ भी किसी भी प्रक्रिया में दोनों हिस्सों को नहीं देखा।
सबसे अधिक 10,000 ओपनर्स एक बार में क्लोजर का इंतजार करते हैं। इससे पहले सबसे पुराने को छोड़ दिया जाता है, इसलिए एक रिसाव बिना बाध्य बढ़ नहीं सकता।

आपकी अपनी फील्ड्स

कोई भी अतिरिक्त कीवर्ड जो आप पास करते हैं वह इवेंट के साथ संग्रहीत है:

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

JSON प्रकारों को बेहतर करें यदि आप बाद में उन्हें क्वेरी करना चाहते हैं। कुछ भी अन्य — एक UUID, एक datetime, एक Decimal, एक सेट, bytes, एक मॉडल ऑब्जेक्ट — एक स्ट्रिंग के रूप में संग्रहीत है।

अपने फील्ड नामों को प्रीफिक्स करें। एक्सट्रास अंत में लागू होते हैं, इसलिए model, tool_name या outcome नाम की फील्ड चुपचाप असली को ओवरराइट करता है। फ्रेमवर्क एडेप्टर्स fw_ का उपयोग करते हैं; वही करें और कुछ भी टकरा नहीं सकता।यही कारण है कि एक गलत वर्तनी वैकल्पिक फील्ड कभी त्रुटि नहीं करता — यह केवल एक नई कस्टम फील्ड बन जाता है। यदि एक मानक फील्ड Cloud में गायब है, तो पहले वर्तनी की जांच करें।

ये पाँच नाम आरक्षित हैं और सीधे अस्वीकार किए जाते हैं: timestamp, session_id, agent_id, type, environment।

डिलीवर करें और सत्यापित करें

डैशबोर्ड
CLI

Observe → Events में, पहले सत्यापित करें कि agent_start मौजूद है और agent_end अंत में मौजूद है। फिर Observe → Sessions खोलें और पुष्टि करें कि मॉडल, टूल, ह्यूमन, हुक, और त्रुटि इवेंट्स इच्छित क्रम में दिखाई देते हैं। सेशन ID को प्राथमिक समस्या निवारण कुंजी के रूप में उपयोग करें।

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 का निरीक्षण करें, अन्यथा ~/.failproofai/custom-agents/events। JSONL फाइलें SDK उत्सर्जन को साबित करती हैं; एक बढ़ता हुआ स्पूल डेमॉन कॉन्फ़िगरेशन या डिलीवरी की ओर इशारा करता है, जबकि एक खाली स्पूल इंस्ट्रूमेंटेशन या प्रक्रिया जीवनकाल की ओर इशारा करता है।

स्पूल का निरीक्षण केवल तब करें जब डेमॉन बंद हो। जबकि यह चलता है, यह मिलीसेकंड के भीतर प्रत्येक बैच को एकत्र करता है और हटाता है, इसलिए एक निर्देशिका सूची कलेक्टर के साथ दौड़ती है और उत्सर्जित इवेंट्स की तुलना में बहुत कम इवेंट्स दिखाती है।

कस्टम रनटाइम में विफलताओं को रोकें

असुरक्षित कार्रवाई, आवश्यक साक्ष्य, और इच्छित प्रतिक्रिया को परिभाषित करने के लिए ऑडिट निष्कर्षों और लिंक किए गए ट्रेस का उपयोग करें। एक कस्टम प्रवर्तन एकीकरण को निष्पादन से पहले कार्रवाई को उजागर करना चाहिए, इसके संरचित इनपुट को नीति इंजन में पास करना चाहिए, और परिणामी allow, instruct, या deny निर्णय लागू करना चाहिए। Failproof AI से संपर्क करें और हम आपके रनटाइम के मॉडल, टूल और जीवनचक्र सीमाओं को नीति हुक्स से मैप करने में मदद करेंगे, फिर एकीकरण को आपके साथ सत्यापित करेंगे।

Connect your agents

Reference

कस्टम एजेंट्स