Framework integrations

Official adapters and starters — same causal log() + parent_id pattern for every stack.

Fastest start (Python): pip install "zizkadb-sdk>=0.5.0" then zizkadb init my-agent --template langchain. The zizkadb init CLI ships with the Python SDK only. Templates: basic, openai, langchain, crewai, mcp-cursor.

Package overview

Python SDK (zizkadb-sdk) — log, why, search, context_for, zizkadb init CLI

TypeScript SDK (npm) — log, why, search, context_for — HTTP client only

zizkadb-langchain — Auto-log LangChain LLM + tool steps (Python)

zizkadb-crewai — Log crew kickoff + output (Python)

zizkadb-livekit — LiveKit voice calls → Sessions + Events (transcript only)

zizkadb-mcp — Cursor / Claude Desktop tools — any language via MCP

Scaffold a project

bashpip install "zizkadb-sdk>=0.5.0"
zizkadb init my-agent --template basic
cd my-agent && cp .env.example .env
pip install -r requirements.txt
python agent.py

OpenAI / Anthropic (SDK)

Use AsyncOpenAI or AsyncAnthropic inside async with ZizkaDB(...). Log the user turn, call the model, log the reply with parent_id=turn.event_id.

python# pip install zizkadb-sdk anthropic
import anthropic
from zizkadb import ZizkaDB

async def run(user_input: str):
    async with ZizkaDB("zizkadb_live_...") as db:
        client = anthropic.AsyncAnthropic()
        turn = await db.log(agent="my-bot", event="user_message", data={"text": user_input})
        response = await client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=1024,
            messages=[{"role": "user", "content": user_input}],
        )
        await db.log(
            agent="my-bot",
            event="assistant_response",
            data={"text": response.content[0].text},
            parent_id=turn.event_id,
        )

LangChain

Install zizkadb-langchain from PyPI. Pass ZizkaDBCallbackHandler in config={"callbacks": [handler]}.

pythonpip install "zizkadb-sdk>=0.5.0" "zizkadb-langchain>=0.1.5" langchain-openai

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
from zizkadb import ZizkaDB
from zizkadb_langchain import ZizkaDBCallbackHandler

async with ZizkaDB("zizkadb_live_...") as db:
    handler = ZizkaDBCallbackHandler(db, agent="my-bot")
    llm = ChatOpenAI(model="gpt-4o-mini")
    await llm.ainvoke([HumanMessage(content="Hello")], config={"callbacks": [handler]})
    (await db.why(handler.last_event_id)).print()

CrewAI

Install zizkadb-crewai from PyPI.ZizkaDBCrewLogger logs kickoff, tasks, and final output with lineage.

pythonpip install "zizkadb-sdk>=0.5.0" "zizkadb-crewai>=0.1.5" crewai

from zizkadb import ZizkaDB
from zizkadb_crewai import ZizkaDBCrewLogger

async with ZizkaDB("zizkadb_live_...") as db:
    logger = ZizkaDBCrewLogger(db, agent="research-crew")
    kickoff = await logger.log_kickoff(goal="Research topic X")
    output = await crew.kickoff_async()
    await logger.log_output(str(output), parent_id=kickoff.event_id)

LiveKit Agents (voice)

Install zizkadb-livekit from PyPI — one command pulls zizkadb-sdk and livekit-agents. One LiveKit call maps to one ZizkaDB session in Activity; transcript text is copied from LiveKit at call end (no audio stored in ZizkaDB).

pythonpip install "zizkadb-livekit>=0.1.0"

import os
from livekit.agents import AgentServer, JobContext, AgentSession, Agent
from zizkadb import ZizkaDB
from zizkadb_livekit import ZizkaDBLiveKitObserver

server = AgentServer()
_observer: ZizkaDBLiveKitObserver | None = None

async def on_session_end(ctx: JobContext) -> None:
    if _observer is not None:
        await _observer.ingest_session_report(ctx)

@server.rtc_session(agent_name="support-voice", on_session_end=on_session_end)
async def entrypoint(ctx: JobContext):
    global _observer
    await ctx.connect()
    db = ZizkaDB(os.getenv("ZIZKADB_API_KEY", "zizkadb_live_..."))
    _observer = ZizkaDBLiveKitObserver(
        db,
        agent=os.getenv("ZIZKADB_AGENT", "support-voice"),
        session_id=f"call_{ctx.room.name}",
    )
    await _observer.log_session_started(room=ctx.room.name)
    session = AgentSession(...)  # your STT / LLM / TTS
    _observer.attach(session, job_ctx=ctx)
    await session.start(agent=Agent(instructions="..."), room=ctx.room)

Self-host: set ZIZKADB_HOST=http://localhost:8000 instead of an API key. Full example: examples/livekit-agent.

Examples in the repo

Runnable trees under examples/ on GitHub: minimal-python, openai-agent, langchain-agent, crewai-agent, livekit-agent, mcp-cursor.