Multi-tool Agent with Escalation Logic

API mode detection. Reads ANTHROPIC_API_KEY from the environment. If set, the agent loop uses the real Claude API (RealClaudeClient). Without it, the pre-scripted MockClaudeClient runs instead — no API key needed for study.

• get_api_key() — reads env var, returns None if absent
• is_live_mode() — boolean check used by run_demo.py to select the client
• mode_banner() — prints LIVE vs SIMULATION banner at startup
• Supports .env file via python-dotenv (optional dependency)

Defines the structured error taxonomy for tool call failures. The core insight: returning a plain string like "Error: refund too large" forces Claude to parse natural language to decide what to do next. Returning a structured dict with isRetryable and errorCategory enables deterministic branching in the agent loop.

• ErrorCategory enum — TRANSIENT, VALIDATION, BUSINESS, PERMISSION
• TRANSIENT — network timeout, 503 error; isRetryable=True
• BUSINESS — refund above limit, account suspended; isRetryable=False — the rule itself must change first
• VALIDATION — wrong type, missing field; do not retry with same args
• PERMISSION — caller lacks authorization; escalate to human
• make_error_response(error) — serializes to MCP dict format with isError: True
• is_retryable(tool_result) — quick check in the agent loop

# Deterministic branch — no NLP parsing needed
if result["content"]["isRetryable"]:
    result = run_tool(tool_name, args)   # retry once
elif result["content"]["errorCategory"] == "BUSINESS":
    escalate()                           # don't retry

Defines 4 tools in the MCP / Claude tool-use format (name, description, input_schema) plus mock implementations. The central lesson: Claude picks tools by reading their descriptions. Two tools with ambiguous descriptions cause probabilistic wrong selections. Explicit disambiguation prevents this.

• get_customer_by_email — entry point when only email is known; description says "Do NOT use if you already have customer_id"
• get_customer_by_id — secondary lookup; description says "ONLY when you already have the customer_id from a previous step"
• process_refund — description forbids calling without verified customer_id; $500 limit noted
• escalate_to_human — four explicit trigger conditions listed in the description
• MOCK_TOOL_IMPLEMENTATIONS — dispatch table: tool name → function; agent loop uses this dict to route calls

# BAD — ambiguous
"description": "Gets a customer record."

# GOOD — deterministic disambiguation
"description": (
  "Use for INITIAL lookup when you only have the email address. "
  "Do NOT use if you already have the customer_id — "
  "use get_customer_by_id instead."
)

Pre- and post-tool-use hooks. The key architectural insight: prompt instructions are probabilistic ("never process refunds above $500" can be ignored under adversarial input or context dilution). Hook code is deterministic — it always runs before/after the tool regardless of what the model decides.

• pre_tool_use_hook(tool_name, tool_args) — returns None (allow) or an intercept dict (redirect)
• Intercept pattern: when amount > 500, returns {intercepted: True, redirect_to: "escalate_to_human", suggested_args: {...}}
• The agent loop calls the redirect tool instead of the original — model never processes the high-value refund
• post_tool_use_hook(tool_name, tool_result) — normalizes dates to ISO 8601; trims results with >10 keys
• Result trimming rationale: every tool result re-sent on every API call; extra fields cost tokens on every future round-trip

def pre_tool_use_hook(tool_name, tool_args):
    if tool_name == "process_refund":
        amount = float(tool_args.get("amount", 0))
        if amount > ESCALATION_THRESHOLD:  # 500.0
            return {
                "intercepted": True,
                "redirect_to": "escalate_to_human",
                "suggested_args": { ... }
            }
    return None  # allow the call

The complete agent loop: messages → API → tool_use → tool result → repeat until stop_reason == "end_turn". Also defines MockClaudeClient (pre-scripted responses for study) and RealClaudeClient (wraps the real Anthropic SDK with the same interface).

• stop_reason == "end_turn" — the ONLY reliable loop exit signal. Never exit based on whether the response "looks done"
• stop_reason == "tool_use" — must handle ALL tool_use blocks in the response, then loop back
• Context accumulation: messages list grows with every iteration; all tokens re-sent on every API call
• max_iterations=10 safety ceiling prevents infinite loops if stop_reason never reaches end_turn
• Pre-hook intercepts → calls redirect tool with same tool_id so conversation thread stays coherent
• Post-hook normalizes every result before appending to history
• Tool results added as role: "user" (Anthropic API convention)

for iteration in range(max_iterations):
    response = client.messages_create(...)

    if response["stop_reason"] == "end_turn":
        return _extract_text(response["content"])   # ← exit here

    elif response["stop_reason"] == "tool_use":
        # run pre-hook → execute or redirect → run post-hook
        # append assistant message + tool results to messages
        continue   # loop back

Runs 3 back-to-back scenarios illustrating the full range of agent behavior. Each scenario prints the step-by-step loop trace so you can observe exactly what fires at each iteration.

• Scenario 1 — Low-value refund ($50): hook does NOT intercept; process_refund runs and returns refund_id
• Scenario 2 — High-value refund ($750): pre_tool_use_hook intercepts; redirected to escalate_to_human; model never calls process_refund
• Scenario 3 — Multi-intent: account check + refund + manager request; agent decomposes into sequential tool calls; "speak to manager" intent short-circuits to immediate escalation