Documentation

Quickstart — Managed Service

Sign up at agentdb.zizka.ai, get your API key, and log your first event in 2 minutes.

pip install agentdb

from agentdb import AgentDB

db = AgentDB("agdb_live_xxxx")   # your API key

# Log an event
result = await db.log(
    agent="my-bot",
    event="tool_call",
    data={"tool": "search", "query": "competitor pricing"}
)
print(result.event_id)  # ✓ logged

Self-Host in 60 Seconds

Run the full AgentDB stack on your own infrastructure with one Docker command. No account, no API key, no credit card.

Requirements

• Docker Desktop (Mac/Windows) or Docker Engine (Linux)
• 4GB RAM minimum (Qdrant needs ~2GB)
• OpenAI API key (for auto-embeddings)

Option A — Single container (simplest)

docker run -p 8000:8000 \
  -e OPENAI_API_KEY=sk-... \
  agentdb/server

API available at http://localhost:8000

Option B — Docker Compose (recommended)

git clone https://github.com/Zizka-ai/agentdb
cd agentdb
cp .env.example .env
# Add OPENAI_API_KEY to .env
docker-compose -f infra/docker-compose.yml up

This starts Postgres, Qdrant, Redis, and the API together.

Connect your SDK to self-hosted

from agentdb import AgentDB

# Point to your local instance — no API key needed
db = AgentDB(host="http://localhost:8000")

await db.log(agent="my-bot", event="started", data={"v": "1.0"})

Python SDK

pip install agentdb

db.log() — Log an event

result = await db.log(
    agent="my-bot",          # agent identifier
    event="tool_call",       # event type (any string)
    data={"tool": "search"}, # any dict
    parent_id=prev_event_id, # optional — enables causal lineage
    session_id="sess_abc",   # optional — groups related events
)
# result.event_id, result.timestamp, result.checksum

db.why() — Causal chain

chain = await db.why(event_id, depth=10)
chain.print()
# user_message: "why is my bill high?"    [14:32:01]
#   └── tool_call: get_billing(456)        [14:32:02]
#       └── agent_response: "anomaly"      [14:32:03]

db.search() — Semantic search

results = await db.search(
    query="customer frustrated about billing",
    agent="support-bot",  # optional filter
    limit=10
)
for event in results:
    print(event.event, event.data, event.score)

db.at() — Time travel

from datetime import datetime

state = await db.at(
    agent="my-bot",
    timestamp=datetime(2026, 5, 1, 15, 0)
)
print(state.state)   # exact agent state at that moment

db.query() — Query events

events = await db.query(
    agent="my-bot",
    limit=50,
    event_type="tool_call",     # optional filter
    after=datetime(2026, 5, 1), # optional time filter
)

TypeScript SDK

npm install agentdb

import { AgentDB } from 'agentdb'

const db = new AgentDB({ apiKey: 'agdb_live_xxxx' })
// or self-hosted:
const db = new AgentDB({ host: 'http://localhost:8000' })

// Log
const result = await db.log({
  agent: 'my-bot',
  event: 'tool_call',
  data: { tool: 'search', query: '...' },
  parentId: prevEventId,
})

// Why
const chain = await db.why(result.eventId)
chain.print()

// Search
const results = await db.search({ query: 'billing issue', limit: 10 })

// Time travel
const state = await db.at({ agent: 'my-bot', timestamp: new Date('2026-05-01') })

API Reference

All endpoints are available at https://agentdb.zizka.ai (managed) or your self-hosted URL.

Authentication: pass your API key as Authorization: Bearer agdb_live_xxxx

POST /v1/events — Log event

curl https://agentdb.zizka.ai/v1/events \
  -H "Authorization: Bearer agdb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-bot",
    "event": "tool_call",
    "data": {"tool": "search"},
    "parent_id": "evt_abc123"
  }'

GET /v1/events/{id}/why — Causal chain

curl "https://agentdb.zizka.ai/v1/events/evt_abc123/why?depth=10" \
  -H "Authorization: Bearer agdb_live_xxxx"

POST /v1/search — Semantic search

curl https://agentdb.zizka.ai/v1/search \
  -H "Authorization: Bearer agdb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"query": "billing frustration", "limit": 10}'