ZizkaDB

When your agent misbehaves, see why.

Self-hosted audit trail for AI agents — one command or one dashboard click from any step back to root cause.

Try it ↓ · START_HERE.md · CONNECT.md · Cloud →

Try it (60 seconds)

Requires Docker. First image pull may take 5–10 minutes.

curl -fsSL https://raw.githubusercontent.com/Zizka-ai/ZizkaDB/main/scripts/quickstart-remote.sh | bash

You should see:

tool_call · lookup_order · ORD-8842
  └── llm_response · gpt-4o
        └── user_message · Why was my order delayed?

Run again anytime: pip install zizkadb-sdk && zizkadb demo

---

Why?

Every agent team asks: Why did it say that? Why did it call that tool?

1. Log agent steps with parent_id (each step links to the one that caused it).
2. Ask why — terminal: zizkadb why <event_id> or Python: (await db.why(event_id)).print()
3. See the chain — walk back to the user message, wrong tool, or bad context.

Dashboard (same chain): Activity → support-bot → click an event → Why? (causal) tab.

---

Connect (3 lines)

import asyncio
from zizkadb import ZizkaDB

async def main():
    async with ZizkaDB(host="http://localhost:8000") as db:
        user = await db.log(agent="my-bot", event="user_message", data={"text": "Why is my order late?"})
        tool = await db.log(agent="my-bot", event="tool_call", data={"tool": "lookup_order"}, parent_id=user.event_id)
        (await db.why(tool.event_id)).print()

asyncio.run(main())

Full guides: CONNECT.md · LangChain · CrewAI · LiveKit (voice) · MCP / Cursor

---

Integrations

Python	TypeScript	LangChain	CrewAI	LiveKit	MCP	REST
zizkadb-sdk	zizkadb-sdk	zizkadb-langchain	zizkadb-crewai	zizkadb-livekit	uvx zizkadb-mcp	Swagger

Scaffold a project: zizkadb init my-agent --template basic

Voice agents (LiveKit)

pip install zizkadb-livekit

One LiveKit call → one Session in Activity (transcript only, no audio in ZizkaDB). Full guide: CONNECT.md → LiveKit · docs/integrations/livekit.md · example.

---

Managed cloud (Pro / Team) — optional

Same Why? feature — hosted at db.zizka.ai. No Docker to maintain.

	Pro	Team
Price	€29 / mo	€69 / mo
Events / mo†	50k	100k
API keys	2	5

Sign up → · Enterprise VPC →

† Plan targets on managed cloud; not enforced in API yet. See docs/README.md.

More features — drift, time-travel, search, GDPR

Function	What it does
db.baseline()	Detect when agent behavior drifts vs past sessions
db.at()	Reconstruct what the agent knew at a timestamp
db.search()	Semantic search over agent history
db.context_for()	Inject relevant past events into prompts
db.forget()	GDPR erasure by metadata filter

FAQ

Do I need to clone this repo?
No — the curl quickstart downloads config + Docker images only.

Do I need an API key locally?
No — http://localhost:8000 uses a built-in dev key. Dashboard: localhost:3001/login.

How is this different from Langfuse / LangSmith?
They observe span trees. ZizkaDB audits with explicit parent_id chains and db.why() on your Postgres — self-host under AGPL, no trace billing.

Voice agents with LiveKit?
Install zizkadb-livekit — one pip command, connect to Docker with ZIZKADB_HOST=http://localhost:8000. See LiveKit guide.

zizkadb demo connection refused?
Start the stack: curl -fsSL …/quickstart-remote.sh | bash or bash scripts/setup-local.sh.

Docs & community

Worked example	worked/01-support-order-delay
Examples	examples/ — includes LiveKit voice agent
LiveKit integration	docs/integrations/livekit.md
Self-hosting	wiki/Self-Hosting
Integrate any agent	docs/integrate/
Issues · Discussions	Issues · Discussions
Contributing · Security	CONTRIBUTING.md · SECURITY.md

_{AGPL-3.0 · MCP server MIT · Disable telemetry: export ZIZKADB_TELEMETRY=false}