Examples

The Kitaru repo includes a set of runnable examples grouped by purpose:

• Agent Harness Platform — a stage-by-stage tour through building a durable agent harness platform on Kitaru + PydanticAI. Read this first if you're new.
• Other end-to-end examples — production-shaped, self-contained scenarios that exercise multiple primitives at once. No required reading order.
• Feature-focused examples — small examples that demo one Kitaru primitive in isolation.

Every example is a standalone project — clone the repo, cd into the example you want, and run it directly.

Clone the repo, install dependencies with uv, initialize the project once, and then run the example you want.

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

Most examples can be run from the repository root with uv run python path/to/script.py. Some end-to-end examples (including the Agent Harness Platform tour) tell you to cd into their directory first because they read a local .env file or have a multi-step README.

Connection context

Examples use whatever Kitaru connection context is already active.

• If you are just trying Kitaru locally, run uv run kitaru login and use 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.

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

Start here — Agent Harness Platform

A platform engineer's starter kit for building their org's internal agent harness platform on top of Kitaru + PydanticAI. Bring Docker and one model-provider API key; then bash setup.sh && uv run python stage_N_*.py. Stages build progressively from a 30-line durable agent to a sandboxed, credential-isolated agent with HITL — each stage adds exactly one tool or one architectural primitive, the library grows monotonically, and the per-stage Profile gates which capabilities each agent actually exercises.

Use it as the first thing you read end-to-end, and as the thing you fork for your team.

→ Agent Harness Platform tour — read the stage-by-stage docs, then grab the code on GitHub.

git clone https://github.com/zenml-io/kitaru.git
cd kitaru/examples/end_to_end/agent_harness_platform
uv sync
uv run kitaru init
export OPENAI_API_KEY=sk-...
uv run python stage_1_basic_agent.py

Other end-to-end examples

Production-shaped examples that exercise multiple primitives in one runnable scenario. Each is self-contained and focused on one harness or scenario — no progressive tour, no required reading order. Pick the one closest to your domain.

Feature-focused examples

Small examples that demo one primitive in isolation. Pick by the thing you want to see.

Core workflow basics

Execution lifecycle and recovery

LLMs and agent integrations

| end_to_end/coding_agent/agent.py | A tool-using coding agent whose LLM calls and tool decisions are visible as durable execution state | Tracked LLM Calls | | end_to_end/news_scout/scout.py | PydanticAI news monitor with per-model/per-tool checkpoints, explicit run inputs, and remote-secret image config | Examples index | | end_to_end/openai_research_bot/research_bot.py | Multi-agent OpenAI research bot with planner/writer runner checkpoints, submitted search fan-out, and published report artifacts | Research bot section | | end_to_end/compliance_review/README.md | Four-stage Claude Agent SDK audit: checkpointed turns, partial replay, and durable wait/resume conversation | Replay and Overrides | | features/mcp/mcp_query_tools.py | Query executions and data through the Kitaru MCP server | MCP Server |

If you'd rather build up primitive-by-primitive first

Agent Harness Platform is the recommended starting point for most readers — it's structured as a tour and each stage's commit message points at the docs page that explains the primitive being introduced. If you'd rather see each primitive in isolation before reading them woven together, follow this path:

1. Quickstart — @flow + @checkpoint in 6 lines.
2. features/basic_flow/first_working_flow.py — the same idea as a runnable file.
3. features/basic_flow/flow_with_logging.py — Logging.
4. features/checkpoint_streaming/checkpoint_streaming.py — Checkpoint Live Events.
5. features/basic_flow/flow_with_artifacts.py — Artifacts.
6. features/execution_management/wait_and_resume.py — Wait, Input, and Resume.
7. features/replay/replay_with_overrides.py — Replay and Overrides.
8. features/llm/flow_with_llm.py — Tracked LLM Calls.
9. integrations/pydantic_ai_agent/pydantic_ai_adapter.py — PydanticAI Adapter.
10. integrations/pydantic_ai_agent/pydantic_ai_streaming.py — PydanticAI streaming.
11. integrations/openai_agents_agent/openai_agents_adapter.py — OpenAI Agents Adapter.
12. integrations/openai_agents_agent/openai_agents_streaming.py — OpenAI Agents streaming.
13. integrations/claude_agent_sdk_agent/claude_agent_sdk_adapter.py — Claude Agent SDK Adapter.
14. integrations/claude_agent_sdk_agent/claude_agent_sdk_streaming.py — Claude Agent SDK streaming.
15. integrations/gemini_interactions_agent/gemini_interactions_adapter.py — Gemini Interactions Adapter.
16. integrations/langgraph_agent/langgraph_adapter.py — LangGraph Adapter.
17. integrations/langgraph_agent/langgraph_streaming.py — LangGraph streaming.
18. end_to_end/openai_research_bot/research_bot.py — Research bot.
19. features/mcp/mcp_query_tools.py — MCP Server.
20. Agent Harness Platform — the same primitives, woven into one runnable agent harness platform.