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

来源