סוכנים מותאמים

מה שכל הגדרה, שיטה ושדה עושים. אם אתה מבצע קביעה לראשונה, התחל עם המדריך — הדף הזה מיועד לחיפוש מידע.

מדריך סוכנים מותאמים

התקנה, קביעה, שיטות האירועים, דוגמה מעבודה, ובעיות נפוצות.

משתמש בפריימוורק?

LangChain, CrewAI, LlamaIndex ו-Pydantic AI מבצעים קביעה עצמית בקריאה אחת.

Python 3.10 ומעלה. אין תלויות זמן ריצה.

התקנה

pip install failproofai-sdk

החבילה מותקנת כ-failproofai-sdk ומיובאת ב-Python כ-failproofai_sdk. הרחבות פריימוורק כמו failproofai-sdk[langgraph] מתקינות את הפריימוורק עצמו; המתאמים תמיד משלוחים בגלגל הבסיס.

חיבור ל-Failproof daemon

לוח הבקרה
CLI

עבור ל-Admin → Keys וצור מפתח עם events:add.
חבר את Failproof daemon ל-Cloud על מכונת הסוכן.
הפעל סשן אחד עם קביעה, ואז מצא את ה-ID המדויק שלו תחת Observe → Events.
עבור ל-Observe → Sessions, בחר את אותה סביבה, ופתח את ה-trace שעוקב מחדש.

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`	כמה קרוב לעתים קרובות ה-thread ברקע כותב לדיסק, בשניות. ברירת המחדל היא `0.5`.
`base_dir`	איפה לכתוב. ברירת המחדל היא ה-spool של ה-daemon, וזה מה שאתה רוצה אלא אם אתה יודע אחרת.

הגדר באמצעות משתנה סביבה במקום:

משתנה	מה זה עושה
`AGENTEYE_ENVIRONMENT`	קובע את `environment` ללא שינוי קוד, לכאשר התווית שייכת להצגה ולא לאפליקציה. ארגומנט `configure()` מנצח עליו.
`FAILPROOFAI_HOME`	מעביר את שורש Failproof AI שמחזיק את ה-spool.
`FAILPROOFAI_SDK_STRICT`	`1` גורם לשגיאות קביעה להעלות חריגות במקום להיות רשומות.
`FAILPROOFAI_SDK_STRICT_INTEGRATIONS`	`1` גורם לבעיית תאימות פריימוורק להעלות חריגות במקום להזהיר ולהמשיך הלאה.

אין פסיקים ב-environment. Ingest מפצל את השדה הזה בפסיקים כדי לבנות את המסננים שלו, ודילג על כל אירוע שהתווית שלו מכילה אחד — אז ריצה שלמה נעלמת בשקט. כתוב prod-eu, לא prod,eu.configure(environment="prod,eu") מעלה חריגות כדי שתגלה מיד. AGENTEYE_ENVIRONMENT לא יכול להעלות חריגות — שום דבר לא קורא לך — אז זה מזהיר פעם אחת וחוזר ל-dev.

אירועים מעומדים בזיכרון ונכתבים ברקע כל flush_interval שניות, עם flush סופי ביציאת המפרש. תהליך שהוכה לחלוטין הולך לאבד כל מה שטרם נכתב.

זהות

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

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 באופן אוטומטי, אך לא threads חדש — עטוף עובד ב-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, כאשר רק אתה יודע את זמן ההשהיה של הספק האמיתי. העבר מספר שלם של אלפיות שנייה — float מעלה חריגות, כי העמודה היא מספר שלם של 32 ביט והיתה נוחתת ריקה אחרת.

מקרי קצה

Ids רק צריכים להיות ייחודיים לסוג, לכל סשן. כלי וקוק יכולים לחלוק אחד; שני סשנים הפועלים בו זמנית יכולים לעשות שימוש חוזר בנתונים הלא מתנגשים.
הם לא מתוחמים לסוכן. זוג שנפתח תחת סוכן אחד וסגור תחת אחר עדיין מתאים — שזו המקרה הנורמלי בקוד רב-סוכן.
request_id אופציונלי אבל מומלץ. בלעדיו, אירועי מודל מזווגים בסדר שהם מגיעים, אז שתי קריאות בו זמנית באותו סוכן יכולות להזדווג בשגיאה.
זוג מחולק בין תהליכים עדיין תואם בעננן, אבל ה-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, set, bytes, אובייקט מודל — מאוחסן כמחרוזת.

קדיסה את שמות השדות שלך. הוספות מיושמות אחרון, אז שדה בשם model, tool_name או outcome דורך בשקט את האמיתי. מתאמי הפריימוורק משתמשים ב-fw_; עשה את אותו הדבר ושום דבר לא יכול להתנגש.זה גם למה שדה אופציונלי שגוי לעולם לא שגוי — הוא פשוט הופך לשדה מותאם חדש. אם שדה סטנדרטי חסר בעננן, בדוק תחילה את האיות.

חמש השמות הבאים שמורים ודחוקים לחלוטין: timestamp, session_id, agent_id, type, environment.

מסור והאמן

לוח הבקרה
CLI

ב-Observe → Events, אמת ש-agent_start קיים תחילה ו-agent_end קיים אחרון. ואז פתח Observe → Sessions ואשר שמודל, כלי, אדם, תריס ואירועי שגיאה מופיעים בסדר המיועד. השתמש בזהות הסשן כמפתח פתרון בעיות ראשוני.

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

אם ענן ריק, בדוק $FAILPROOFAI_HOME/custom-agents/events, אחרת ~/.failproofai/custom-agents/events. קובצי JSONL מוכיחים פליטת SDK; spool גדל מצביע על תצורת daemon או הפקה, בעוד spool ריק מצביע על קביעה או אורך חיי תהליך.

בדוק את ה-spool רק כאשר ה-daemon עוצר. בזמן שהוא פועל, הוא אוסף ודל כל קבוצה תוך אלפיות שנייה, אז רשימת ספרייה מתחרה בקולט ומראה הרבה פחות אירועים מאשר פלטו.

מנע כשלים בזמן ריצה מותאם

השתמש בממצאי ביקורת ובעקבות מקושרות כדי להגדיר את הפעולה הבלתי בטוחה, הראיות הנדרשות, והתגובה המיועדת. אינטגרציה אכיפה מותאמת חייבת לחשוף את הפעולה לפני ביצוע, להעביר את הקלט המובנה שלה למנוע המדיניות, ולהחיל את החלטת ה-allow, instruct, או deny שהתקבלה. צור קשר עם Failproof AI וניתן לנו לעזור למפות את גבולות המודל, הכלים וחיי הסוכן של זמן הריצה שלך לתריסי מדיניות, ואז לאמת את האינטגרציה איתך.

Connect your agents

Reference

סוכנים מותאמים

מדריך סוכנים מותאמים

משתמש בפריימוורק?

התקנה

חיבור ל-Failproof daemon

תצורה

זהות

קטלוג אירועים

זיווג ומשך

השדות שלך

מסור והאמן

מנע כשלים בזמן ריצה מותאם

מדריך סוכנים מותאמים

משתמש בפריימוורק?

​התקנה

​חיבור ל-Failproof daemon

​תצורה

​זהות

​קטלוג אירועים

​זיווג ומשך

​השדות שלך

​מסור והאמן

​מנע כשלים בזמן ריצה מותאם

התקנה

חיבור ל-Failproof daemon

תצורה

זהות

קטלוג אירועים

זיווג ומשך

השדות שלך

מסור והאמן

מנע כשלים בזמן ריצה מותאם