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).