Troubleshooting

A field guide to the failure modes you hit running an agent loop in production. Each entry follows the same shape: symptom, cause, fix. Pair it with the tool reference and the rules when debugging.

Quick Triage

Infinite Loops

The agent calls tools forever, oscillates between two actions, or re-plans without converging.

A correct loop has three exits: a final answer, a step cap, and an error budget.

MAX_STEPS = 12
for step in range(MAX_STEPS):
    resp = client.messages.create(model=MODEL, messages=messages, tools=TOOLS)
    if resp.stop_reason != "tool_use":
        return resp  # natural completion -> exit
    messages.append({"role": "assistant", "content": resp.content})
    messages.append({"role": "user", "content": run_tools(resp.content)})
else:
    raise RuntimeError(f"agent exceeded {MAX_STEPS} steps")

Detect oscillation by hashing each (tool_name, input) and bailing on repeats:

key = (block.name, json.dumps(block.input, sort_keys=True))
seen[key] += 1
if seen[key] > 2:
    raise RuntimeError(f"looping on {block.name}")

Hallucinated Tool Calls

The model invents a tool name you never defined, or passes arguments that violate the schema.

Never let an unknown tool throw. Return a structured error so the model can recover on the next turn:

def dispatch(block):
    if block.name not in REGISTRY:
        return {"type": "tool_result", "tool_use_id": block.id,
                "content": f"Error: unknown tool '{block.name}'.",
                "is_error": True}
    return REGISTRY[block.name](block.input)

Tight schemas with required, enum, and minimum constraints prevent most argument hallucinations — give the model less room to improvise.

Ignoring Tool Results

The agent calls a tool, then acts as if it never ran — repeating the call, or answering from stale assumptions.

Every tool_use block must be answered by exactly one tool_result with the same id, in the very next user turn:

results = []
for block in resp.content:
    if block.type == "tool_use":
        results.append({
            "type": "tool_result",
            "tool_use_id": block.id,        # MUST match
            "content": str(dispatch(block))[:8000]  # cap size
        })
messages.append({"role": "user", "content": results})

Context Overflow

The request fails with a token/context error, or the agent "forgets" early instructions deep into a long run.

A simple sliding window plus a running summary keeps context bounded:

def compact(messages, keep=6):
    if len(messages) <= keep + 1:
        return messages
    summary = summarise(messages[1:-keep])  # one cheap LLM call
    note = {"role": "user", "content": f"[Summary so far]\n{summary}"}
    return messages[:1] + [note] + messages[-keep:]

Prefer returning handles over payloads — write the 5 MB file to disk, return the path.

Getting Stuck

The agent declares it cannot continue, asks the same clarifying question repeatedly, or produces empty turns.

Give the model an explicit escape hatch — an ask_human tool it can call when blocked — so "stuck" becomes a clean, observable outcome rather than a silent hang. See Lesson 5 for re-planning patterns when the environment shifts mid-task.

Unsafe Actions

The agent deletes data, sends real emails, runs destructive shell commands, or burns through budget unchecked.

Classify tools by blast radius and require confirmation for the dangerous ones:

DESTRUCTIVE = {"delete_file", "send_email", "run_shell", "charge_card"}

def guarded(block):
    if block.name in DESTRUCTIVE and not approve(block):
        return {"type": "tool_result", "tool_use_id": block.id,
                "content": "Denied by guardrail: action not approved.",
                "is_error": True}
    return dispatch(block)

Enforce a hard resource budget (cumulative tool calls and tokens) alongside the step cap from Infinite loops — abort the run the moment it is exhausted. Full safety architecture, sandboxing, and the principal hierarchy are covered in Lesson 7.

Where to Go Next