DEV Community

Ruca.
Ruca.

Posted on

I Built an Investigation-First Debugger for AI Agents — TraceMotive v0.3

#ai #opensource #python #debugging

I Built an Investigation-First Debugger for AI Agents — TraceMotive v0.3

I just released TraceMotive v0.3.0.

TraceMotive is an open-source, local-first debugging tool for AI agent executions.

GitHub:

https://github.com/doraemonfv-glitch/tracemotive

The problem

Imagine you have two agent executions.

One worked.

One didn't.

Traditional tracing gives you the raw execution data, which is useful — but you still have to answer the hard question yourself:

Where should I start looking?

That is the problem I wanted v0.3 to focus on.

Good run vs bad run

The new workflow is:

reference run
      vs
changed run
      ↓
structural alignment
      ↓
first evidence-supported behavioral divergence
      ↓
deterministic findings
      ↓
investigation starting point
Enter fullscreen mode Exit fullscreen mode

The important word here is supported.

TraceMotive does not try to guess the root cause.

It identifies the first behavioral difference that can be supported by the available structural evidence.

What can it detect?

v0.3 can produce deterministic findings such as:

  • tool input changed
  • tool output changed
  • new error observed
  • error resolved
  • tool added
  • tool removed
  • execution subtree added or removed
  • tool repetition changed

It can also surface context-only changes such as:

  • model changed
  • request parameters changed
  • trace status changed

Those context changes do not automatically become the investigation starting point.

Uncertainty is a feature

A debugger shouldn't pretend to know something it doesn't.

For example, repeated calls can be difficult to align safely.

Consider:

Run A:
weather()
weather()
weather()

Run B:
weather()
weather()
weather()
Enter fullscreen mode Exit fullscreen mode

Pairing the first call on the left with the first call on the right simply because they have the same position can create false matches.

TraceMotive deliberately avoids that.

When evidence is ambiguous, incomplete, redacted, or unavailable, the result may be:

uncertain
Enter fullscreen mode Exit fullscreen mode

instead of inventing an answer.

Investigation-first UI

v0.3 also introduces a new comparison interface.

Instead of showing the full raw comparison first, the UI prioritizes:

  1. the investigation state
  2. the first supported investigation point
  3. evidence observed there
  4. additional behavioral observations
  5. context
  6. uncertainty
  7. detailed raw comparison

The existing detailed comparison remains available through /api/v2.

The new investigation API lives at:

GET /api/v3/compare/{left_trace_id}/{right_trace_id}
Enter fullscreen mode Exit fullscreen mode

Try it without an API key

v0.3 includes a deterministic local demo.

Install:

pip install tracemotive==0.3.0
Enter fullscreen mode Exit fullscreen mode

Start TraceMotive:

tracemotive serve
Enter fullscreen mode Exit fullscreen mode

Then open another terminal:

tracemotive demo
Enter fullscreen mode Exit fullscreen mode

The demo creates a reference execution and a changed execution and prints a URL that opens directly in the investigation UI.

No OpenAI API key is required for the demo.

Still local-first

The privacy model remains important to me.

TraceMotive keeps:

  • loopback-only Collector/UI serving
  • local SQLite persistence
  • privacy-controlled content capture
  • redaction before transport
  • no TraceMotive analytics
  • no external TraceMotive telemetry

What TraceMotive does NOT claim

TraceMotive does not prove causality.

It does not say:

This change caused the failure.

It says something closer to:

This is the first behavioral divergence supported by the evidence. This is a reasonable place to begin investigating.

That distinction became one of the biggest design principles in v0.3.

What's next?

The next big area is broader real-world integration validation.

OpenAI Agents SDK is currently the primary validated adapter.

I also want to keep testing whether this investigation workflow is actually useful on real agent failures instead of just adding more observability features.

If you build AI agents, I'd love feedback — especially examples where TraceMotive becomes too conservative or points you somewhere unhelpful.

GitHub:

https://github.com/doraemonfv-glitch/tracemotive

PyPI:

pip install tracemotive==0.3.0
Enter fullscreen mode Exit fullscreen mode

Top comments (0)