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

כוונן עקבות מסוכן מותאם באמצעות failproofai-sdk כדי ש-Failproof AI יוכל לשחזר כל הרצה, לבדוק את ההתנהגות שלה ולמצוא כשלים מסומכים בראיות. ה-SDK כותב אירועים מובנים עבור Failproof daemon להעביר ל-Cloud. זה דורש Python 3.10 או חדש יותר. Tracing הופך סוכנים מותאמים לניתני תצפית ולביקורת. מניעת פעולה לא בטוחה לפני שהיא מתבצעת דורשת גם hook אכיפה בזמן ריצה שלך.

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

התקן את `failproofai-sdk`

ה-SDK מופץ כרגע כגלגל פרטי. בקש מאחד ה-Failproof AI שלך את הגרסה הנוכחית וגישה להורדה.

VERSION=<sdk-version>
pip install "./failproofai_sdk-${VERSION}-py3-none-any.whl"
python -c "import failproofai; print(failproofai.__version__)"

עם uv, הורד את הגלגל תחילה והרץ uv add ./failproofai_sdk-${VERSION}-py3-none-any.whl. קבע את הגלגל במאגר חפצים פרטי או בנעילת תלות. החבילה מותקנת כ-failproofai-sdk ומיובאת בפייתון כ-failproofai.

חבר את Failproof daemon

לוח בקרה
CLI

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

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

כוונן הרצה שלמה

קרא ל-configure() פעם אחת בעת התחלת התהליך. כל קריאת אירוע היא keyword-only ודורשת session_id ו-agent_id יציבים.

import traceback
import uuid

import failproofai

failproofai.configure(environment="production")

session_id = uuid.uuid4().hex
agent_id = "checkout-agent"

failproofai.event.agent_start(
    session_id=session_id,
    agent_id=agent_id,
    goal="Resolve a failed checkout",
)

try:
    tool_call_id = uuid.uuid4().hex
    failproofai.event.tool_use(
        session_id=session_id,
        agent_id=agent_id,
        tool_name="lookup_order",
        tool_call_id=tool_call_id,
        input={"order_id": "ord_8421"},
    )
    result = {"status": "payment_failed"}
    failproofai.event.tool_result(
        session_id=session_id,
        agent_id=agent_id,
        tool_name="lookup_order",
        tool_call_id=tool_call_id,
        output=result,
    )
except Exception as exc:
    failproofai.event.error(
        session_id=session_id,
        agent_id=agent_id,
        error_type=type(exc).__name__,
        message=str(exc),
        traceback=traceback.format_exc(),
    )
    failproofai.event.agent_end(
        session_id=session_id,
        agent_id=agent_id,
        outcome="failed",
    )
    raise
else:
    failproofai.event.agent_end(
        session_id=session_id,
        agent_id=agent_id,
        outcome="success",
        summary="Escalated the failed payment",
    )

פלוט agent_start פעם אחת לכל שחקן. עבור תת-סוכנים, השתמש חוזר ב-session_id של ההורה, תן לכל שחקן agent_id מובחן, והגדר parent_id ל-agent ID של ההורה, לא למזהה ההפעלה.

התייחסות תצורה

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

הגדרה	התנהגות
`base_dir`	שורש ספול מפורש. קודם לכל משתנים של סביבה.
`flush_interval`	שניות בין כתיבות רקע מזיכרון ל-JSONL. ברירת מחדל: `0.5`.
`environment`	תווית פריסה בכל אירוע. ברירת מחדל ל-`dev`.
`FAILPROOFAI_HOME`	משנה את שורש Failproof AI המכיל את ה-`custom-agents` spool.

ה-SDK כותב ל-base_dir המפורש כשהוא מוגדר. אחרת, הוא משתמש בספול custom-agents של Failproof daemon תחת FAILPROOFAI_HOME או ~/.failproofai. ה-SDK תוור קריאות בזיכרון וכותב אצווות בחוט רקע. הוא גם מנסה flush סופי דרך טיפול atexit של Python. עבור עובדים קצרי חיים, אפשר כיבוי מתורגם רגיל; סיום תהליך קשה יכול לאבד אירועים עדיין בזיכרון.

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

כל השיטות מחזירות None. שדות שנותרו כ-None מושמטים ולא כתובים כ-JSON null.

שיטה	שדות נדרשים מעבר לזהות	שדות אופציונליים
`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`
`model_response`	—	`model`, `stop_reason`, `input_tokens`, `output_tokens`, `content`, `role`
`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", אינם מסווגים ככשלים על ידי ה-backend הנוכחי.

כללי קורלציה ומשך זמן

השתמש חוזר באותו tool_call_id, hook_id, pause_id, או input_id עבור אירוע ההשלמה המתאים.
ה-SDK מחשב duration_ms עבור tool_result, hook_completed, agent_resume, ו-human_input. העברתו בעצמך לשיטות אלה מעלה ValueError.
זיהויים של כלים וחישוקים חולקים מפת pending אחת בחוץ תהליך. הפוך אותם ייחודיים בעולם על פני הפעלות בו-זמנית ועל פני שני מרחבי השמות; זיהויים מספקי או UUIDs הם בטוחים ביותר.
זוג מפוצל על פני תהליכים עדיין מתייחסות במורד הזרם, אך ה-SDK אינו יכול לחשב את משך ה-in-process שלו.
מפת ההמתנה מחזיקה לכל היותר 10,000 התחלות וסילוקי הכניסה הישנה ביותר כשהיא מלאה.

שדות וטעימות מותאמים

כל אירוע מקבל שדות keyword נוספים. השתמש בערכים תואמים JSON כאשר שאילתות במורד הזרם צריכות מבנה. עלים לא נתמכים כגון UUIDs, datetimes, decimals, sets, bytes, and model objects מחרוזים על ידי הכותב. שמות מותאמים שמורים הם timestamp, session_id, agent_id, type, ו-environment. שגיאות באות field אופציונלית מתקבלות כשדות מותאמים חדשים, לכן בדוק את ה-JSON המופץ כאשר שדה סטנדרטי לא מופיע בCloud.

העבר ובדוק

לוח בקרה
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

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

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

השתמש בממצאי ביקורת ובעקבות משובצות להגדרת הפעולה הלא בטוחה, ההוכחה הנדרשת והתגובה המכוונת. אינטגרציה אכיפה מותאמת חייבת לחשוף את הפעולה לפני ביצוע, להעביר את הקלט המובנה שלה לנוע המדיניות, וליישם את ההחלטה המותרת, הוראה, או סירוב. שלח דוא”ל support@befailproof.ai כדי לעצב ולאמת אינטגרציה זו עבור זמן הריצה שלך.

Connect your agents

Reference

HTTP API

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

התקן את `failproofai-sdk`

חבר את Failproof daemon

כוונן הרצה שלמה

התייחסות תצורה

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

כללי קורלציה ומשך זמן

שדות וטעימות מותאמים

העבר ובדוק

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

​התקן את failproofai-sdk

​חבר את Failproof daemon

​כוונן הרצה שלמה

​התייחסות תצורה

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

​כללי קורלציה ומשך זמן

​שדות וטעימות מותאמים

​העבר ובדוק

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

התקן את `failproofai-sdk`

חבר את Failproof daemon

כוונן הרצה שלמה

התייחסות תצורה

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

כללי קורלציה ומשך זמן

שדות וטעימות מותאמים

העבר ובדוק

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