Causal Lineage and Session Replay with ZizkaDB

Описание и применение

ZizkaDB решает проблему отладки поведения LLM-агентов, храня решения в виде графа причинно-следственных связей. В отличие от стандартных трассировщиков, он позволяет отслеживать, почему агент принял конкретное решение, и воспроизводить сессии для поиска корневых причин ошибок.

Задача

Standard distributed tracing tools provide span trees useful for performance debugging but fail to explain the causal chain of agent decisions, making it difficult to determine why an LLM agent produced a specific wrong answer or behavior.

Результат

ZizkaDB enables developers to trace the 'why' behind LLM agent decisions by storing events as a causal graph rather than a flat list. This allows for precise root-cause analysis of behavioral errors and detection of prompt drift.

Рабочий процесс

• Self-host ZizkaDB using the quickstart script or clone the repository.
• Install the ZizkaDB Python SDK (zizkadb-sdk).
• Initialize the ZizkaDB client in the application code.
• Log events (user messages, tool calls, responses) using db.log(), explicitly passing the parent_id from the previous event to establish causal links.
• Use the why() method on a specific event_id to retrieve the causal decision path leading to that event.
• Use the replay() method to reconstruct the entire session timeline with state at each step.
• Optionally use baseline() and check_drift() to detect behavioral regressions against known-good snapshots.

Доказательства

Instead of storing spans like a tracing tool, it stores agent decisions as a graph, where each event points to the event that caused it

Источник

why() walks the parent chain backward and returns the decision path that produced it

Источник