Causal chaining instead of span trees
The core architectural decision in ZizkaDB is explicit parent_id chaining. Most observability platforms record span trees that show what happened but make it difficult to trace why. In ZizkaDB, each agent action—user message, tool call, LLM response—stores the event ID of the step that triggered it. A user message creates one event. A tool call references that event as its parent. An LLM response references the tool call. Walking backward through these links reconstructs exactly why the agent reached any decision. The why command surfaces this chain from the terminal as zizkadb why <event_id> or in Python as (await db.why(event_id)).print(). The dashboard mirrors this in the Activity view, where clicking an event on a support-bot session reveals a Why? (causal) tab that walks the chain to its origin.
Starting a local stack in one command
Self-hosting requires Docker. The quickstart script pulls configuration and images in a single curl command, or teams can clone the repository and run scripts/setup-local.sh. The stack starts the API on localhost:8000, a login dashboard on localhost:3001, and Swagger documentation at localhost:8000/swagger. Local development uses a built-in dev key, so no API key configuration is needed for evaluation. The Python SDK lets teams scaffold a project with zizkadb init my-agent and begin logging agent steps within minutes.
Integration surface across frameworks
Native integrations cover Python, TypeScript, LangChain, CrewAI, LiveKit, and MCP. The zizkadb-livekit package records voice agent sessions as transcripts in the Activity view, one session per LiveKit call. The MCP server, installed via uvx zizkadb-mcp, allows tools such as Cursor to query the audit trail directly. A Swagger-documented REST API covers any framework outside the native SDKs. The worked example at worked/01-support-order-delay demonstrates a complete support bot flow with causal logging.
Production functions beyond logging
For deployed agent systems, ZizkaDB provides functions that go beyond basic audit trails. The db.baseline() method detects when agent behavior drifts from past sessions, flagging anomalies that might indicate prompt injection, model degradation, or configuration changes. The db.at() function reconstructs the agent's knowledge state at any historical timestamp, supporting incident analysis and compliance audits. Semantic search over agent history runs through db.search(), while db.context_for() injects relevant past events into active prompts to give agents long-term memory. The db.forget() function handles GDPR erasure requests filtered by metadata, enabling data deletion without dismantling the audit trail.
Cloud pricing and licensing model
The managed cloud option at db.zizka.ai removes Docker maintenance overhead. The Pro plan costs €29 per month with 50,000 events and two API keys. The Team plan costs €69 per month with 100,000 events and five API keys. Plan targets apply to managed cloud deployments but are not enforced through the API. The operator admin console and VPC deployment live in a separate private repository, keeping the self-hosted stack under AGPL-3.0 licensing while the MCP server remains MIT. Telemetry can be disabled by exporting ZIZKADB_TELEMETRY=false.
How it differs from observability platforms
ZizkaDB distinguishes itself from span-tree-focused tools like Langfuse and LangSmith through explicit parent_id chains and the why command. Self-hosting under AGPL eliminates trace-based billing, which grows substantial at scale. The EU AI Act Article 12 compliance orientation means the audit trail is structured for regulatory requirements alongside developer debugging needs. The project includes integration guides, troubleshooting documentation, and a community forum for issues and discussions.