Lesson 71 — Beginner

Agent Reliability, UX & Failure Recovery

Agents fail honge — galat tool, galat arguments, tool hi unavailable, repeat hota action, infinite loop. Asli sawaal yeh hai ki failure kaise aaye: predictable budget ke andar, ya bina kisi guard ke. Is lesson mein budgets, idempotency, persistence, fallbacks/escalation aur user ko informed rakhne wale UX patterns cover honge.

Common agent failures

• Galat tool/arguments: description theek karo, schema tight karo (L5.3), errors informative rakho.
• Unavailable tool: tool registry health check + model ko bata do ki ab kya available hai.
• Repeated actions: seen-set/idempotency — ek hi action dobara nahi.
• Incomplete plan / infinite loop: max steps + repetition guard + budget (L5.2).
• Context growth: memory trimming + result truncation (L5.5) — dheere-dheere quality ko maar deta hai, dikhta nahi.

Budgets — steps, time, retries, cost

class BudgetExceeded(Exception):
    pass

class Budget:
    def __init__(self, max_steps=10, max_minutes=120,
                 max_retries=2, max_tokens=200000):
        self.steps = 0
        self.retries = 0
        self.spent = 0
        self.limits = {"steps": max_steps, "minutes": max_minutes,
                       "retries": max_retries, "tokens": max_tokens}

    def step(self):
        self.steps += 1
        if self.steps > self.limits["steps"]:
            raise BudgetExceeded("max steps hit — stop karo, user ko batao")

    def charge(self, n):
        self.spent += n
        if self.spent > self.limits["tokens"]:
            raise BudgetExceeded("token budget khatam — resume plan banao")

# budget.step() loop ke andar har turn, budget.charge() har model call par

• Steps: loop ka ceiling — infinite loop ka pehla guard.
• Time: wall-clock timeout — slow tools bhi rok dete hain.
• Retries: per-operation retry budget — "baar baar try karta rahega" nahi.
• Cost/tokens: run ka total spend cap — agent ka sabse mehnga failure mode yahi hai.
• Exceed kya kare: exception throw, partial state persist, user ko graceful message — chup-chaap khatam nahi.

Idempotency aur persistence

def place_order(cart_id, idem_key):
    existing = idem_store.get(idem_key)   # pehle hi ho chuka?
    if existing:
        return existing                    # dobara side effect mat karo
    result = payments.charge(cart_id)
    idem_store.put(idem_key, result)       # aage kabhi retry ho toh safe
    return result

# idem_key = order_id + action ka stable hash
# retry tab safe hai jab operation idempotent ho — nahi toh refund dobara!

Retries se pehle socho: kya dobara chalana safe hai? Read-only — hamesha safe. Refund/send/delete — idempotency key ke bina kabhi nahi. Yahi hai "idempotent operations" ka asli matlab.

• Persistence: har step ka state (thread_id ke saath) store karo — crash/interrupt ke baad wahi se resume.
• Key design: natural key lo (order_id + action), random nahi — warna retry naya key bana dega.
• At-least-once world: networks aur timeouts retry karwaate hain — idempotency hi wo guarantee hai jo safe banati hai.

Fallbacks aur human escalation

• Fallback chain: primary tool fail → alternative (search fail → list), model fail → cached/default response, plan fail → saved partial result.
• Escalation rule: agent jab safely continue na kar sake — budget hit, confused, consequential decision — tab human ko do.
• Escalation payload: reason, transcript/state reference, attempted actions, suggested next step. Sirf "error ho gaya" bhejna bekaar hai.
• Never-say-die nahi: kabhi-kabhi stop hona hi sahi outcome hai. Predictable failure > unpredictable heroics.

def escalate(reason, thread_id, attempted, suggestion):
    queue.push({
        "reason": reason,                    # kyun ruke
        "transcript_ref": thread_id,         # kahan tak pahuncha
        "attempted": attempted,              # kya-kya try kiya
        "suggested_action": suggestion,      # aage kya kar sakte ho
        "state_snapshot": save_state(),      # resume ke liye
    })
    return "Ek specialist jaldi se humari taraf — progress save hai."

Progress, control aur understandable execution

• Progress surface karo: current task, abhi kaunsa tool chal raha hai, results/sources — spinner ke bajaye events bhejo (tool_start, tool_result, approval_needed).
• User ko control do: cancel, pause, resume, redirect — lambi run par yeh buttons zaroori hain. Cancel ka matlab hai run ko stop kar state save karo.
• Approval prompts: consequential action se pehle clear ask — kya hoga, kitna, kisne bola.
• Understandable, par private reasoning nahi: short status + sources + action summary dikhao — model ki poori chain-of-thought screen mat kholo.

Exercise

Common mistakes

• Sirf steps ka budget rakhna: Time aur cost budget bhi do — ek dheema tool ghanta rok sakta hai aur ek bada run poora bill. Charon alag-alag limits hain.
• Retries bina idempotency ke: Timeout par retry = refund dobara, order dobara. Side-effect wale operations natural key se idempotent banao, tabhi retry safe hai.
• Failure ko chhupana: Silent stuck run user ko sabse zyada pareshan karta hai. Current tool, next step, aur cancel option dikhao — control dena hi asli UX hai.
• Poori reasoning stream karna: Private reasoning dikhne se trust nahi, confusion aati hai. Short status + sources + summary dikhao, detailed thought andar rakho.

budget:     max distance / max fare — uske baad ride rukti hai
fallback:   road band -> alternate route ya pickup point shift
progress:   live location + ETA + driver ka naam (tool calls dikhao)
control:    cancel / change destination / share trip (cancel, redirect)