Observability ו-Failure Recovery — לראות, לתפוס כשלים, ולעצור לולאות

למה harness בלי observability הוא קופסה שחורה

נתחיל מתרחיש שכל מי שבנה loop ביתי מכיר. אתה מריץ task, רואה את ה-CPU עובד, רואה כמה הודעות נדפסות ב-terminal, ואז — שקט. הסוכן "חושב". עוברות שתי דקות. עוד דקה. אתה מסתכל על החשבון ב-Console ורואה שנשרפו 40,000 tokens. על מה? אין לך מושג. הסוכן נתקע על איזה tool? קרא לאותו endpoint שוב ושוב? נכנס ל-compaction באמצע? אתה לא יודע, כי הלולאה שלך לא מספרת לך כלום.

זו לא בעיה תיאורטית. אחד מ-beginner_mistakes המתועדים במחקר של 2026 הוא בדיוק זה: הסתמכות על frameworks כבדים שמגיעים עם "אפס observability ו-agents שלולפים 6+ פעמים על קריאת tool אחת" (מתוך course.research.json, gotchas). שים לב לצירוף: אפס observability ולולאה של 6+ מופיעים יחד — לא במקרה. כשאתה לא רואה את הלולאה, אתה לא יודע שהיא קורית עד שמגיע החשבון.

Observability (נראוּת) היא היכולת לענות על השאלה "מה באמת קרה בריצה הזו?" בלי לנחש. במערכות תוכנה רגילות זה מורכב משלושה רכיבים: logs (מה קרה), metrics (כמה, כמה מהר, כמה עלה) ו-traces (באיזה סדר, מה הוביל למה). ב-harness לסוכן, ה-trace הוא הרכיב הקריטי, כי ריצת agent היא רצף של turns ו-tool calls שמובילים זה לזה — ובלי לראות את הרצף, אתה לא יכול להבין למה הסוכן הגיע למקום שהוא הגיע אליו.

הנקודה המעשית: observability היא לא "אופציה לפרודקשן" — היא תנאי כדי בכלל לבנות את שאר ה-harness. אי אפשר לבנות recovery חכם בלי לראות מה נכשל. אי אפשר לשלוט בעלות subagents (פרק 6) בלי לייחס tokens לכל אחד. אי אפשר למדוד אם Dreaming (פרק 7) באמת שיפר משהו בלי baseline. לכן זה הפרק שבא לפני ה-orchestration: קודם עיניים, אחר כך צוות.

שווה לעצור על ההבדל בין שלושת רכיבי ה-observability, כי מפתחים מבלבלים אותם. logs הם רשומות שטוחות — "קרה X בזמן T". הם טובים לחיפוש טקסטואלי אבל גרועים בהבנת רצף. metrics הם מספרים מצטברים — "50 ריצות, ממוצע 12 turns, עלות חציונית $0.30". הם מצוינים למגמות אבל לא אומרים לך מה קרה בריצה ספציפית. traces הם הרכיב שמחבר: הם מראים את הרצף ההיררכי של ריצה אחת — turn הוביל ל-tool call שהחזיר שגיאה שהוביל ל-turn נוסף. בעולם ה-LLM, שבו כל החלטה של הסוכן נשענת על מה שקרה לפניה, ה-trace הוא הרכיב שבלעדיו אתה פשוט לא מבין למה הסוכן עשה מה שעשה. הקורס מתמקד ב-traces כי הם הרכיב הייחודי לסוכנים — logs ו-metrics אתה כבר יודע מכל מערכת תוכנה אחרת.

יש כאן גם שאלה כלכלית, לא רק הנדסית. במחקר של הקורס מצוין במפורש שמפתח ישראלי צריך לתקצב ריצות agent עתירות-tokens תוך התחשבות בשער ILS/USD וב-VAT (מתוך course.research.json, local_market_notes). כשריצה בודדת יכולה לשרוף עשרות אלפי tokens, ולולאה לא-מזוהה יכולה להכפיל את זה פי כמה — ההבדל בין "יש לי observability" ל"אין לי" הוא הבדל ישיר בחשבון בסוף החודש. observability היא לא הוצאה, היא חיסכון.

לפני שצוללים ל-Langfuse — נעצור שנייה על המושגים. trace (עקבה) זה כמו "תיק רפואי של ריצה אחת": לא סתם "מה קרה", אלא רצף כרונולוגי של אירועים עם זמני התחלה וסיום, תוצאות, ועלויות. span זה אירוע אחד בתוך הריצה — turn (קריאה למודל) או tool call. generation זה span מיוחד לקריאת LLM, שרושם בנוסף גם token usage. בעולם הסוכנים, כל ריצה = trace אחד, וה-spans מתקבצים תחתיו בעץ. Langfuse היא המערכת שמייצרת, שומרת, ומציגה את העץ הזה בממשק גרפי — בדיוק מה שאתה צריך כדי לענות על שתי השאלות למעלה.

Langfuse כשכבת tracing — trace, span, ומה לרשום

Langfuse הוא פלטפורמת observability open-source שנבנתה ספציפית ל-LLM applications. בניגוד לכלי tracing כלליים, הוא מבין את המודלים של עולם הסוכנים: trace לכל ריצה, span לכל turn או tool call, וייחוס token cost לכל קריאה למודל. במחקר של הקורס הוא מסומן כשכבת ה-tracing המומלצת ל-harness (מתוך course.research.json, suggested_chapters: "Observability and Failure Recovery" → "Langfuse tracing"). יש לו tier חינמי ל-self-hosting וגם SaaS — לצרכי הקורס שניהם מספיקים.

שני מושגי היסוד:

החיבור ל-Claude Agent SDK פשוט להפתיע. שלושה משתני סביבה ו-decorator, או — לשליטה מלאה — קריאות ידניות לכל span. נתחיל מהגרסה הידנית כי היא מלמדת מה באמת קורה:

# pip install langfuse
import os
from langfuse import Langfuse

# מפתחות מ-Langfuse Console (יש tier חינמי)
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com"  # או self-hosted

langfuse = Langfuse()

def run_agent(goal: str):
    # trace אחד לכל ריצה — כל ה-spans יתקבצו תחתיו
    trace = langfuse.trace(name="agent-run", input={"goal": goal},
                           metadata={"harness_version": "0.5"})
    messages = build_initial_messages(goal)

    for turn in range(MAX_TURNS):
        # span לכל turn = קריאה למודל. generation רושם token usage
        gen = trace.generation(name=f"turn-{turn}", model="claude-sonnet-4-6",
                               input=messages)
        response = call_model(messages)          # הקריאה ל-Claude Agent SDK
        gen.end(output=response.content,
                usage={"input": response.usage.input_tokens,
                       "output": response.usage.output_tokens})

        tool_calls = extract_tool_use(response)
        if not tool_calls:
            trace.update(output=response.content)  # stop condition: יש תשובה סופית
            break

        for call in tool_calls:
            # span מקונן לכל tool call — כאן נראה latency אמיתי
            span = trace.span(name=f"tool:{call.name}", input=call.input)
            result = execute_tool(call)            # ה-tool execution מ-ch2/ch4
            span.end(output=result, metadata={"error": result.is_error})
            messages.append(tool_result_block(call, result))

    langfuse.flush()   # חשוב: לשלוח את ה-spans לפני שהתהליך מסתיים

שים לב לשלושה דברים. ראשית, ה-trace נוצר פעם אחת לכל ריצה — כל מה שקורה בלולאה מתקבץ תחתיו, וזה מה שנותן לך את התמונה ההיררכית במקום ערימת logs. שנית, trace.generation() הוא span מיוחד שיודע לרשום token usage — וזה מה שיאפשר את ה-cost attribution בסעיף הבא. שלישית, langfuse.flush() בסוף הוא לא קישוט: ה-SDK שולח spans באצווה ברקע, ואם התהליך מת לפני ה-flush, איבדת את ה-trace. ב-harness שרץ ב-CI או ב-cron, שכחת flush = ריצה שלמה שנעלמה.

# tools.py — read_file / write_file מינימליים לתרגיל
import pathlib

def read_file(path: str) -> str:
    return pathlib.Path(path).read_text(encoding="utf-8")

def write_file(path: str, content: str) -> str:
    pathlib.Path(path).write_text(content, encoding="utf-8")
    return f"wrote {len(content)} chars to {path}"

# רישום הכלים ל-Claude Agent SDK — input_schema חייב להיות תקין JSON Schema
TOOLS = [
    {"name": "read_file", "description": "קורא קובץ טקסט מהדיסק",
     "input_schema": {"type": "object",
                      "properties": {"path": {"type": "string"}},
                      "required": ["path"]}},
    {"name": "write_file", "description": "כותב טקסט לקובץ בדיסק",
     "input_schema": {"type": "object",
                      "properties": {"path": {"type": "string"},
                                     "content": {"type": "string"}},
                      "required": ["path", "content"]}},
]

Token cost attribution ו-Latency profiling

עכשיו שיש לך spans עם token usage, אתה יכול לענות על השאלה ששרפה לך 40,000 tokens בלי הסבר: איזה שלב היה יקר, ולמה? זה נקרא token cost attribution — ייחוס עלות ה-tokens לכל turn ו-tool call ספציפי, במקום מספר אחד גדול בסוף.

הקשר לפרק 3 ישיר: שם למדת למדוד input/output/cache tokens מתוך תגובת ה-SDK. כאן אתה לוקח את אותם מספרים ורושם אותם לכל span בנפרד. הסכימה הזו:

# ייחוס עלות לכל turn — מתבסס על token accounting מ-ch3
PRICE_PER_MTOK = {"input": 3.00, "output": 15.00, "cache_read": 0.30}  # USD/million, דוגמה מייצגת

def cost_of_turn(usage) -> float:
    return (usage.input_tokens   * PRICE_PER_MTOK["input"]
          + usage.output_tokens  * PRICE_PER_MTOK["output"]
          + usage.cache_read     * PRICE_PER_MTOK["cache_read"]) / 1_000_000

# בכל turn, מצרפים את העלות ל-span כ-metadata
gen.end(output=response.content,
        usage={"input": u.input_tokens, "output": u.output_tokens},
        metadata={"cost_usd": cost_of_turn(u),
                  "cache_hit_ratio": u.cache_read / max(u.input_tokens, 1)})

Latency profiling הוא הצד השני של אותו מטבע. לכל span כבר יש זמן התחלה וסיום, אז ה-latency "חינם" — אבל הערך הוא בפילוח. שאלת המפתח: האם ה-latency הוא network או CPU? tool שקורא ל-API חיצוני איטי בגלל הרשת; tool שמריץ עיבוד כבד מקומית איטי בגלל ה-CPU. ההבחנה משנה את הפתרון:

בוא נראה מספרים, כי כאן ה-cost attribution מוכיח את עצמו. נניח ריצה של 8 turns שעלתה $0.48 בסך הכל. בלי attribution, זה כל מה שאתה יודע. עם attribution, ה-trace מראה ש-turn 5 לבדו עלה $0.21 — כמעט חצי מהריצה. למה? כי בדיוק לפניו tool החזיר 40KB של JSON ישר ל-context (זוכר/ת את context budget מפרק 3?), וה-turn הבא נשא את כל ה-40KB כ-input tokens. בלי attribution היית מחפש את הבעיה בכל מקום; עם attribution, ה-trace מצביע ישר על ה-turn האשם ועל ה-tool שלפניו. התיקון — להחזיר reference במקום ה-JSON המלא (ch3) — חוסך את ה-$0.21 בכל ריצה עתידית. זה ההבדל בין ניחוש לניתוח.

שים/י לב גם ל-cache_hit_ratio שרשמנו ל-span. ה-Claude Agent SDK תומך ב-prompt caching — חלקים יציבים מההיסטוריה (system prompt, הוראות קבועות) נקראים מ-cache במחיר מוזל משמעותית. cache hit ratio נמוך לאורך זמן הוא דגל אדום: כנראה ה-system prompt או סדר ההודעות משתנים בכל turn ושוברים את ה-cache. ה-trace חושף את זה — ושיפור ה-cache hit ratio הוא לרוב הדרך הזולה ביותר להוריד עלות, בלי לגעת בלוגיקה.

השורה האחרונה בטבלת ה-latency היא הגשר לסעיף הבא. כש-tool call חוזר עם אותו input, יש שתי אפשרויות: או ששכחת caching (בזבוז), או שהסוכן נתקע בלולאה (כשל). ה-trace מראה לך את התסמין; עכשיו נבנה את המנגנון שמבחין ועוצר.

Loop detection — ה-failure הקלאסי

הגענו ל-failure הכי נפוץ, הכי יקר, והכי קל לפספס: הסוכן קורא לאותו tool, עם אותו input, שוב ושוב. במחקר של הקורס זה מתואר כ"agents looping 6+ times on a single tool call" (מתוך course.research.json, gotchas) — וזה לא מקרה קצה, זו ההתנהגות הברירת-מחדל של סוכן שנתקל בכשל שהוא לא "מבין".

הדינמיקה כך: הסוכן קורא ל-search("X"), מקבל שגיאה או תוצאה ריקה, "חושב" שאולי הוא טעה, וקורא שוב ל-search("X") — בדיוק אותו דבר. שוב שגיאה. שוב קריאה. כל סבב כזה הוא turn מלא: קריאה למודל (input = כל ההיסטוריה שגדלה!), עיבוד, קריאת tool. הלולאה הזו לא רק לא מתקדמת — היא מאיצה, כי כל סבב מנפח את ה-context (פרק 3) ומקרב אותך ל-compaction. סוכן בלולאה הוא סוכן שמדמם budget ומאבד היסטוריה בו-זמנית.

דוגמה קונקרטית: נניח שה-search tool מחזיר {"results": []} כשאין תוצאות. הסוכן ראה "רשימה ריקה" ומנחש שבקשתו לא מספיק טובה. הוא מנסח מחדש — אבל את אותה שאלה בדיוק עם מילים שונות מעט. תוצאה: 6 קריאות שונות קלות שכולן חוזרות על {"results": []}. כל קריאה מוסיפה עוד turn להיסטוריה. turn 1: 800 input tokens. turn 7: 4,200 input tokens — כי ההיסטוריה של ששת הקריאות הקודמות נמצאת שם. העלות מצטברת לא ליניארית.

איך מזהים לולאה? המפתח הוא signature — חתימה שמזהה "אותה קריאה". הנאיבי הוא להשוות שם tool בלבד, אבל זה תופס false positives (סוכן שקורא ל-read_file על 5 קבצים שונים זה לגיטימי!). הנכון הוא חתימה של שם ה-tool + ה-input המנורמל:

import hashlib, json

def tool_signature(call) -> str:
    # נרמול: אותו tool + אותו input = אותה חתימה
    canonical = json.dumps(call.input, sort_keys=True, ensure_ascii=False)
    raw = f"{call.name}::{canonical}"
    return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:16]

נרמול ה-input (sort_keys=True) חשוב: {"q":"X","lang":"he"} ו-{"lang":"he","q":"X"} הם אותה קריאה לוגית, וצריכים אותה חתימה. עם החתימה ביד, ה-circuit breaker הוא פשוט מונה.

יש כאן עדינות אחת ששווה לדעת: לולאה לא תמיד מדויקת לחלוטין. לפעמים הסוכן קורא ל-search("מחיר Claude"), נכשל, ואז קורא ל-search("מחיר Claude API") — input קצת שונה, אבל אותה לולאה לוגית. החתימה המדויקת לא תתפוס את זה, כי ה-input השתנה במילימטר. לרוב ה-harnesses, חתימה מדויקת מספיקה (היא תופסת את 90% מהמקרים — הסוכן בדרך כלל חוזר על בדיוק אותו דבר). אבל אם אתה רואה ב-trace לולאות "כמעט-זהות" שחומקות, אפשר לשדרג ל-fuzzy signature — למשל לחשב חתימה על שם ה-tool בלבד עם סף גבוה יותר (8-10 קריאות לאותו tool גם עם input משתנה). התחל/י מהמדויק; שדרג/י רק אם ה-trace מראה שאתה צריך.

Circuit breaker בקוד — לספור, להזהיר, לעצור

ה-circuit breaker (מפסק) הוא דפוס שמושאל מהנדסת מערכות: כשרכיב נכשל שוב ושוב, "מנתקים" אותו במקום להמשיך לקרוא לו. ב-harness שלנו: סופרים כמה פעמים אותה חתימה הופיעה, ומגיבים בשני ספים — אזהרה רכה (3), עצירה קשה (6). שני הספים מכוונים: 3 כדי לתפוס מוקדם בלי false positive (לפעמים שתי קריאות זהות לגיטימיות), 6 כי זה הסף ש-course.research.json מזהה כ"לולאה" (6+ קריאות).

from collections import Counter

class CircuitBreaker:
    def __init__(self, warn_at=3, trip_at=6):
        self.counts = Counter()
        self.warn_at, self.trip_at = warn_at, trip_at

    def check(self, call, trace=None):
        sig = tool_signature(call)
        self.counts[sig] += 1
        n = self.counts[sig]

        if n == self.warn_at:
            # אזהרה רכה: מזריקים למודל הודעה שהקריאה חוזרת
            if trace: trace.event(name="loop-warning",
                                  metadata={"tool": call.name, "count": n})
            return ("warn", f"קראת ל-{call.name} עם אותו input {n} פעמים. "
                            f"נסה גישה אחרת או החזר תשובה סופית.")

        if n >= self.trip_at:
            # עצירה קשה: לא מריצים את ה-tool, עוצרים את הריצה
            if trace: trace.event(name="circuit-tripped", level="ERROR",
                                  metadata={"tool": call.name, "count": n})
            raise CircuitTripped(tool=call.name, signature=sig, count=n)

        return ("ok", None)

שים לב להבדל בין שני הספים — זה לב העניין. ב-3 קריאות אנחנו לא עוצרים, אלא מזריקים feedback למודל: "אתה חוזר על עצמך, נסה אחרת". לפעמים זה מספיק כדי לשבור את הלולאה — המודל לא ידע שהוא תקוע. זו גישה של self-healing רכה. רק ב-6 קריאות, כשברור שהמודל לא מצליח לצאת לבד, אנחנו עושים hard-stop — זורקים CircuitTripped ועוצרים. ההבחנה הזו בין self-healing ל-hard-stop תחזור עוד מעט כעיקרון.

החיבור ללולאה: ה-check() נכנס לפני execute_tool() בלולאה מפרק 2 — בדיוק במקום שבו בפרק 4 שמת את ה-policy gate. למעשה, circuit-breaker הוא סוג של gate: gate על תדירות במקום על תוכן.

for call in tool_calls:
    status, feedback = breaker.check(call, trace=trace)   # ה-gate החדש
    if status == "warn":
        messages.append(system_nudge(feedback))           # מזריקים feedback
        continue                                          # לא מריצים את ה-tool הפעם
    span = trace.span(name=f"tool:{call.name}", input=call.input)
    result = execute_tool(call)
    span.end(output=result, metadata={"error": result.is_error})
    messages.append(tool_result_block(call, result))

Failure capture — לתפוס כשל כמו אזרח מהשורה הראשונה

circuit breaker עוצר לולאה — אבל מה עושים עם הכשל? כאן נכנס failure capture: במקום לזרוק exception ש"נעלם" ל-stderr, תופסים כל כשל כרשומה מובנית. זה לא קישוט — זו תשתית. במחקר של הקורס, זהו דפוס מרכזי של Aden Hive, ה-harness הרב-סוכני open-source (~10.5k stars ב-GitHub), שמתואר עם "failure capture" כיכולת מובנית (מתוך course.research.json, features). ב-Aden Hive, failure הוא first-class citizen — אזרח מהשורה הראשונה — לא תקלה שמטאטאים מתחת לשטיח.

למה מבנה ולא טקסט? כי רשומה מובנית אפשר לתחקר, לספור, ולהזין בחזרה למערכת. וזה הגשר הישיר לפרק 7: ה-failures שאתה תופס כאן הם חומר הגלם של Dreaming — תהליך ה-self-improvement האסינכרוני של Claude Managed Agents שמשפר זיכרון על בסיס transcripts (מתוך course.research.json, features, "Claude Dreaming"). בלי failure capture מובנה, אין מה ל-Dreaming לעבד.

דוגמה קונקרטית לפני הקוד. נניח שהסוכן קורא ל-search("מחיר מניית אפל") ומקבל timeout. במקום שייזרק exception וייעלם ל-stderr, capture_failure בונה רשומה אחת: failure_type="transient", tool_name="search", error_message="ConnectionError: timed out after 30s", input_snapshot={"q": "מחיר מניית אפל"}, turn_number=4, token_cost_so_far=0.07. חמשת השדות האלה (לא סיפור, לא traceback) נשמרים גם ב-failure_store (לתחקור ול-Dreaming) וגם כ-event ב-Langfuse (לראייה מיידית). הרשומה המינימלית שמייצרת את זה:

from dataclasses import dataclass, field, asdict
from datetime import datetime, timezone

@dataclass
class FailureRecord:
    failure_type: str          # loop / tool_error / schema_violation / policy_block / timeout
    tool_name: str | None
    error_message: str
    input_snapshot: dict       # מה הסוכן ניסה לעשות
    context_summary: str       # תקציר state — לא כל ההיסטוריה (זוכר/ת context budget מ-ch3)
    turn_number: int
    token_cost_so_far: float   # מ-cost attribution — כמה כבר נשרף
    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())

def capture_failure(exc, call, turn, trace, cost_tracker) -> FailureRecord:
    rec = FailureRecord(
        failure_type=classify_failure(exc),
        tool_name=getattr(call, "name", None),
        error_message=str(exc),
        input_snapshot=getattr(call, "input", {}),
        context_summary=summarize_recent_messages(messages, last_n=3),  # קצר!
        turn_number=turn,
        token_cost_so_far=cost_tracker.total(),
    )
    # נרשם גם ל-trace (לראות) וגם ל-store (לזכור — ch7)
    if trace: trace.event(name="failure-captured", metadata=asdict(rec))
    failure_store.append(asdict(rec))
    return rec

שני פרטים שמבדילים failure capture טוב מ-except: pass. ראשית, context_summary הוא תקציר של 3 ההודעות האחרונות, לא כל ההיסטוריה — אם תשמור את כל ה-context בכל רשומת כשל, תנפח את ה-store ותשלם פעמיים (פעם על הריצה, פעם על האחסון). שנית, token_cost_so_far מגיע מ-cost attribution של הסעיף הקודם — וזה מה שיאפשר לך אחר כך לשאול "כמה עולים לי הכשלים מסוג X?".

מדיניות recovery — retry, fallback, escalate, stop

עכשיו מחברים הכל למדיניות recovery אחת: בהינתן רשומת כשל מסווגת, מה עושים? יש ארבע תגובות אפשריות, וההבחנה ביניהן היא ההבדל בין harness שמתאושש ל-harness שמדמם.

הלב של ה-retry gate הדטרמיניסטי הוא ההבחנה transient מול permanent. retry על כשל transient = חכם (הרשת חזרה, ההמשך עובד). retry על כשל permanent = בדיוק הלולאה ששורפת budget (מתוך course.research.json, common_mistakes לפרק זה: "לעשות retry על כל כשל באופן עיוור"). ההבחנה היא דטרמיניסטית — מבוססת סוג השגיאה, לא שיפוט של LLM:

import time

def recover(rec: FailureRecord, attempt: int, max_retries=3):
    # retry gate דטרמיניסטי — לא LLM שיפוטי, רק לוגיקה על סוג הכשל
    if rec.failure_type == "transient" and attempt < max_retries:
        time.sleep(2 ** attempt)          # exponential backoff: 1s, 2s, 4s
        return Action.RETRY

    if rec.failure_type == "schema" and attempt < 3:
        return Action.RETRY_WITH_FEEDBACK  # ה-pattern מ-ch4

    if rec.failure_type in ("transient", "schema"):
        # מיצינו retries — ננסה מסלול חלופי לפני שמוותרים
        return Action.FALLBACK

    if rec.failure_type in ("loop", "permanent"):
        return Action.ESCALATE             # retry כאן = לולאה. לא עושים

    if rec.failure_type == "policy":
        return Action.HARD_STOP            # gate חסם — לא עוקפים. לעולם

    return Action.ESCALATE                  # ברירת מחדל: כשלא בטוחים, קוראים לאדם

שים/י לב ל2 ** attempt — exponential backoff. אם הרשת נפלה, להציף אותה ב-retries מיידיים רק מחמיר. backoff מעריכי (1s, 2s, 4s) נותן למערכת להתאושש ומפזר עומס. זה סטנדרט בכל retry של רשת.

שים/י לב גם לברירת המחדל בשורה האחרונה: return Action.ESCALATE כשלא מזהים את סוג הכשל. זה עקרון הנדסי חשוב — כשלא בטוח, escalate לאדם. harness שממשיך לפעול עם כשל לא-מזוהה עשוי לעשות נזק שקשה לזהות. כשלא יודעים — מבקשים עזרה, לא ממשיכים בעיוורון.

Escalation, self-healing מול hard-stop

הגענו לשאלה הפילוסופית-מעשית של הפרק: מתי ה-harness מתקן את עצמו, ומתי הוא חייב לעצור ולקרוא לאדם? ההבחנה בין self-healing ל-hard-stop היא לא טכנית בלבד — היא החלטה על כמה אוטונומיה אתה נותן.

self-healing (ריפוי עצמי) זה כשה-harness פותר את הבעיה בלי אדם: schema retry שמתקן output לא-תקין, transient retry שמחכה לרשת, loop-warning שמזריק feedback והמודל מתאושש. hard-stop זה כשה-harness עוצר בכוונה: policy violation (gate חסם — לעולם לא עוקפים), loop שלא נשבר, או כשל permanent חוזר. ביניהם יושב escalation — עצירה שקוראת לאדם להחליט, במקום להיכשל בשקט.

ה-escalation מתחבר ישירות ל-human-approval gate מפרק 4. שם בנית gate שמשהה את הריצה עד אישור אנושי בנקודה רגישה (לפני שליחת email). אותו מנגנון בדיוק משמש כאן ל-recovery — רק שהטריגר שונה: בפרק 4 הטריגר היה "פעולה רגישה", כאן הטריגר הוא "כשל שה-harness לא יודע לפתור לבד". זה לא מקרה — גם governance וגם recovery מתכנסים לאותה תשתית של "השהה והמתן לאדם". תשתית זו כדאי לממש פעם אחת כ-abstraction נפרד ולהשתמש בה בשני המקרים.

def escalate(rec: FailureRecord, channel):
    # אותו מנגנון human-in-the-loop מ-ch4, טריגר שונה: כשל במקום פעולה רגישה
    channel.notify(
        title=f"🛑 Harness escalation: {rec.failure_type}",
        body=f"tool={rec.tool_name} · turn={rec.turn_number} · "
             f"cost_so_far=${rec.token_cost_so_far:.2f}\n"
             f"error: {rec.error_message}",
        actions=["retry_manual", "skip_step", "abort_run"],
    )
    # הריצה מושהית עד שאדם בוחר — לא נכשלת בשקט, לא ממשיכה לבד
    return channel.wait_for_decision(timeout_hours=4)

שים/י לב לשדה cost_so_far בגוף ה-escalation. כשאדם מקבל הודעה "הסוכן נתקע", ידיעת העלות שכבר נשרפה משנה את ההחלטה. "כשל ב-turn 2, עלות $0.02 עד כה" → אולי נסה שוב. "כשל ב-turn 22, עלות $1.40 עד כה" → כנראה עדיף לבטל ולנסח מחדש. ה-cost attribution מהסעיף הראשון הוא זה שמאפשר את ה-escalation הזה להיות מושכל — לא רק "משהו נכשל" אלא "משהו נכשל וכבר עלה X".

מדידת אמינות — איך יודעים שה-recovery עובד

בנית tracing, circuit-breaker, failure capture ו-recovery policy. אבל איך אתה יודע שזה עובד? כאן חוזרים ל-observability — לא כדי לדבג ריצה בודדת, אלא כדי למדוד אמינות לאורך זמן. שלוש מטריקות הן המינימום:

הערך האמיתי הוא במגמה, לא בנקודה. completion rate שעולה מ-70% ל-90% אחרי ששיפרת tool מסוים — זה ה-recovery עובד. עלות-לכשל שיורדת אחרי שהזזת circuit-breaker מ-6 ל-5 — זה חיסכון מדיד. בלי ה-tracing מהתחלת הפרק, אף אחת מהמטריקות האלה לא קיימת; עם ה-tracing, הן בחינם — רק צריך לאסוף ולחשב.

איך אוספים את המטריקות בפועל? Langfuse מאפשר לבנות dashboard מ-traces קיימים. הגישה הפשוטה: סכם traces לפי שדות שכבר רשמת. לאסוף completion rate, שאל: "כמה traces מסתיימים עם trace.output מול כאלה שמסתיימים עם event של circuit-tripped או failure-captured?" הנתון הזה נמצא ב-Langfuse ללא כתיבת קוד נוסף — כי רשמת את ה-events הנכונים בתרגילים 1-3.

בדיקה עצמית