> ## Documentation Index
> Fetch the complete documentation index at: https://reagent-ai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Stack Traces

> Readable failure diagnostics showing the full tool-calling history.

## Overview

When an assertion fails, reagent-flow attaches an **Agent Stack Trace** — a readable dump of every turn, tool call, and result. This gives you the full context of what the agent did, making it easy to diagnose why the assertion failed.

## Example output

```
AGENT STACK TRACE — refund_flow
================================
Turn 0: lookup_order(order_id="123")
  → {"status": "active", "amount": 49.99}
Turn 1: process_refund(order_id="123", amount=49.99)
  → {"success": true}
Turn 2: [text response] "Refund processed."
================================
✗ "delete_account" was never called (3 turns, 2 tool calls)
```

## What's included

Each turn in the stack trace shows:

* **Turn index** — positional ordering
* **Tool call** — function name and arguments
* **Tool result** — the return value or error
* **Text responses** — LLM text-only responses (marked as `[text response]`)

The final line shows the assertion that failed and a summary of trace stats.

## When they appear

Agent Stack Traces are attached to **every** assertion failure — handoff contracts, tool output contracts, flow assertions, golden baseline diffs, and more. They're part of the `AssertionError` message, so they appear directly in pytest output.

## Reading a stack trace for handoff failures

For multi-agent handoff failures, the stack trace shows the child session's full history plus the handoff context:

```
AGENT STACK TRACE — security-review
================================
Handoff context: {"vendor_name": "ClearVoice AI", "data_access": {"handles_personal_data": true}}
Turn 0: assess_security_risk(vendor_name="ClearVoice AI")
  → {"risk_level": "LOW", "reason": "..."}
================================
✗ handoff field 'data_access.contains_customer_pii': missing from data
```

The `Handoff context` line shows exactly what the child received, making it easy to spot the drift (here: `handles_personal_data` instead of `contains_customer_pii`).