> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> מכוונן עקבות מסוכנים מותאמים כדי ש-Failproof AI יוכל לשחזר הרצות ולמצוא כשלים.

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

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

<Info>
  כדי אכוף מדיניויות בהגדרת סוכן מותאמת, [צור קשר עם Failproof AI](mailto:support@befailproof.ai). אנחנו נעזור למפות את גבולות המודל, הכלים וחיי המחזור של זמן הריצה שלך לאגוזי מדיניות.
</Info>

<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
  <iframe src="https://www.youtube.com/embed/VWxukZc5k7s?rel=0&playsinline=1" title="Agent tracing with the Failproof AI Python SDK" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }} />
</div>

## התקן את `failproofai-sdk`

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

```bash theme={null}
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

<Tabs>
  <Tab title="לוח בקרה">
    1. עבור אל **Admin → Keys** וצור מפתח עם `events:add`.
    2. [חבר את Failproof daemon לCloud](/he/start/setup#connect-a-machine-to-cloud) על מכונת הסוכן.
    3. הרץ הפעלה מכוונת אחת, ואז מצא את המזהה המדויק שלה תחת **Observe → Events**.
    4. עבור אל **Observe → Sessions**, בחר באותה סביבה ופתח את העקבה שחוזרה.

           <img src="https://mintcdn.com/exosphere/WgPwQzedeDNwJBTy/images/dashboard/session-detail.png?fit=max&auto=format&n=WgPwQzedeDNwJBTy&q=85&s=7b5f022dd5c485565a8cd92b2e936235" alt="הפעלה של סוכן Python מותאמת שחוזרה כגרף ביצוע ועקבה של אירועים מסודרת." width="3200" height="2000" data-path="images/dashboard/session-detail.png" />
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    failproofai config \
      --connect https://app.befailproof.ai \
      --token <events-add-key>
    failproofai config --status
    ```
  </Tab>
</Tabs>

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

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

```python theme={null}
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** של ההורה, לא למזהה ההפעלה.

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

```python theme={null}
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.

## העבר ובדוק

<Tabs>
  <Tab title="לוח בקרה">
    ב-**Observe → Events**, בדוק תחילה שקיים `agent_start` ו-`agent_end` קיים אחרון. לאחר מכן פתח **Observe → Sessions** ובדוק שמודל, כלים, אנוש, חישוק ואירועי שגיאה מופיעים בסדר הנדרש. השתמש במזהה ההפעלה כמפתח בעיות עיקרי.
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    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
    ```
  </Tab>
</Tabs>

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

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

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

שלח דוא"ל [support@befailproof.ai](mailto:support@befailproof.ai) כדי לעצב ולאמת אינטגרציה זו עבור זמן הריצה שלך.