> 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 Your agent has already been tested thousands of times in production. Most of that evidence is sitting in a trace store as something you can read but not run. Kitaru makes it runnable: it records or imports each run as a **session**, then **replays** it against your real code, with the recording answering for the world the original run saw. Change the prompt, swap the model, or point replay at the fix in your working tree, and see what improved and what broke before it ships. {% hint style="success" %} **Who it's for:** Teams with an agent in front of real users, where regression testing today means re-running a few samples and eyeballing the output. Kitaru replaces that with [evaluators](/kitaru/core-concepts/evaluators.md), [cohorts](/kitaru/core-concepts/cohorts.md), and [experiments](/kitaru/core-concepts/experiments.md) over your actual traffic. If you're prototyping and haven't shipped, it will feel like more machinery than you need. {% endhint %} **Frameworks:** adapters ship for [PydanticAI](/kitaru/adapters/pydantic-ai.md), [LangGraph](/kitaru/adapters/langgraph.md), and the [OpenAI Agents SDK](/kitaru/adapters/openai-agents.md) in Python, and for [Mastra](/kitaru/adapters/mastra.md) and the [Vercel AI SDK](/kitaru/adapters/vercel-ai.md) in TypeScript. Other frameworks still work: [import your traces](/kitaru/import-your-traces/import-your-traces.md) with the built-in Langfuse, LangSmith, Braintrust, Logfire, Arize Phoenix, or JSONL importers; [write a custom importer](/kitaru/import-your-traces/custom-importer.md), usually about a page of Python; or [build a small adapter](/kitaru/adapters/custom.md), where the recording API is two client calls. {% hint style="info" %} Kitaru has both a Python and a TypeScript SDK, and both talk to the same server. The CLI ships with the Python package. {% endhint %} **Kitaru is built to be driven by agents.** The MCP server gives Claude Code, Codex, Cursor, and other coding assistants bounded Kitaru operations. The agent skills teach the procedures, and the CLI speaks JSON when a shell command is the right tool. You bring the judgment; your assistant handles the investigation work. [Set up your coding agent](/kitaru/getting-started/setup.md) takes a few minutes. Kitaru is open source (Apache 2.0) and self-hosted, from the team behind [ZenML](https://zenml.io): ZenML is for ML pipelines, Kitaru is for agents. ## The loop * **Record.** Wrap your agent or import your traces (both shown below). Either way, runs land as [sessions](/kitaru/core-concepts/agents-and-sessions.md). * **Replay.** [Re-execute a session](/kitaru/core-concepts/replay.md) against your real code. Tool calls are answered from the recording, so nothing touches real systems. An unchanged replay gives you the faithful baseline. Then fork it with a different model, a new prompt, or your working tree's code. * **Improve.** This is where your judgment enters. In an [investigation](/kitaru/core-concepts/investigations.md), your coding assistant authors the review, walks you through the evidence, asks the questions Kitaru needs answered, and pins your answers to the exact trace as annotations. Those judgments calibrate the [evaluators](/kitaru/core-concepts/evaluators.md) that evaluate both sides; [cohorts](/kitaru/core-concepts/cohorts.md) freeze the population; [experiments](/kitaru/core-concepts/experiments.md) replay a cohort against a change and show what improved and what regressed. The cohort that caught a failure becomes the regression gate that keeps it caught. In daily work, that loop becomes five steps: **observe** a recorded behavior, **judge** what should have happened, **define** the behavior to test, **replay** the changed agent, and **compare** the evidence. Recording gives you the raw material; observe, judge, and define turn human judgment into durable criteria; replay and compare close the loop. The [Quickstart](/kitaru/getting-started/quickstart.md) walks all five. To try it in a controlled environment, ask your assistant for the `kitaru-guided-tour` skill, which runs the loop on the public [`kitaru-template`](https://github.com/zenml-io/kitaru-template), or follow the [complete returns-agent tutorial](/kitaru/guides/returns-agent.md) manually. ## Do I have to run it in production? No. There are two ways to get sessions, and they end in the same place: * **Import the history you already have.** If your agent logs to Langfuse or anything else you can export from, import it. Nothing in your production path changes: your trace store stays your system of record, and Kitaru gets a runnable copy. * **Record with an adapter.** Wrap the agent once, no rewrite, and every run becomes a session wherever the agent runs: production, staging, or your laptop. {% tabs %} {% tab title="Import traces" %} ```bash kitaru session import langfuse-export.jsonl \ --importer kitaru/langfuse@latest \ --agent support-agent@latest --wait ``` {% endtab %} {% tab title="Record with an adapter" %} ```python from pydantic_ai import Agent from kitaru_pydantic_ai import KitaruAgent agent = Agent( "openai:gpt-5.4", name="support-agent", system_prompt="You resolve support tickets." ) @agent.tool_plain def refund_payment(order_id: str) -> str: return payments.refund(order_id) # your real API support = KitaruAgent(agent, agent_id=AGENT_ID) support.run_sync("Refund order #4821, the card reader double-charged me.") ``` {% endtab %} {% endtabs %} Replays, imports, and evaluations run offline on [workers](/kitaru/core-concepts/workers.md) in your environment. None of that touches your production traffic. An adapter does run inside your agent's process to record; if you do not want Kitaru near production, the import path never gets close to it. ## Built to sit in your stack * **Self-hosted.** One FastAPI + Postgres server on your infrastructure. Your traces and credentials don't leave your systems. * **Beside your observability, not instead of it.** Langfuse, LangSmith, Braintrust, Logfire, and Arize Phoenix remain where you watch production. Kitaru is where you re-run it. * **Choose how you drive it:** the `kitaru` CLI, Python SDK, TypeScript SDK, and your [coding agent](/kitaru/getting-started/setup.md). Kitaru observes your production agents; your coding assistant is how you talk to Kitaru. **Questions, bugs, feedback?** Join the [Slack community](https://kitaru.ai/slack), report bugs at [kitaru.ai/help](https://kitaru.ai/help) (it goes straight to GitHub issues), or email . All three reach a human. ## Next steps
InstallationSDK, CLI, a local server, and a login./pages/cDb4N92M787W6Uf33vjO
QuickstartUnderstand the five-step method before running commands./pages/knQ03wCkSkWfSSXcMRor
Kitaru templatePrepare a ready PydanticAI agent and checked-in Langfuse traces.https://github.com/zenml-io/kitaru-template
Complete tutorialInvestigate and replay the template's synthetic returns agent./pages/R1lYNNZKYCdTyMZbtsck
Import your tracesStart from the history you already have./pages/o74tFfkKFSg3Ubasut52
Core ConceptsSessions, replay, evaluators, cohorts, experiments./pages/qw8hIFEbl4taSEvy4SNP
Build a regression suiteProduction traffic as your test suite./pages/ktnQrV1qibhxXwZEZKDn
Deploy KitaruSelf-host for your team./pages/RQBXLDtvODELNqqDX86n
--- # 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=&goal= ``` `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.