> 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/getting-started/readme.md).

# Welcome to Kitaru

Kitaru is the runtime for production AI agents: **run, replay, improve**. It records every model call and tool call as a durable checkpoint, then lets you re-execute a real run faithfully with one thing changed — a different model, a different prompt — and diff the result against the original. Because the baseline reproduces, the difference you see is your change, not replay noise.

The harness you already picked (PydanticAI, OpenAI Agents SDK, LangGraph, Claude Agent SDK, raw Python) keeps owning how the agent thinks. Kitaru owns the run record and the replay loop. A Kitaru flow is a dynamic ZenML pipeline, so agents run on the same [stacks](/kitaru/agent-runtime-stacks/stacks.md), server, and dashboard as your ZenML pipelines.

## Run, replay, improve

* **Run (durable).** Every `@checkpoint` is a durable unit of work; its output is persisted automatically, and every model and tool call is recorded. If a flow fails partway, replaying it reuses recorded results instead of re-running expensive work.
* **Replay (the differentiator).** Re-execute a recorded run from any checkpoint. A plain rerun with no change reproduces the original — that is your baseline. Replay again with one input overridden and diff the two. This re-executes the real run from a checkpoint; it is not re-scoring saved outputs like an eval.
* **Improve.** Apply the same change across a cohort of recent runs, measure cost, latency, and quality, and keep the winner.

Kitaru is self-host-first: a single-service server on your own Kubernetes, artifacts in your own S3/GCS/Azure Blob. No mandatory SaaS control plane in the path of your agent's data. See [Harness, Runtime, Platform](/kitaru/core-concepts/harness-runtime-platform.md) for where Kitaru fits.

## The replay loop

```python
import kitaru
from kitaru import checkpoint, flow

@checkpoint
def research(topic: str) -> str:
    return kitaru.llm(f"Summarize {topic} in two sentences.")

@checkpoint
def draft_report(summary: str) -> str:
    return kitaru.llm(f"Write a short report based on: {summary}")

@flow
def research_agent(topic: str) -> str:
    summary = research(topic)
    return draft_report(summary)

if __name__ == "__main__":
    # Run, then replay from a checkpoint with one input changed.
    run = research_agent.run(topic="Why do agents need durable execution?").wait()

    baseline = research_agent.replay(run.exec_id, at="draft_report")
    variant = research_agent.replay(
        run.exec_id,
        at="draft_report",
        flow_overrides={"model": "anthropic/claude-opus-4"},
    )
    # baseline reproduces the original; diff variant against it to isolate your change.
```

`run(...)` returns a handle; `.wait()` blocks for the result and exposes `.exec_id`. `replay(exec_id, at="<checkpoint>", flow_overrides={...})` re-executes from that checkpoint, overriding flow inputs such as the model or prompt profile. The same loop is available over the [CLI](https://sdkdocs.kitaru.ai) and the [MCP server](/kitaru/agent-native/mcp-server.md) so a coding agent can drive it.

See the [Quickstart](/kitaru/getting-started/quickstart.md) to install and run this yourself.

## Where ZenML fits

Kitaru is built by the team behind [ZenML](https://docs.zenml.io), the open-source framework for production ML and LLM pipelines, and runs on the same foundations. Each project works on its own — you can use Kitaru without ever touching ZenML. If you use both, they compose rather than coexist: a Kitaru flow is a dynamic ZenML pipeline under the hood, so your agents and pipelines run on the same [stacks](/kitaru/agent-runtime-stacks/stacks.md), persist artifacts to the same stores, and show up in the same server and dashboard. If your work is ML pipelines rather than agents, start with the [ZenML docs](https://docs.zenml.io) — and if you want the narrative tutorial for agents, the [Agents guide](https://docs.zenml.io/user-guides/agents-guide) sits alongside ZenML's Starter, Production, and LLMOps guides in the shared [Learn](https://docs.zenml.io/user-guides) section.

## Runtime primitives

These are the primitives Kitaru adds on top of your existing Python agent code. You keep your harness and your control flow; Kitaru records the run and makes it replayable.

* **Replay and override:** Re-execute any run from any checkpoint — to recover from a failure, or with [overrides](/kitaru/guides/replay-and-overrides.md) (a different model or parameter) to isolate the effect of a change before you ship it. Use invocation overrides when you need to change one recorded checkpoint, tool, or model call instead of every call with the same checkpoint name.
* **Durable execution:** Wrap steps in [`@checkpoint`](/kitaru/core-concepts/checkpoints.md) and your agent picks up where it left off without re-running expensive work
* **Wait and resume:** Add [`kitaru.wait()`](/kitaru/guides/wait-and-resume.md) and let agents pause for a human, another system, or later input; after the polling timeout, compute is released and the run resumes when input lands
* **Artifact lineage:** Every checkpoint output is written to your object store as a typed, versioned artifact — step through runs, diff outputs across runs, and trace a bad final output back to the exact step that produced it
* **Execution management:** [`KitaruClient`](/kitaru/guides/execution-management.md) lets you inspect, replay, retry, resume, and cancel executions from code or CLI
* **Tracked LLM calls:** Use [`kitaru.llm()`](/kitaru/guides/llm-calls.md) and every call gets automatic secret resolution, prompt/response capture, and token/latency logging
* **Persistent data:** [`kitaru.save()` / `kitaru.load()`](/kitaru/guides/artifacts.md) let agents store and retrieve files, objects, and results across executions
* **Structured observability:** [`kitaru.log()`](/kitaru/core-concepts/logging.md) attaches key-value metadata to any checkpoint or flow for debugging and the UI
* **Runtime configuration:** [`kitaru.configure()`](/kitaru/guides/configuration.md) sets your model, log store, and stack defaults in one call
* **Framework and infrastructure portability:** Keep your Python control flow, use your preferred framework, and run locally or on remote stacks — Kubernetes, Vertex AI, SageMaker, AzureML

## Next steps

<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>Installation</strong></td><td>Install Kitaru with uv or pip.</td><td><a href="/pages/cDb4N92M787W6Uf33vjO">/pages/cDb4N92M787W6Uf33vjO</a></td></tr><tr><td><strong>Quickstart</strong></td><td>Run a tiny flow end to end.</td><td><a href="/pages/knQ03wCkSkWfSSXcMRor">/pages/knQ03wCkSkWfSSXcMRor</a></td></tr><tr><td><strong>Examples</strong></td><td>Browse runnable workflows grouped by goal.</td><td><a href="/pages/avGnXrIi7fgY7KLr0o2L">/pages/avGnXrIi7fgY7KLr0o2L</a></td></tr><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, and what lives where in local dev vs production.</td><td><a href="/pages/fpgU4WBhT9hosGDLfA42">/pages/fpgU4WBhT9hosGDLfA42</a></td></tr><tr><td><strong>Core Concepts</strong></td><td>Flows, checkpoints, and the execution model.</td><td><a href="/pages/qw8hIFEbl4taSEvy4SNP">/pages/qw8hIFEbl4taSEvy4SNP</a></td></tr><tr><td><strong>Execution Management</strong></td><td>Inspect runs, replay, retry, resume, and fetch logs.</td><td><a href="/pages/m1ms9iW3v3U2tkSxyRWm">/pages/m1ms9iW3v3U2tkSxyRWm</a></td></tr><tr><td><strong>Wait, Input, and Resume</strong></td><td>Pause flows for external input and continue the same execution.</td><td><a href="/pages/BUp6cWRuU8VUfknQKRto">/pages/BUp6cWRuU8VUfknQKRto</a></td></tr><tr><td><strong>Tracked LLM Calls</strong></td><td>Use kitaru.llm() with aliases, secrets, and captured artifacts.</td><td><a href="/pages/wljT8fZIU4BA8fs9S8aB">/pages/wljT8fZIU4BA8fs9S8aB</a></td></tr><tr><td><strong>Secrets + Model Registration</strong></td><td>Store provider credentials, register a model alias, and use kitaru.llm().</td><td><a href="/pages/DJsLPOTXT5IAsfz7v4WZ">/pages/DJsLPOTXT5IAsfz7v4WZ</a></td></tr><tr><td><strong>Configuration</strong></td><td>Set runtime defaults and understand override precedence.</td><td><a href="/pages/jfZrP31z5ehu33Ct8Ljy">/pages/jfZrP31z5ehu33Ct8Ljy</a></td></tr><tr><td><strong>Stacks</strong></td><td>Create, inspect, switch, and clean up local and remote stacks across Kubernetes, AWS, GCP, and Azure.</td><td><a href="/pages/Md0YgNiF5z5NwLEvQ5aR">/pages/Md0YgNiF5z5NwLEvQ5aR</a></td></tr><tr><td><strong>MCP Server</strong></td><td>Query and manage executions via MCP tools.</td><td><a href="/pages/bKWyQ7nmVr76lemvYneQ">/pages/bKWyQ7nmVr76lemvYneQ</a></td></tr><tr><td><strong>Agent Skills</strong></td><td>Install quickstart, scoping, authoring, and adapter migration skills.</td><td><a href="/pages/dxfY4zN6l6d8rDPipYj2">/pages/dxfY4zN6l6d8rDPipYj2</a></td></tr><tr><td><strong>CLI Reference</strong></td><td>Browse the generated command reference.</td><td><a href="https://sdkdocs.kitaru.ai">https://sdkdocs.kitaru.ai</a></td></tr><tr><td><strong>Blog</strong></td><td>Read essays on durable execution, long-running agents, and Kitaru's design.</td><td><a href="https://kitaru.ai/blog/">https://kitaru.ai/blog/</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/getting-started/readme.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.