התקנה
הוספת מעקב
ומה כל אחד מהם למעשה פולט:
הכל בתוך יכול להשמיט
session_id ו-agent_id. הטווחים קושרים זהות על משתנות context ותוך כל קריאת event היא קוראת אותה חזרה, כך שאתה אף פעם לא מחליק מזהים דרך הפונקציות שלך.
כל השלושה עובדים תחת async with כמו גם תחת with.
קינון סוכנים בונה את העץ. parent_id והעמוק מחושבים מהערימה:
כיצד טווח סוגר
agent() מטפל בחריגות עבורך:
השגיאה פלטת לפני
agent_end, כי הדashboard סוגר את ה-span ב-agent_end וכל דבר אחרי זה מיוחס לכלום. ביטול אינו כשל, כך שהרצות מבולות לא מזוהמות על משטח השגיאות. החריגה תמיד מוגבה מחדש: טווח אף פעם לא בולע.
שיטות האירוע
חמש עשרה שיטות בשש משפחות. רובן מגיעות בזוגות — אתה פולט את הפותח, ואז את הסוגר, והSDK מודד את ה-span ביניהם.שתי משפחות בני אדם מצביעות בכיוונים מנוגדים.
אף פריימוורק לא משדר את הזוג השני, כך שתמיד שלך להפליט.
דוגמה
לולאת קריאת כלי כנגד ה-OpenAI API, ללא פריימוורק סוכנים:docs/manual/examples/.
חוטים ו-async
משתנות context מתפשטות לתוך asyncio tasks באופן אוטומטי. הן לא מתפשטות לתוך חוטים חדשים, כי חוט מתחיל עם context ריק.propagate(), אירועי העובד מגבילים TypeError ששם את התיקון במקום נחיתה ללא session. זה כוונתי: אירוע ללא session מדולל על ידי ingest וענות 200, שזה הכשל שקט שלנו שה-identity layer קיים כדי למנוע.
הוסף מעקב לפריימוורק ללא מתאם
כל סוכן פריימוורק נותן לך את אותם שלושה seams. מפה אותם ויש לך עקבות מלא — ארבעת המתאמים המספקים לא עושים יותר מזה.1
תחום את ה-run
2
תחום כל כלי
בכל מה שהפריימוורק קורא tool wrapper או middleware.
3
זווג כל קריאת מודל
ידני והאוטומטי מרכיבים. מתאם שנמצא בתוך scope כתוב ביד מצטרף לשיוך זה ומוריש לסוכן זה, כך שאתה מקבל עץ אחד ולא שניים — שימושי כאשר אתה מעביר מסגרת אחת בעצמך לצד אחד בעל תמיכה.
למה אין מתאם AutoGen
למה אין מתאם AutoGen
שתי סיבות, והשלושת ה-seams למעלה הן התשובה לשניהם:
autogen-coreלא תופסת תחזוקה מ-September 2025.- AG2 לא חושף נקודת רישום כללית תהליך שווה ערך למשדרים של פריימוורקים אחרים, כך שהוספת מעקב אומר עטיפת כל סוכן בכל אתר בנייה.
עומק יותר
איך ההקלטה למעשה עובדת. כלום מזה לא נחוץ כדי להתחיל.מה הקלטה נראית כמו, לכל פריימוורק
מה הקלטה נראית כמו, לכל פריימוורק
לכל הקלטה אותו צורה: span נפתח, עבודה קינה בתוכו, ולכל אירוע פותח יש אירוע סוגר אחד.הזוג הוא היחידה. כל אירוע סוגר נושא משך זמן SDK מודד מה-opening שלו.להלן הרצה אמיתית אחת לכל פריימוורק — תפוסה מהדוגמאות שנמצאות עם ה-SDK, שם מודל מנורמל. שים לב כמה חוזר מקריאה יחידה.Nodes הופכים לזוגות hook, כך שאתה מקבל לטנציה לכל node ללא טביעת הרשימה סוכנים.
- LangGraph
- CrewAI
- LlamaIndex
- Pydantic AI
- סוכנים מותאמים אישית
14 events
איך session מתחיל ומסתיים
איך session מתחיל ומסתיים
אין אירוע session-end. session אינה משהו שאתה סוגר — היא קבוצה של אירועים השיתוף
session_id.סטטוס נגזר מצורת העקבות:כך שsession מסתיים כאשר כל זוג סוגר. המתאמים פולטים
agent_end עבורך, והם סוגרים כל דבר עדיין פתוח ומסימנים אותו לא שלם — הרצה קרוסה מתפזרת כ-done עם פער גלוי במקום תלויה לנצח.זה למה session יכול להקיף שתי קריאות. LangGraph
interrupt() השהה את ה-run, ה-root span בכוונה נשאר פתוח, והקריאה הממשיכה סוגרת אותה. שתי הקריאות הן session אחד.זהות: session_id, agent_id, והמי חושב אותם
זהות: session_id, agent_id, והמי חושב אותם
session_id ו-agent_id הם אופציונליים בכל שיטת event. בהשמטה, הם מתפזרים מהטווח שוקע:TypeError שם את התיקון במקום הפקת אירוע ללא session, אשר ingest היה דלל תוך התשובה 200.טווחים קושרים זהות על משתנות context. אלה מתפשטות לתוך asyncio tasks באופן אוטומטי אך לא לתוך חוטים חדשים — עטוף עובד ב-failproofai_sdk.propagate().מי חושב איזה id
איך מתאמים מתפזרים session_id
תאימה ראשונה זוכה:- ערך
session_idמפורש - metadata לכל קריאה
- טווח
session()שוקע - framework metadata
- framework’s שלהם run id
שמור agent_id low cardinality
זה ה-facet ראשי בכל משטח dashboard, ו-LowCardinality(String) כולונה. ערך לכל run מורידה את הכולונה ומלאה את ה-filter dropdown בערך אחד לכל run.מתאמים בטחון כולונה זו עבורך:ה-ID האמיתי שמור ב-
fw_agent_id / fw_run_id, איפה זה נשאר queryable ללא להיות facet.סוגי אירוע, מקובצים — וריימוורק איזה רשום מה
סוגי אירוע, מקובצים — וריימוורק איזה רשום מה
איזה פריימוורק רושם מה, נמדד מה-runs למעלה:
dash פירושו הפריימוורק אין לו כזה קונספט.
human_pause ו-human_interrupt תארו אדם פועל על סוכן, אשר אף פריימוורק משדר — הפלוט אלה בעצמך.זוגות, קורלציה ומשך זמן
זוגות, קורלציה ומשך זמן
אירוע אף פעם לא מגיע בודד. אחד פותח span, אחד סוגר אותו, ואירוע הסיום נוצא משך זמן SDK מודד מה-opening.
כללי קורלציה
- חזור על אותו
tool_call_id,hook_id,pause_id, אוinput_idלאירוע השלמה תואם. - SDK מחשבות
duration_msלכלtool_result,hook_completed,agent_resume, ו-human_input. עברור אותו הודעות raisesValueError. duration_msהוא קבול ב-model_response, כי רק ה-caller יודע ה-real provider latency. זה חייב להיות integer — float raisesValueErrorבקריאה site, כי השרת קורא את הכולונה כ-unsigned 32-bit integer וחנה NULL לכל דבר אחר.- מפתחות קורלציה בטוח לפי סוג וsession, אז tool call ו-hook עשוי בטוח שיתוף id, וsessions מקבילות שני חזור על אותם ids ללא התנגשות. הם לא בטוח על ידי סוכן: זוג פתוח תחת סוכן אחד וסגור תחת אחר עדיין קורלציה, שהיא המקרה הרגיל במסגרות רב סוכנים.
request_idזוגותmodel_requestעםmodel_response. ללא אותו, אירועי מודל זוג בסדר לכל סוכן, כך קריאות מקבילות mispair.- זוג פיצול על פני processes עדיין קורלציה downstream, אך SDK לא יכול לחשב in-process duration.
- מפת pending מחזיקה לכל היותר 10,000 starts ו-evicts ערך עתיק כאשר מלא.
מה בחבילה, ואיך instrument() מוצא הפריימוורק שלך
מה בחבילה, ואיך instrument() מוצא הפריימוורק שלך
התקנת ערכה קבל את זה שגוי והתהליך פועל עם ה-SDK ייובא, המתאם לכאורה מותקן, ולא אירוע אחד פלט. זה עוקב אזהרה אומר בדיוק זה — אז בדוק לוגים ראשון כאשר run רושם כלום.
failproofai-sdk מתקנת הכל, כל ארבעת המתאמים כלול. ה-extras משדרים את הפריימוורק, לא את המתאם.import failproofai_sdk הוא חוזה אפס תלויות, אינפורמציה על ידי בדיקה שמתקנת את הגלגלון עם --no-deps ועוד שמוכיח אף פריימוורק מגיע ל-sys.modules.גילוי אוטומטי קורא
sys.modules, לא את רשימת חבילה מותקנת, אז פריימוורק שיש לך מותקן אבל אף פעם לא ייבוא הוא לא מוכן והוא אף פעם לא ייובא בשמך. להראות מה חווט למעלה:instrument("crewai") על מכונה ללא CrewAI לא מגביל. זה עוקב אזהרה ו-return (), אז פריימוורק חמיץ אף פעם לוקח תהליך שגם מהמרות אחרים.האזהרה נוצא ה-ImportError בקדמה, וזה הודעה שם את פקודת התקנה מדויקת — כך התיקון בלוגים שלך, לא מוסתר.FAILPROOFAI_SDK_STRICT=1 כדי יש לו מגביל במקום. זה דגל קורא פעם אחת ו-cached, אז ייצוא זה לפני התהליך מתחיל במקום קביעה mid-run.איך אירועים מגיעים Cloud
איך אירועים מגיעים Cloud
ה-spool הוא מה עושה זה בטוח: סוכן שלך אף פעם לא חסום על הרשת, וCloud outage אומר ספריה גדלה במקום קביעה אירועים.כל flush כתוב קובץ אצווה אחד,
.tmp ראשון, ואז fsync, ואז atomic rename:.jsonl, אז זה לא יכול אף פעם קרא חצי כתוב קובץ. הגזע נוצא timestamp, process id וסדר מספר, אז שני תהליכים flush בה-millisecond לא יכול להתנגש. התור כובל בחסום 10,000 אירועים; העבר זה זה טיפל הוקדם וrelog.ה-daemon משלח אצוות שלך. זה לא פתוח או לשכתב אותם.Redaction פועל איפה ה-daemon כתוב שלהם אירועים — לא איפה אצוות משודרים. כך prompt או tool argument מחזיק API key עדיין מחזיק זה בהגעה.זה כוונתי. אלה בעצמך מעקב קריאות, וכתיבה מחדש בטרנזיט יומר את אירועים אתה קבל הם לא אירועים אתה פלט.ה-daemon מוחק כל אצווה בתוך milliseconds משליחה, אז
ls מרוצים collector וש fraction של מה אתה פלט — לא ניתנת להבחנה מ-SDK ש קיבוץ כלום.לאשר אירועים באמת נחתו, בדוק את ה-dashboard. לצפות ה-spool תמלא, עצור את ה-daemon ראשון.כאשר מעקב נכשל
כאשר מעקב נכשל
כל callback פועל בתוך wrapper שלה יחידה משימה היא להגביל מחדש, אז קריאה שלך יושבת בדיוק אחד
try והכל SDK עושה קורה מחוץ אותה.ה-default הוא ימין בייצור וחצי בזמן debug, כי זה יכול רק אי פעם הוכח אתה לא קרס. קביעה
FAILPROOFAI_SDK_STRICT=1 לעשות בוליט כשל קול.בעיות נפוצות
span לא סיים
span לא סיים
אירוע פותח אין אחד סוגר:
model_request ללא model_response, או tool_use ללא tool_result. השתמש הטווחים, אשר ערובה הזוג אפילו כאשר הגוף מגביל. אם אתה קורא את שיטות האירוע ישירות, השתמש try ו-finally.עברור duration_ms מגביל ValueError
עברור duration_ms מגביל ValueError
זה נמדד מה-opening תואם אירוע, אז זה דחוי ב-
tool_result, hook_completed, agent_resume, ו-human_input. זה קבול ב-model_response, כי רק אתה יודע ה-real provider latency, וזה חייב להיות integer.אירועים מעובד חוט מגביל TypeError
אירועים מעובד חוט מגביל TypeError
החוט לא אף פעם inherited ה-context. עטוף את ה-callable ב-
failproofai_sdk.propagate(). ראה חוטים ו-async.שדה תוספת נעלם או כתוב על משהו
שדה תוספת נעלם או כתוב על משהו
שדות תוספת מיזוג אחרון, אז אחד שנקרא כמו שדה אמיתי כמו
model או outcome היה כתוב על זה ו-שינוי כלונה שמור. Namespace שלך; המתאמים משתמשים fw_ קידומת.סוכן filter יש אלפים of entries
סוכן filter יש אלפים of entries
agent_id היא low-cardinality facet ו-אתה שים run id בזה. השתמש תפקיד או node שם ו-שים ה-ID אמיתי בשדה payload.הבא
איך זה עובד
זוגות, ids, session lifecycle, ו-delivery.
קרא trace
עקוב סיבתיות דרך ה-session אתה רק תפוסה.
מתאמי פריימוורק
LangGraph, CrewAI, LlamaIndex, ו-Pydantic AI.

