Blog · ← All posts
Reading a Causality Graph: Debugging Multi-Agent Incidents Across the DAG
By the Ingenious AI team · Published: November 14, 2026 · Reviewed: November 14, 2026 · 7 min read
The short answer: A causality graph turns a multi-agent incident from interleaved timelines into a readable map: nodes are recorded actions, edges are caused_by links naming the exact record that triggered each action. Debug by starting at the harmful action, walking edges backward to the root cause (a human instruction, an external event, or an agent's uncaused decision), then walking forward from the root to enumerate everything it touched. Fan-outs show blast radius, fan-ins show where multiple agents' outputs combined, and agents absent from the graph are cleared by evidence, not by assertion.
Replay a recorded agent incident free → Step through a real recorded run in the replay view, or paste ledger records into the public verifier and get a VERIFIED/BROKEN verdict in seconds — no signup.
Single-agent incidents have a timeline. Multi-agent incidents have a braid: five streams of records, interleaved in time, each locally plausible, with the failure living in the joins between them. Reading five timelines in parallel and holding the joins in your head is how postmortems produce the phrase 'a perfect storm of contributing factors' — the sound of a graph problem being described by people without the graph.
Agent Flight Recorder records caused_by links between agents' actions, rendering the workflow as a directed acyclic graph. This guide is the reading method: how the graph is structured, the three walks that solve incidents, and the patterns — fan-out, fan-in, the silent branch — that experienced readers look for first.
What is a causality DAG? a directed acyclic graph of recorded agent actions in which an edge from record A to record B means B's action was triggered by A's output — B's record carries a caused_by reference to A's exact record (agent, sequence, hash). The graph is acyclic because causes precede effects, and it is built at recording time from the workflow's actual handoffs, not reconstructed afterward from timestamps.
Anatomy: nodes, edges, and roots
A node is one ledger record: an action with its agent, timestamp, summary, and outcome. An edge is a declared cause: this action happened because that record's output arrived. Roots are nodes with no incoming agent edge — their causes are human instructions, schedules, or external events, each recorded as such — and roots matter because every backward walk ends at one, and the root is where responsibility ultimately sits: a person's instruction, a system's event, or an agent's autonomous decision with no upstream agent to share the story.
The graph inherits the ledger's trust properties. Edges name records by hash, so a claimed cause can be opened and read; the whole structure verifies with the chains it spans. A causality graph drawn from memory in a postmortem is a hypothesis; this one is an index into evidence.
Walk one: backward from the harm
Start at the action that did the damage — the wrong charge, the bad send — and follow its incoming edges: what triggered this agent? Then that record's causes, recursively. The walk has a discipline: at fan-ins, follow every incoming edge, because the harmful decision often needed two inputs (the data agent's stale figure AND the planner's uncritical acceptance), and stopping at the first plausible cause manufactures a single culprit for a joint failure. The walk ends at roots; the deepest agent node whose inputs were wrong, or whose judgment first departed, is your first-divergence neighborhood — now located across agents, in the join where it actually happened.
Walk two: forward from the root — the blast radius
From the identified root or divergence, walk outgoing edges to enumerate everything downstream: every action the bad output touched, across every agent. This is the scoping walk, and its output is the incident's true extent — usually different from the reported extent in both directions (some reported effects turn out unrelated; some quiet effects turn out connected). Forward enumeration from the graph, reconciled against downstream systems, produces the bounded impact statement that communications and remediation are built from. Without the graph, blast radius is estimated from timestamps and hope.
Walk three: the absence walk — clearing the innocent
The walk nobody plans is often the most valuable: check which agents are NOT in the harmful subgraph. The summarizer everyone suspected, the new agent deployed that morning — if their records carry no path to the harm, they are cleared by the structure of the evidence, and the postmortem can say so in one sentence with a citation. Absence-clearing ends witch-hunts, protects teams, and — in regulated settings — bounds the incident's compliance footprint to the agents actually involved. It works only because the graph is complete: an edge set built by declaration at handoff time, in a system whose coverage is measured.
Patterns to read at a glance
Three shapes recur. The amplifier: one root fans out to dozens of actions across agents — a bad datum with many consumers — whose fix is at the root and whose lesson is about propagation controls. The combiner: several agents' outputs fan into one decision that none of them would have made alone — the fix is at the join, usually a missing validation of combined inputs. And the silent branch: an expected consumer never appears — the reviewer agent that should have checked the output has no node — revealing a routing failure that pure timeline reading almost never catches, because humans are bad at noticing that something is missing. Train reviewers to ask the graph all three questions before writing a word of narrative.
Five actions you must take today
Graphs are only readable if they are complete and if the team practices reading them:
- Enforce caused_by at every handoff. The workflow layer attaches the causing record's reference automatically; an agent that cannot name its cause does not get to act on the input.
- Record roots explicitly. Human instructions, schedules, and external events enter the graph as labeled cause events — a walk should end at a named origin, not a shrug.
- Rehearse the three walks on a healthy workflow. Backward, forward, absence — on last week's normal run, in peacetime, so the motions exist before the incident does.
- Scope incidents from the forward walk. The blast-radius statement in every postmortem cites the graph enumeration, reconciled downstream — never a timestamp estimate.
- Check for silent branches in reviews. Every workflow review asks which expected consumers are missing from the graph; absence is a finding with its own line.
Worked example: the pricing error that three agents made together
At fictional B2B supplier Hartwell Industrial, enterprise customers were quoted prices 12% low for one afternoon. The graph for the quoting workflow held that day's 6,204 records across four agents. Backward from a known-bad quote: the quoting agent's calculation cited two causes — the catalog agent's price record (correct) and the promotions agent's discount record, which had applied a consumer promotion to an enterprise account. The promotions record's own cause was a customer-tier lookup whose result came from the data agent — which had read the tier from a cache entry written during a migration, mislabeled for exactly one account segment.
Forward from that cache read, the blast radius enumerated precisely: 143 quotes, 96 sent, 31 already accepted — a bounded, honorable remediation list instead of a panicked all-customers email. The absence walk cleared the approvals agent everyone suspected first: no path from its records to any bad quote; it had never been invoked, because the discount path skipped its threshold check — a silent branch that became the second corrective action.
Fixes landed in three places because the graph showed three places: the cache labeling, the promotions agent's tier validation, and the missing approval invocation. A narrative postmortem would have found one villain. The graph found the system.
FAQ
What if an agent consumes input but the link was not recorded?
Then the graph has a gap exactly where the incident may live — which is why links are enforced by the workflow layer rather than volunteered by agents, and why coverage reviews sample handoffs specifically. When a gap is found in an investigation, mark it as a gap in the postmortem, bound the uncertainty it creates, and let the corrective action be the enforcement fix. A graph with one admitted hole is still more useful than five timelines; a graph that hides its holes is a liability.
How large can these graphs get before they are unreadable?
Production workflows produce thousands of nodes a day, and nobody reads those raw. The reading method is always anchored: start at a node (the harm, the root, the suspect) and walk — the relevant subgraph for an incident is usually tens of nodes. Tooling should render neighborhoods, not universes: the steps around a selected record, expandable edge by edge. If your view opens on the whole fleet, it opens on nothing.
Do causal links replace timestamps?
No — they complement them. Timestamps order events in wall-clock terms and connect the graph to the outside world (the customer's call, the market event); causal edges order events in responsibility terms, which wall-clock order cannot express when agents run in parallel. Incidents are solved by reading both: the graph for structure, the clock for pace — how long a bad output sat unexamined is a timestamps question with real accountability in it.
Can the graph cross into systems we do not record?
It can point at the boundary: an external system's output enters as a root-cause event with its provenance (system, identifier, digest), and your agent's consumption of it is a normal edge. Inside the external system there is no graph — which is an argument for boundary records detailed enough to support the dispute you may one day have with that system's owner, from your side of the wall.
How do we start if our framework does not emit causal links?
At the handoff points you control: most frameworks pass work through a queue, an orchestrator, or a function call, and each pass can carry the causing record's ID as metadata that the receiver's first action record includes. Begin with the consequential workflows — the ones whose incidents would hurt — and let completeness spread from there. Even a partial graph, honestly scoped, outperforms parallel timelines from the first incident it touches.
Start logging your agents free → The free tier gives you the full hash-chained ledger for 1 agent and 1,000 actions a month, with chain verification and replay included.