Error Handling and Context Budget

~36 min · errors, context, budgets

Level 0Observer

0 XP0/40 lessons0/12 achievements

0/100 XP to next level100 XP to go0% complete

Production loops fail in ordinary ways

Tools timeout. APIs return partial data. The model calls the right tool with the wrong argument. A loop reaches its step budget. Context fills up and the most important decision falls out of view. None of that is exotic. That is Tuesday.

A real single-agent loop treats failures as structured observations, not as exceptions sprayed into the transcript. The model needs enough information to recover, and the operator needs enough information to debug.

Context budget is a safety budget

Do not run until the context window is full. Once the margin is gone, the agent loses room for tool results, recovery, compaction, and human handoff. Good agents stop before the wall.

Recoverability beats optimism

Every tool result should say whether it succeeded, whether retry is allowed, what changed, and what the next safe action is. Errors should carry type, message, retryability, and a compact trace id.

Code

Recoverable tool envelope·python

def execute_tool_safely(name, args, trace_id, timeout=30):
    try:
        result = execute_tool(name, args, timeout=timeout)
        return {
            "ok": True,
            "tool": name,
            "trace_id": trace_id,
            "changed_state": result.get("changed_state", False),
            "data": result,
        }
    except TimeoutError:
        return {
            "ok": False,
            "tool": name,
            "trace_id": trace_id,
            "error_type": "timeout",
            "retryable": True,
            "message": f"{name} timed out after {timeout}s",
            "next_safe_action": "retry_with_smaller_input",
        }
    except PermissionError as exc:
        return {
            "ok": False,
            "tool": name,
            "trace_id": trace_id,
            "error_type": "permission",
            "retryable": False,
            "message": str(exc),
            "next_safe_action": "ask_for_human_approval",
        }

Context margin gate·python

def should_compact_or_stop(token_count, max_context, active_tool_budget=8000):
    hard_margin = max_context * 0.15
    required_margin = max(hard_margin, active_tool_budget)
    remaining = max_context - token_count
    if remaining < required_margin:
        return {
            "decision": "compact_before_next_tool",
            "remaining_tokens": remaining,
            "required_margin": required_margin,
        }
    return {"decision": "continue", "remaining_tokens": remaining}

External links

Exercise

Write a failure envelope for a web search timeout, a schema validation error, and a permission denial. Mark retryability and next safe action.

Hint

If every error says 'try again', the executor is not thinking.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousClaude Tool Use: tool_use and tool_result Next →System Prompt and State Contract

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.