Examples

The Kitaru repo includes runnable examples that demonstrate each primitive. Each example is a standalone project — clone the repo, cd into the example you want, and run it directly.

Get the examples

git clone https://github.com/zenml-io/kitaru.git
cd kitaru/examples/features/basic_flow
kitaru init
python first_working_flow.py

Run kitaru init once before your first example to set up the local execution environment.

Every example uses imports relative to its own directory, so always cd into the example folder before running.

Connection context

Examples use whatever Kitaru connection context is already active.

If you are just trying Kitaru locally, run them as-is.
If you already have a deployed Kitaru server and want the examples to use it, connect first and verify the active context before running the example.

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

Browse by goal

I want to...	Example	Run
Start with the smallest runnable flow	`features/basic_flow/`	`python first_working_flow.py`
See structured metadata logging	`features/basic_flow/`	`python flow_with_logging.py`
Persist and reload data across executions	`features/basic_flow/`	`python flow_with_artifacts.py`
Seed, inspect, compact, and purge durable memory	`features/memory/`	`python flow_with_memory.py`
Set runtime configuration defaults	`features/basic_flow/`	`python flow_with_configuration.py`
Inspect and manage past executions	`features/execution_management/`	`python client_execution_management.py`
Pause for human input and resume later	`features/execution_management/`	`python wait_and_resume.py`
Replay from a checkpoint with overrides	`features/replay/`	`python replay_with_overrides.py`
Track a model call inside a flow	`features/llm/`	`python flow_with_llm.py`
Wrap a PydanticAI agent	`integrations/pydantic_ai_agent/`	`python pydantic_ai_adapter.py`
Wrap an OpenAI Agents SDK agent	`integrations/openai_agents_agent/`	`python openai_agents_adapter.py`
Run a multi-agent OpenAI research bot	`end_to_end/openai_research_bot/`	`python research_bot.py "Your query" --max-searches 2`
Query executions from an MCP client	`features/mcp/`	`python mcp_query_tools.py`

For example:

cd examples/features/basic_flow
python first_working_flow.py

Core workflow basics

Example	Demonstrates	Related docs
`features/basic_flow/first_working_flow.py`	Smallest `@flow` + `@checkpoint` example	Quickstart
`features/basic_flow/flow_with_logging.py`	`kitaru.log()` metadata at flow and checkpoint scope	Logging
`features/basic_flow/flow_with_artifacts.py`	`kitaru.save()` and `kitaru.load()` across executions	Artifacts
`features/basic_flow/flow_with_configuration.py`	`kitaru.configure()` defaults, overrides, and frozen specs	Configuration

Durable shared state

Example	Demonstrates	Related docs
`features/memory/flow_with_memory.py`	Outside-flow seeding, in-flow `kitaru.memory`, detached post-run execution-scope writes, explicit-scope inspection, and post-run maintenance (compact, purge, audit log) via `KitaruClient.memories`	Use Memory

Execution lifecycle and recovery

Example	Demonstrates	Related docs
`features/execution_management/client_execution_management.py`	`KitaruClient` for listing runs, reading details, and loading data	Execution Management
`features/execution_management/wait_and_resume.py`	`kitaru.wait()` with inline prompt or CLI input/resume	Wait, Input, and Resume
`features/replay/replay_with_overrides.py`	Replay from a checkpoint with overridden inputs	Replay and Overrides

LLMs and agent integrations

Example	Demonstrates	Related docs
`features/llm/flow_with_llm.py`	`kitaru.llm()` prompt-response tracking with usage metadata	Tracked LLM Calls
`integrations/pydantic_ai_agent/pydantic_ai_adapter.py`	Wrap a PydanticAI agent with Kitaru replay boundaries	PydanticAI Adapter
`integrations/openai_agents_agent/openai_agents_adapter.py`	Wrap an OpenAI Agents SDK agent with Kitaru call-level or runner-call durability in a real API-backed support flow (`OPENAI_API_KEY` required, default model `gpt-5-nano`)	OpenAI Agents Adapter
`end_to_end/openai_research_bot/research_bot.py`	Run a multi-agent OpenAI research bot with planner/writer runner checkpoints, submitted search fan-out, and a published report (`OPENAI_API_KEY` required, default model `gpt-5-nano`)	Research bot section
`features/mcp/mcp_query_tools.py`	Query executions and data through the Kitaru MCP server	MCP Server

The LLM and adapter examples require additional dependencies — check each example's README for setup instructions.

Recommended path

If you are learning Kitaru from scratch:

features/basic_flow/first_working_flow.py — Quickstart
features/basic_flow/flow_with_logging.py — Logging
features/basic_flow/flow_with_artifacts.py — Artifacts
features/memory/flow_with_memory.py — Use Memory
features/execution_management/client_execution_management.py — Execution Management
features/execution_management/wait_and_resume.py — Wait, Input, and Resume
features/replay/replay_with_overrides.py — Replay and Overrides
features/llm/flow_with_llm.py — Tracked LLM Calls
integrations/pydantic_ai_agent/pydantic_ai_adapter.py — PydanticAI Adapter
integrations/openai_agents_agent/openai_agents_adapter.py — OpenAI Agents Adapter
end_to_end/openai_research_bot/research_bot.py — Research bot section
features/mcp/mcp_query_tools.py — MCP Server

On this page