Which AI agent broke it? Tracing multi-agent failures back to the first wrong step with FalkorDB

Pulkit Agarwal — Sun, 18 Oct 2026 17:31:46 +0000

Try it: butterfly-falkordb.netlify.app · Code: github.com/PulkitAgrwal/butterfly

The problem: the mistake is never at the end

Here is a real failed run from the Who&When benchmark. A user asks a team of AI agents a simple question:

Where can I take martial arts classes within a five-minute walk from the New York Stock Exchange after work?

A planner makes a plan. A web-browsing agent searches, opens a result, and at step 12 clicks a link that lands on an unrelated website. Nobody notices. For the next fifteen steps the team goes in circles, and at step 28 the run ends without an answer.

If you build multi-agent systems, you know this shape. The failure shows up at the end, but the mistake that caused it happened much earlier, and every step after it built on it. Finding that first wrong move means scrolling through the whole log, sometimes more than a hundred steps, and guessing.

I wanted a tool that answers two questions in one click: which agent broke it, and at which step?

The idea: stop reading the log, ask the graph

A failed run is not really a list of messages. It is a set of dependencies: this step used a URL that step introduced, this agent followed that instruction, this answer relied on that tool output. That is a graph, so I built Butterfly on FalkorDB for the WeMakeDevs × FalkorDB Graph Hacks hackathon.

The name comes from the butterfly effect: one small flap early on, one storm at the end. Butterfly looks for the flap.

1. Turn the run into a graph

Every message becomes a (:Step) node, with the agent that wrote it and the facts it introduced: URLs, file names, numbers and names. When a later step reuses something an earlier step introduced, or follows its plan, instruction or tool result, Butterfly adds an edge:

(:Step)-[:DEPENDS_ON {via}]->(:Step)    // later step relied on earlier step
(:Step)-[:FEEDS]->(:Step)               // the same link, pointing forward
(:Step)-[:BY]->(:Agent)
(:Step)-[:INTRODUCES]->(:Entity)

Each run is its own graph (butterfly:hc-1, butterfly:ag-18, ...), written with UNWIND + MERGE, so re-importing never duplicates anything. No LLM is involved in building it.

2. Let FalkorDB rank the suspects

The intuition: the decisive mistake is usually a step that a lot of the later run builds on. FalkorDB's built-in breadth-first search measures exactly that:

MATCH (s:Step {candidate: true})
CALL algo.BFS(s, 200, 'FEEDS') YIELD nodes
RETURN s.idx AS idx, size(nodes) AS downstream,
       any(n IN nodes WHERE n.is_final) AS reaches_final

Combined with how many new facts a step introduced and how early it happened, this gives every step a score. Most of the work is done here, before any model is called.

3. One LLM call, only on the top suspects

Instead of handing a model the entire log, Butterfly gives one small LLM call just the top 5 to 10 suspects with their neighbours, and asks it to pick the decisive one and explain why.

4. Look for the chain back to the failure

Finally, a shortest-path query looks for the chain of dependencies from the failed final step back to the chosen step:

MATCH (f:Step {is_final: true}), (s:Step {idx: $idx})
WITH shortestPath((f)-[:DEPENDS_ON*]->(s)) AS p
RETURN [n IN nodes(p) | n.idx] AS steps, [r IN relationships(p) | r.via] AS via

On the martial-arts run it returns 28 ← 12 in well under a millisecond: the final step depended directly on what step 12 introduced. In the app, that becomes an arrow from the mistake to the failure.

Every query runs with GRAPH.RO_QUERY and a timeout, the image is pinned, and the app shows the exact Cypher that ran, so nothing is a black box.

Does it actually work? 184 real failures

I didn't want to grade myself on faults I planted, so I evaluated on all 184 failures in Who&When (ICML 2025), a public benchmark where human experts labelled which agent caused each failure and at which step. The baseline is the same model (gpt-5.4-mini) reading the entire log, with the steps numbered for it, so it doesn't lose points by miscounting.

Method	Finds the step	Names the agent	LLM input per run
Whole log, steps numbered	33.2%	53.8%	7.8k tokens
Butterfly, graph only (no LLM)	28.3%	58.2%	none
Butterfly, graph + one call	34.8%	62.5%	3.8k tokens

What that means, honestly:

Naming the responsible agent: Butterfly is better, 62.5% vs 53.8%, and the difference is statistically significant (paired McNemar test, p = 0.04).
Finding the exact step: a tie, about a third each. It is a hard problem for everyone; even the paper's own methods struggle with it.
Cost: about half the LLM tokens, because the graph decides what the model needs to read.
No LLM at all: the graph alone finds the exact step 28% of the time.

What I learned

Be honest about what the graph proves. My first version showed "proved with a shortest path" on every answer. Then I tested it like a judge would and found that for most runs the graph finds no direct chain from the chosen step to the failure: a chain exists for 66 of the 184 answers. Now the app says "no direct chain found" instead of drawing an arrow it can't back up. A chain shows that the failure depended on that step; whether the step was wrong is decided by the ranking and the LLM call. I'd rather show less and have all of it be true.

Fair baselines matter more than fancy ones. The benchmark's official prompt asks the model to count steps itself, and it miscounts constantly. Against that prompt, Butterfly looked about twice as good. Once I numbered the steps for the baseline, the step-finding gap disappeared. The real win is naming the agent, and doing it with half the tokens.

FalkorDB details worth knowing:

One graph per key made per-run isolation trivial: 184 graphs, zero extra setup.
algo.BFS and shortestPath run right inside Cypher, so ranking and the chain are a few lines of query, not a separate graph library.
algo.BFS(s, 0, ...) did not mean "unlimited depth" for me; it returned nothing. Pass an explicit max depth.
I pinned falkordb/falkordb:v4.22.1 after hitting crashes on 6.0.x.
If you see unknown command GRAPH.QUERY, you are probably talking to a plain Redis on port 6379, not FalkorDB. I moved FalkorDB to 6380.
After a server restart, an index lookup for idx: 0 came back empty for me, so a MERGE re-import could duplicate step 0. Reading one row per step index keeps the app correct.

Use it from your own agent: an MCP server

A debugger is only half the story if agents can't use it themselves. So Butterfly also runs as an MCP server. Any MCP client, such as Claude Code, Claude Desktop or Cursor, can call it as a tool:

claude mcp add butterfly -- uv run --directory /path/to/butterfly python -m butterfly.mcp_server

It exposes four tools:

list_failed_runs: the 184 failed runs
diagnose_run: the decisive agent and step, the reason, and the dependency chain back from the failure when the graph has one
get_step: one step's cleaned message
query_run_graph: any read-only Cypher on that run's FalkorDB graph (GRAPH.RO_QUERY with a timeout, so writes are rejected)

So you can ask your agent "which step broke run hc-1?" and it calls diagnose_run, gets web browser, step 12, chain 28 ← 12, and can then query the graph itself to see what depended on that step. One agent, debugging another.

Try it

Watch: the 2:40 demo
Click around: butterfly-falkordb.netlify.app. Pick any of the 184 failed runs and press Find the mistake.
Run it live: clone the repo and run docker compose up. No API keys are needed; the LLM answers are cached.
Plug it into your agent: see the MCP section of the README.

Next, I want to try Butterfly on live agent traces instead of a benchmark, so the MCP server can debug runs as they fail.

If you build multi-agent systems, I'd love to hear how you debug them today.

DEV Community: Pulkit Agarwal