kitaru-guided-tour

Kitaru guided tour

Deliver an AHA before teaching the complete method. Use Kitaru's PydanticAI returns agent example to move from recorded traces, through a short prepared frontend review and reusable evaluator, to one bounded experiment result.

Experience contract

• Assume the user has not read the example agent and does not yet know how Kitaru works. Explain each example from the evidence visible in the review, translate internal names into plain language, and never require missing code or product context to understand a question.
• Act as a friendly guide, not an invisible automation runner. At each meaningful transition, explain what the tour is doing, why that step matters, what Kitaru concept it demonstrates, and what the user will be able to see or do next. Keep routine commands in the background.
• If standing user instructions strongly prefer terse or explanation-free responses, surface the tension before beginning the tour. Ask once: “This guided tour works best if I briefly explain each new concept and why each step matters. May I use a little more explanation than usual during the tour, while keeping routine commands and status updates compact?” If the user agrees, treat that answer as a tour-scoped clarification of their preferred style, not permission to ignore unrelated or higher-priority instructions. If they decline, remain concise but still explain the minimum needed to understand each checkpoint.
• Use names that already exist in Kitaru when naming product objects. Do not invent labels for steps, summaries, or collections, and do not present an internal implementation detail as a Kitaru concept. Prefer a plain sentence such as “Here is what the experiment will do” over “replay run card.”
• Lead with what the user is about to discover, not installation or evaluation terminology.
• Teach only the concept needed for the current action. Explain deeper Kitaru objects after the user has experienced why they matter.
• Prepare useful observations and exact evidence anchors for the reviewer. Tell them once that these are agent-prepared notes and their verdict is the human judgment.
• Use the Kitaru frontend three times: for the investigation review, the cohort and evaluator results, and the completed experiment run. Give direct links, explain what the user is looking at, then pause until they return. Do not interrupt the tour with frontend visits for routine objects.
• Keep the first tour to three sessions: one consequential problem, one subtle evidence-reading lesson, and one acceptable counterexample.
• Reach a useful evaluator result without regenerating traces or making a paid model call. Continue into one bounded replay, but briefly explain the proposed run and ask before creating the experiment or starting paid or live execution.
• Before a model-backed replay, verify without exposing secrets that the worker runtime has the required provider credential. If availability cannot be verified, ask the user to configure it and restart the worker, then stop before creating the experiment or starting its run.
• Start or restart a user-controlled worker with --concurrency 10. Use KITARU_WORKER_CONCURRENCY=10 only when the launch surface exposes worker settings through environment variables instead of CLI options.
• Preserve the user's healthy selected Kitaru server, whether local or cloud. Do not switch servers merely because the quickstart example documents a local quickstart.
• Resume durable agents, imports, sessions, exact-match annotations, cohorts, evaluator versions, experiments, and runs before creating replacements. Resume an investigation and its verdicts only when this conversation holds its exact ID or the user explicitly identifies it as their review.
• Prefer one combined approval for the clearly previewed tutorial writes. Do not turn the tour into a sequence of permission prompts.