> For the complete documentation index, see [llms.txt](https://docs.zenml.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zenml.io/kitaru/core-concepts/concepts.md).

# Overview

Kitaru is the runtime for production AI agents. It records every run as durable checkpoints, lets you replay a real run with one thing changed, and helps you roll the winning change across recent runs. The loop is **run → replay → improve**.

A Kitaru flow is a dynamic ZenML pipeline and a checkpoint is like a step, so agents run on the same stacks, server, and dashboard as your ZenML pipelines.

1. **Run (durable).** Every model call and tool call is recorded as a checkpoint. This is the enabler for everything below, not the headline.
2. **Replay (the differentiator).** Re-execute a real run from a checkpoint. A rerun with no change reproduces the original — that faithful baseline is your control. Replay again with one input changed (a different model, a different prompt) and diff the two. Because the baseline reproduced, the difference is your change, not replay noise. This re-executes the real run; it is not re-scoring outputs like an eval.
3. **Improve.** Apply the same change across a cohort of recent runs, measure cost, latency, and quality, and keep the winner.

Durable execution is the mechanism that makes replay faithful. Start with [Harness, Runtime, Platform](/kitaru/core-concepts/harness-runtime-platform.md) for where Kitaru fits in an agent stack, or [How It Works](/kitaru/core-concepts/how-it-works.md) 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 unit
* `flow.run(...).wait()` — run a flow to completion; the handle carries `.exec_id`
* `flow.replay(exec_id, at="<checkpoint>", flow_overrides={...})` — re-execute a recorded run from a checkpoint, optionally overriding flow inputs such as `model` or `prompt_profile`
* `kitaru.log()` — attach structured metadata to the current scope
* `kitaru.wait()` — pause a flow until external input is supplied
* `kitaru.llm()` — make tracked model calls with prompt/response capture
* `kitaru.connect()` — connect to a Kitaru server
* `kitaru.configure()` — set process-local runtime defaults
* `kitaru.save()` / `kitaru.load()` — persist and load named artifacts in checkpoints
* `kitaru.list_stacks()` / `kitaru.current_stack()` / `kitaru.use_stack()` — manage the default stack
* `KitaruClient` — inspect executions, fetch logs, resolve waits, retry, replay, and browse artifacts
* `FlowHandle` — interact with a running or finished execution

Replay and diff are also exposed over an MCP server and the `kitaru` CLI (`kitaru executions replay <id> --at <checkpoint> --flow-overrides <json>`), so a coding agent can drive the run → replay → improve loop directly.

{% hint style="info" %}
All of the primitives listed here ship today. Some capabilities are backend-dependent — runtime log retrieval, for example, requires a server-backed connection — but they are part of the supported Kitaru surface.
{% endhint %}

## Explore the concepts

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Harness, Runtime, Platform</strong></td><td>Where Kitaru fits in an agent stack, and where it doesn't.</td><td><a href="/pages/jFEpVFR4YYhJvoEp1r9K">/pages/jFEpVFR4YYhJvoEp1r9K</a></td></tr><tr><td><strong>How It Works</strong></td><td>Server, runner, execution targets; three planes; local dev vs production.</td><td><a href="/pages/fpgU4WBhT9hosGDLfA42">/pages/fpgU4WBhT9hosGDLfA42</a></td></tr><tr><td><strong>Flows</strong></td><td>Define durable execution boundaries and control how workflows run.</td><td><a href="/pages/fRZF8ymHawJ9ME3mH2F1">/pages/fRZF8ymHawJ9ME3mH2F1</a></td></tr><tr><td><strong>Checkpoints</strong></td><td>Break work into persisted units with concurrency support.</td><td><a href="/pages/Zt6utJ6bxTsCzHn1d3At">/pages/Zt6utJ6bxTsCzHn1d3At</a></td></tr><tr><td><strong>Logging and Metadata</strong></td><td>Attach structured data to executions and checkpoints.</td><td><a href="/pages/ibSSC0mR9ajxhHhbbv29">/pages/ibSSC0mR9ajxhHhbbv29</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.zenml.io/kitaru/core-concepts/concepts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.