Skip to main content
לסוכן שכתבת בעצמך, או לפריימוורק של Failproof AI אין לו מתאם. אין כלום להוסיף: אתה פולט את האירועים. זה אותו API שארבעת מתאמי הפריימוורק קוראים תחתיו. הם טבלאות תרגום עליו.

התקנה

ללא תוספים, וללא תלויות.

הוספת מעקב

קרא זאת מלמעלה למטה והיא אומרת מה זה אומר: ומה כל אחד מהם למעשה פולט: הכל בתוך יכול להשמיט session_id ו-agent_id. הטווחים קושרים זהות על משתנות context ותוך כל קריאת event היא קוראת אותה חזרה, כך שאתה אף פעם לא מחליק מזהים דרך הפונקציות שלך. כל השלושה עובדים תחת async with כמו גם תחת with. קינון סוכנים בונה את העץ. parent_id והעמוק מחושבים מהערימה:

כיצד טווח סוגר

agent() מטפל בחריגות עבורך: השגיאה פלטת לפני agent_end, כי הדashboard סוגר את ה-span ב-agent_end וכל דבר אחרי זה מיוחס לכלום. ביטול אינו כשל, כך שהרצות מבולות לא מזוהמות על משטח השגיאות. החריגה תמיד מוגבה מחדש: טווח אף פעם לא בולע.

שיטות האירוע

חמש עשרה שיטות בשש משפחות. רובן מגיעות בזוגות — אתה פולט את הפותח, ואז את הסוגר, והSDK מודד את ה-span ביניהם.
העדף את הטווחים — agent() ו-tool_call() — בכל מקום שהם מתאימים. הם מבטיחים את אירוע הסיום גם כאשר הגוף מגביל. פנה לשיטות אלה ישירות כאשר זרימת הבקרה שלך לא קינה, כמו קריאה למודל בתוך עוזר.
שתי משפחות בני אדם מצביעות בכיוונים מנוגדים.אף פריימוורק לא משדר את הזוג השני, כך שתמיד שלך להפליט.
עבור request_id כאשר קריאות מודל פועלות במקביל. בלעדיו, בקשות ותגובות מתזווגות בסדר הגעה לכל סוכן — וקריאות מקבילות מתזווגות בצורה שגויה, ומצרפות כל תגובה לבקשה הלא נכונה.

דוגמה

לולאת קריאת כלי כנגד ה-OpenAI API, ללא פריימוורק סוכנים:
זה מייצר את אותם ששת סוגי אירוע שמתאם היה נותן לך. הגרסה הרצה המלאה, עם הגדרות הכלים, משפנה ב-SDK repository תחת docs/manual/examples/.

חוטים ו-async

משתנות context מתפשטות לתוך asyncio tasks באופן אוטומטי. הן לא מתפשטות לתוך חוטים חדשים, כי חוט מתחיל עם context ריק.
ללא propagate(), אירועי העובד מגבילים TypeError ששם את התיקון במקום נחיתה ללא session. זה כוונתי: אירוע ללא session מדולל על ידי ingest וענות 200, שזה הכשל שקט שלנו שה-identity layer קיים כדי למנוע.

הוסף מעקב לפריימוורק ללא מתאם

כל סוכן פריימוורק נותן לך את אותם שלושה seams. מפה אותם ויש לך עקבות מלא — ארבעת המתאמים המספקים לא עושים יותר מזה.
1

תחום את ה-run

2

תחום כל כלי

בכל מה שהפריימוורק קורא tool wrapper או middleware.
3

זווג כל קריאת מודל

יש node, step או middleware boundary שחייב להיות נראה? עטוף אותו בזוג hook — hook_triggered / hook_completed — לא nested agent(). agent_id הוא facet low-cardinality, והערך אחד לכל node טובע אותו. Hook spans מתרנדרים בדרך זהה וגם נותנים לך לטנציה לכל node.
ידני והאוטומטי מרכיבים. מתאם שנמצא בתוך scope כתוב ביד מצטרף לשיוך זה ומוריש לסוכן זה, כך שאתה מקבל עץ אחד ולא שניים — שימושי כאשר אתה מעביר מסגרת אחת בעצמך לצד אחד בעל תמיכה.
שתי סיבות, והשלושת ה-seams למעלה הן התשובה לשניהם:
  • autogen-core לא תופסת תחזוקה מ-September 2025.
  • AG2 לא חושף נקודת רישום כללית תהליך שווה ערך למשדרים של פריימוורקים אחרים, כך שהוספת מעקב אומר עטיפת כל סוכן בכל אתר בנייה.
מיפוי ה-seams ביד רושם את אותם אירועים, בדיוק זהה, שמתאם משודר היה עושה.

עומק יותר

איך ההקלטה למעשה עובדת. כלום מזה לא נחוץ כדי להתחיל.
לכל הקלטה אותו צורה: span נפתח, עבודה קינה בתוכו, ולכל אירוע פותח יש אירוע סוגר אחד.הזוג הוא היחידה. כל אירוע סוגר נושא משך זמן SDK מודד מה-opening שלו.להלן הרצה אמיתית אחת לכל פריימוורק — תפוסה מהדוגמאות שנמצאות עם ה-SDK, שם מודל מנורמל. שים לב כמה חוזר מקריאה יחידה.
14 events
Nodes הופכים לזוגות hook, כך שאתה מקבל לטנציה לכל node ללא טביעת הרשימה סוכנים.
אין אירוע session-end. session אינה משהו שאתה סוגר — היא קבוצה של אירועים השיתוף session_id.סטטוס נגזר מצורת העקבות:כך שsession מסתיים כאשר כל זוג סוגר. המתאמים פולטים agent_end עבורך, והם סוגרים כל דבר עדיין פתוח ומסימנים אותו לא שלם — הרצה קרוסה מתפזרת כ-done עם פער גלוי במקום תלויה לנצח.
זה למה session יכול להקיף שתי קריאות. LangGraph interrupt() השהה את ה-run, ה-root span בכוונה נשאר פתוח, והקריאה הממשיכה סוגרת אותה. שתי הקריאות הן session אחד.
session_id ו-agent_id הם אופציונליים בכל שיטת event. בהשמטה, הם מתפזרים מהטווח שוקע:
העברתם בגלוי עדיין עובדת ולוקחת עדיפות. ללא כלום קשור וכלום עברר, הקריאה מגבילה TypeError שם את התיקון במקום הפקת אירוע ללא session, אשר ingest היה דלל תוך התשובה 200.טווחים קושרים זהות על משתנות context. אלה מתפשטות לתוך asyncio tasks באופן אוטומטי אך לא לתוך חוטים חדשים — עטוף עובד ב-failproofai_sdk.propagate().

מי חושב איזה id

איך מתאמים מתפזרים session_id

תאימה ראשונה זוכה:
  1. ערך session_id מפורש
  2. metadata לכל קריאה
  3. טווח session() שוקע
  4. framework metadata
  5. framework’s שלהם run id
זה אף פעם לא המצוי בזמן אחד מאלה קיים — id סינתטי היה מפלג הרצה אחת על פני מספר sessions.

שמור agent_id low cardinality

זה ה-facet ראשי בכל משטח dashboard, ו-LowCardinality(String) כולונה. ערך לכל run מורידה את הכולונה ומלאה את ה-filter dropdown בערך אחד לכל run.מתאמים בטחון כולונה זו עבורך:ה-ID האמיתי שמור ב-fw_agent_id / fw_run_id, איפה זה נשאר queryable ללא להיות facet.
שמירה זו רק נוגעת בתוויות הפריימוורק בחר. agent_id אתה עבור עצמך — ל-event.*, או ל-failproofai_sdk.agent(...) — הוקלט בדיוק כנתון. שמאלה כתוב argument מפורש היה גרוע יותר מה-cardinality זה מנע, כך שקרא את הspan שלך בהתאם.
איזה פריימוורק רושם מה, נמדד מה-runs למעלה:dash פירושו הפריימוורק אין לו כזה קונספט. human_pause ו-human_interrupt תארו אדם פועל על סוכן, אשר אף פריימוורק משדר — הפלוט אלה בעצמך.
אירוע אף פעם לא מגיע בודד. אחד פותח span, אחד סוגר אותו, ואירוע הסיום נוצא משך זמן SDK מודד מה-opening.
אירוע פותח ללא סוגר אחד הוא span שלא סיים. השיוך מתרנדר כעדיין פעיל, לנצח, וה-active duration שלו ממשיך לגדול. זה כשל mode לצפות בו כאשר אתה מוסיף מעקב ביד.

כללי קורלציה

  • חזור על אותו tool_call_id, hook_id, pause_id, או input_id לאירוע השלמה תואם.
  • SDK מחשבות duration_ms לכל tool_result, hook_completed, agent_resume, ו-human_input. עברור אותו הודעות raises ValueError.
  • duration_ms הוא קבול ב-model_response, כי רק ה-caller יודע ה-real provider latency. זה חייב להיות integer — float raises ValueError בקריאה 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 ערך עתיק כאשר מלא.
התקנת failproofai-sdk מתקנת הכל, כל ארבעת המתאמים כלול. ה-extras משדרים את הפריימוורק, לא את המתאם.
import failproofai_sdk הוא חוזה אפס תלויות, אינפורמציה על ידי בדיקה שמתקנת את הגלגלון עם --no-deps ועוד שמוכיח אף פריימוורק מגיע ל-sys.modules.
אין failproofai_sdk.crewai תכונה. מתאמים בכוונת לא חשוף על הפרה עליונה חבילה: לוגע אחד היה ייבוא הפריימוורק כ-side effect של גישה תכונה, שבירת אפס תלויות הבטחה. השתמש instrument().
גילוי אוטומטי קורא sys.modules, לא את רשימת חבילה מותקנת, אז פריימוורק שיש לך מותקן אבל אף פעם לא ייבוא הוא לא מוכן והוא אף פעם לא ייובא בשמך. להראות מה חווט למעלה:
instrument("crewai") על מכונה ללא CrewAI לא מגביל. זה עוקב אזהרה ו-return (), אז פריימוורק חמיץ אף פעם לוקח תהליך שגם מהמרות אחרים.האזהרה נוצא ה-ImportError בקדמה, וזה הודעה שם את פקודת התקנה מדויקת — כך התיקון בלוגים שלך, לא מוסתר.
ערכה FAILPROOFAI_SDK_STRICT=1 כדי יש לו מגביל במקום. זה דגל קורא פעם אחת ו-cached, אז ייצוא זה לפני התהליך מתחיל במקום קביעה mid-run.
instrument() חייב לבוא אחרי ייבוא הפריימוורק שלך. גילוי אוטומטי קורא sys.modules, אז קריאה ערומה מעל הייבוא מוצא כלום, מתקן כלום, וחוזר ().
קבל את זה שגוי והתהליך פועל עם ה-SDK ייובא, המתאם לכאורה מותקן, ולא אירוע אחד פלט. זה עוקב אזהרה אומר בדיוק זה — אז בדוק לוגים ראשון כאשר run רושם כלום.
ה-spool הוא מה עושה זה בטוח: סוכן שלך אף פעם לא חסום על הרשת, וCloud outage אומר ספריה גדלה במקום קביעה אירועים.כל flush כתוב קובץ אצווה אחד, .tmp ראשון, ואז fsync, ואז atomic rename:
ה-daemon רק עוזב .jsonl, אז זה לא יכול אף פעם קרא חצי כתוב קובץ. הגזע נוצא timestamp, process id וסדר מספר, אז שני תהליכים flush בה-millisecond לא יכול להתנגש. התור כובל בחסום 10,000 אירועים; העבר זה זה טיפל הוקדם וrelog.
collector.redact עושה לא חל ל-SDK אירועים שלך. זה אף פעם לא רואה אותם.
ה-daemon משלח אצוות שלך. זה לא פתוח או לשכתב אותם.Redaction פועל איפה ה-daemon כתוב שלהם אירועים — לא איפה אצוות משודרים. כך prompt או tool argument מחזיק API key עדיין מחזיק זה בהגעה.זה כוונתי. אלה בעצמך מעקב קריאות, וכתיבה מחדש בטרנזיט יומר את אירועים אתה קבל הם לא אירועים אתה פלט.
אתה שלוט בפעילויות ב-source, בשני מקומות:
  • כבה לכידת תוכן על המתאם. שם אפשרות שונה, ומתאם אחד אין אחד — זה לא אחד כללי אוניברסלי מתג:
    • LangChain / LangGraph, Pydantic AI — capture_content=False
    • LlamaIndex — capture_messages=False
    • CrewAI — אין מתג תוכן בכל; session_id היא רק אפשרות שהיא קורא, אז prompts ו-completions תמיד רשום.
    instrument() טיול אפשרויות מתאם לא קורא, אז עברור שם שגוי מגביל כלום ושינויים כלום.
  • אל תעביר את הסוד ל-input= בראשון מקום.
collector.redact הוא לא תחליף לאף אחד מאלה.
ספריה spool ריקה היא המדינה הבריאה. אל תשתמש בזה כדי בדוק משלוח.
ה-daemon מוחק כל אצווה בתוך milliseconds משליחה, אז ls מרוצים collector וש fraction של מה אתה פלט — לא ניתנת להבחנה מ-SDK ש קיבוץ כלום.לאשר אירועים באמת נחתו, בדוק את ה-dashboard. לצפות ה-spool תמלא, עצור את ה-daemon ראשון.
כל callback פועל בתוך wrapper שלה יחידה משימה היא להגביל מחדש, אז קריאה שלך יושבת בדיוק אחד try והכל SDK עושה קורה מחוץ אותה.ה-default הוא ימין בייצור וחצי בזמן debug, כי זה יכול רק אי פעם הוכח אתה לא קרס. קביעה FAILPROOFAI_SDK_STRICT=1 לעשות בוליט כשל קול.

בעיות נפוצות

אירוע פותח אין אחד סוגר: model_request ללא model_response, או tool_use ללא tool_result. השתמש הטווחים, אשר ערובה הזוג אפילו כאשר הגוף מגביל. אם אתה קורא את שיטות האירוע ישירות, השתמש try ו-finally.
זה נמדד מה-opening תואם אירוע, אז זה דחוי ב-tool_result, hook_completed, agent_resume, ו-human_input. זה קבול ב-model_response, כי רק אתה יודע ה-real provider latency, וזה חייב להיות integer.
החוט לא אף פעם inherited ה-context. עטוף את ה-callable ב-failproofai_sdk.propagate(). ראה חוטים ו-async.
שדות תוספת מיזוג אחרון, אז אחד שנקרא כמו שדה אמיתי כמו model או outcome היה כתוב על זה ו-שינוי כלונה שמור. Namespace שלך; המתאמים משתמשים fw_ קידומת.
agent_id היא low-cardinality facet ו-אתה שים run id בזה. השתמש תפקיד או node שם ו-שים ה-ID אמיתי בשדה payload.

הבא

איך זה עובד

זוגות, ids, session lifecycle, ו-delivery.

קרא trace

עקוב סיבתיות דרך ה-session אתה רק תפוסה.

מתאמי פריימוורק

LangGraph, CrewAI, LlamaIndex, ו-Pydantic AI.