Quickstart

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 as an environment variable:

export OPENAI_API_KEY=sk-...

That's it — kitaru.llm() will pick it up automatically.

kitaru secrets set openai-creds --OPENAI_API_KEY=sk-...
kitaru model register fast --model openai/gpt-4o-mini --secret openai-creds

Optional: start a local Kitaru server

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

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

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")

Then run it:

uv run agent.py

python agent.py

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 cost
4. .run() starts the execution and 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.

Deploy to a remote stack

Everything above runs locally. To run on remote infrastructure (Kubernetes, Vertex AI, etc.), 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": ["httpx", "pydantic-ai"],
        "apt_packages": ["git"],
    },
)
def research_agent(topic: str) -> str:
    ...

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: