Core Concepts
The mental model behind Kitaru's durable execution primitives
Kitaru sits in the runtime layer of your agent stack. Underneath it are the harness your team picked (Pydantic AI / Pydantic AI Harness, LangGraph, Claude Agent SDK, raw Python) and the model(s) that harness drives. On top sits the platform your org already runs (auth, observability, policy, UI). Kitaru's job is to make the run durable — checkpoints, replay, resume, wait states, versioned deployments — without forcing a graph DSL or a rewrite of your control flow.
Start with Harness, Runtime, Platform if you want the big-picture split, or How It Works for the three-planes model (control / orchestration / execution) and what-runs-where in local dev vs production.
Core ideas
| Concept | What it is |
|---|---|
| Flow | The outer durable boundary around your workflow |
| Checkpoint | A unit of work inside a flow whose output is persisted |
| Execution | A single run of a flow, identified by a unique ID |
| Structured metadata | Key-value data you attach to executions and checkpoints with kitaru.log() |
| Runtime log storage | Where runtime logs are sent (configured separately from structured metadata) |
| Active stack | The default execution target used when no per-run stack=... override is passed |
What you can use today
Kitaru's current release includes:
@flow— mark a function as a durable workflow@checkpoint— mark a function as a persisted work unitkitaru.memory— keep durable versioned key-value state by scopekitaru.log()— attach structured metadata to the current scopekitaru.wait()— pause a flow until external input is suppliedkitaru.llm()— make tracked model calls with prompt/response capturekitaru.connect()— connect to a Kitaru serverkitaru.configure()— set process-local runtime defaultskitaru.save()/kitaru.load()— persist and load named artifacts in checkpointskitaru.list_stacks()/kitaru.current_stack()/kitaru.use_stack()— manage the default stackKitaruClient— inspect executions, fetch logs, resolve waits, retry, replay, and browse artifactsFlowHandle— interact with a running or finished execution
All of the primitives listed here ship today. Some capabilities are backend-dependent — for example, runtime log retrieval requires a server-backed connection — but they are part of the supported Kitaru surface.
Explore the concepts
Harness, Runtime, Platform
Where Kitaru fits in an agent stack, and where it doesn't
How It Works
Server, runner, execution targets; three planes; local dev vs production
Flows
Define durable execution boundaries and control how workflows run
Checkpoints
Break work into persisted units with concurrency support
Memory
Store versioned durable key-value state across executions
Logging and Metadata
Attach structured data to executions and checkpoints