Debugging an agent run end-to-end - Apragya Docs

When an agent run goes wrong, the platform gives you an unusually rich trail - the run itself, every node it touched, every LLM call, every tool call, every cost line, every guardrail check. This guide is the order to walk that trail in when you're trying to figure out what went wrong, plus the five failure modes we see most often.

Start with the Run row

Sidebar > Agents > [agent] > Runs > [run_id]. The Run row tells you the high-level shape - status (completed / failed / paused), duration, total cost, the input payload, the final output (or error). 80% of debugging starts and ends here.

Walk the RunNode trace

Each step the agent took writes a RunNode row - the model call, every tool invocation, every guardrail check. Click into the Run > Trace tab to see them in chronological order with their individual durations + costs + outputs. The failing node usually has status=failed and an error message; the nodes before it are still useful for context.

LLMTrace for prompt-level detail

When the failure looks like the model misunderstood the prompt, the LLMTrace tab on a step gives you the full conversation - system prompt, user message, the model's response, and its tool-choice decisions. Use this to confirm "did the prompt actually say what I thought it said?".

Cost records when the bill looks wrong

The Run > Cost tab breaks the AI Credit consumption down by step, model, and tool. Useful when a run cost far more than you expected - usually one rogue node looped, or one tool returned a very large payload that got fed back to the model. The Cost tab makes the culprit obvious.

The five most common failure modes

1. Guardrail tripped (run paused, not failed) - HITL pending. Check the HITL Reviews queue, not the run log. Common confusion source
2. Tool returned an error the prompt didn't anticipate - the agent doesn't know what to do; output goes stale. Fix by adding tool-error handling to the system prompt
3. AI Credit budget exceeded mid-run - the run terminates with a budget error. Trim what the agent is being asked to produce, or raise the per-run cap deliberately if the task legitimately needs it
4. Custom tool webhook timeout - external service slow/down. Add retries + a tighter timeout on the tool definition; consider a fallback path
5. Hallucinated tool call - the model invokes a tool with garbage parameters. Tighten the tool's input schema; consider one-shot examples in the system prompt

When a failure repeats but you can't reproduce it locally, capture the exact input payload from the Run row and drop it into a new test case on the Tests tab. The test now reproduces deterministically. Iterate on the prompt with the test running; once the test passes consistently, you have your fix - publish a new version.

When to escalate to support

If a run failed with a status the docs don't explain, or with an error message you've never seen, or if a guardrail tripped where it shouldn't have - the Run row's Copy Diagnostic button collects everything support needs (run_id, trace, logs, prompt, last input). Paste that into a ticket at /contact-support; first reply typically lands within 2 hours during business days IST.