Quickstart

Run your first durable agent flow with Kitaru

This guide walks you through setting up a model and running your first durable flow. If you haven't installed Kitaru yet, start with Installation.

Initialize your project

kitaru init

This creates a .kitaru/ directory that marks your project root.

Set up a model

kitaru.llm() needs to know which model to call and how to authenticate. Set your provider API key and a default model:

export OPENAI_API_KEY=sk-...
export KITARU_DEFAULT_MODEL=openai/gpt-5-nano

kitaru.llm() picks up both from the environment.

For production, register a model alias so you can swap models or credentials without changing code:

kitaru secrets set openai-creds --OPENAI_API_KEY=sk-...
kitaru model register fast --model openai/gpt-5-nano --secret openai-creds

See Secrets + Model Registration for the full setup.

Optional: start a local Kitaru server

Flows always run where you execute them — the server does not run your code. It stores execution metadata, secrets, model aliases, and serves the UI. If you already have a deployed server and want your executions tracked there, connect first and verify with kitaru status. If you are just trying Kitaru locally, skip this section.

uv project

uv run kitaru login https://my-server.example.com
uv run kitaru status

pip environment

Run your first flow

Create a file called agent.py:

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 this summary:\n\n{summary}"
    )

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

if __name__ == "__main__":
    research_agent.run(topic="durable execution for AI agents").wait()

Then run it:

uv (recommended)

uv run agent.py

pip environment

What happens here:

1. @flow marks the top-level execution boundary — everything inside is tracked

2. Each @checkpoint persists its return value automatically

3. kitaru.llm() picks up your API key from the environment, calls the model, and captures the prompt, response, token usage, and latency

4. .run() starts the execution and returns a FlowHandle; .wait() blocks until completion

Why checkpoints matter

Now imagine research succeeds but draft_report fails — maybe you hit a rate limit or the model returned an error. Without Kitaru you would re-run the entire script, paying for the research call again and losing progress. With Kitaru, you replay from the failure point:

kitaru executions list          # find the execution ID
kitaru executions replay <exec-id> --from draft_report

Replay creates a new execution that reuses the recorded output of research and only re-executes draft_report. The more checkpoints your flow has, the less work you repeat when something goes wrong.

This works the same whether you use kitaru.llm() or bring your own client.

That's the runtime layer running on your laptop. The same flow survives the move into production unchanged: the harness inside your checkpoints keeps owning how the agent thinks, Kitaru keeps owning the durable run, and your platform (auth, policy, UI) keeps sitting in front. When you're ready, my_agent.deploy(...) captures an immutable versioned snapshot that your platform invokes by flow name — no per-deployment tokens, no separate service per version.

Deploy to a remote stack

Everything above runs locally. To run on remote infrastructure (Kubernetes, Vertex AI, SageMaker, or AzureML), point your flow at a remote stack. When targeting a remote stack, Kitaru automatically builds a container image with your code and dependencies. You can control the base image, Python packages, system packages, and environment variables through the image parameter:

@flow(
    stack="prod-k8s",
    image={
        "base_image": "python:3.12-slim",
        "requirements": ["kitaru[pydantic-ai,openai]", "httpx"],
        "apt_packages": ["git"],
    },
)
def research_agent(topic: str) -> str:
    ...

This example includes kitaru[pydantic-ai,openai] explicitly because setting base_image means you control the image contents. Kitaru can auto-add plain kitaru when it builds the requirements list for you, but it does not guess optional extras such as the PydanticAI/OpenAI adapter dependencies.

See the Containerization guide for the full set of image options, custom Dockerfiles, and how Kitaru packages your source code.

What's Next

Now that Kitaru is installed and you've run a flow, follow the next path that fits what you want to learn:

Agent Harness Platform

The recommended end-to-end tour: build a durable agent harness platform stage by stage on Kitaru + PydanticAI

Core Concepts

Understand flows, checkpoints, and the execution model

Execution Management

Inspect runs, fetch logs, replay, retry, and resume

Configuration

Configure runtime defaults and precedence

Examples

Browse runnable Kitaru workflows grouped by goal

Containerization

Control base images, dependencies, and Dockerfiles for remote execution

Wait, Input, and Resume

Pause flows for external input and continue later

Tracked LLM Calls

Use kitaru.llm() with captured prompt/response artifacts

Secrets + Model Setup

Store provider credentials, register an alias, and use kitaru.llm()

MCP Server

Query and manage executions through assistant tool calls