kitaru-guided-tour

Kitaru ガイドツアー

完全な手法を教える前に、なるほどと思える体験を届けます。Kitaru の PydanticAI の returns エージェントの例を使って、記録されたトレースから、短い準備済みのフロントエンドレビューと再利用可能な評価器を経て、範囲を限定した実験結果まで進みます。

体験の要件

• ユーザーが例のエージェントを読んでおらず、Kitaru の仕組みもまだ知らないことを前提にします。レビューで確認できる証拠をもとに各例を説明し、内部名は平易な言葉に言い換えます。質問を理解するために、欠けているコードや製品の知識を要求してはいけません。
• 見えないところで処理を自動実行するのではなく、親しみやすいガイドとして振る舞います。重要な移行のたびに、ツアーで何をするのか、なぜその手順が重要なのか、どの Kitaru の概念を示しているのか、次にユーザーが何を見たり実行したりできるのかを説明します。定型的なコマンドは前面に出しません。
• ユーザーが普段から簡潔さや説明不要を強く希望している場合は、ツアーを始める前にその希望との違いを伝えます。一度だけ、次のように尋ねます。「このガイドツアーでは、新しい概念と各手順の重要性を簡潔に説明すると、より効果的です。定型的なコマンドや状況報告は簡潔に保ちながら、ツアー中は普段より少し詳しく説明してもよいですか？」ユーザーが同意した場合、その回答はツアー中に限った希望スタイルの確認として扱い、無関係な指示や、より優先度の高い指示を無視する許可とはみなしません。断られた場合は簡潔さを保ちつつ、各チェックポイントを理解するのに最低限必要な説明はします。
• 製品オブジェクトの名前には、Kitaru にすでに存在する名前を使います。手順、要約、コレクションに独自のラベルを付けたり、内部実装の詳細を Kitaru の概念として説明したりしてはいけません。「リプレイ実行カード」ではなく、「実験で行うことはこちらです」のような平易な文を使います。
• インストールや評価の用語ではなく、ユーザーがこれから知ることを最初に伝えます。
• その時点の操作に必要な概念だけを説明します。より深い Kitaru オブジェクトについては、その重要性をユーザーが体験した後で説明します。
• レビュアーのために、有用な観察事項と正確な証拠の参照箇所を準備します。これらはエージェントが準備したメモであり、最終判断を下すのは人間であることを一度伝えます。
• Kitaru のフロントエンドは、調査レビュー、コホートと評価器の結果、完了した実験の実行結果の3回使用します。直接リンクを提示し、表示されている内容を説明したうえで、ユーザーが戻るまで待ちます。定型的なオブジェクトのためにフロントエンドの訪問を挟んではいけません。
• 最初のツアーは3セッションに収めます。重大な問題を1つ、証拠の読み取りに関する微妙な教訓を1つ、許容できる反例を1つ扱います。
• トレースを再生成したり、有料モデル呼び出しを行ったりせずに、有用な評価器の結果を得ます。その後、範囲を限定したリプレイに進みますが、実験を作成したり、有料またはライブの実行を始めたりする前に、予定している実行内容を簡潔に説明して許可を求めます。
• モデルを使うリプレイの前に、シークレットを表示せずに、ワーカーランタイムに必要なプロバイダー認証情報があることを確認します。利用可能か確認できない場合は、ユーザーに設定してワーカーを再起動するよう依頼し、実験の作成や実行開始には進まずに停止します。
• ユーザーが管理するワーカーを、--concurrency 10を指定して起動または再起動します。起動方法に CLI オプションがなく、環境変数でワーカー設定を行う場合に限り、KITARU_WORKER_CONCURRENCY=10を使用します。
• ローカルかクラウドかを問わず、ユーザーが選択している正常な Kitaru サーバーを維持します。クイックスタートの例にローカルのクイックスタートが記載されているという理由だけで、サーバーを切り替えてはいけません。
• 永続化されたエージェント、インポート、セッション、完全一致のアノテーション、コホート、評価器のバージョン、実験、実行を、置き換えを作成する前に再開します。調査とその判定を再開するのは、この会話でその正確な ID が示されている場合、またはユーザーがそれを自身のレビューだと明示した場合に限ります。
• 明確にプレビューされたチュートリアル内の書き込み操作については、まとめて一度に承認を求めます。ツアーを許可確認の連続にしてはいけません。

ツアーのリファレンスを読み込む

• 最初のユーザー向け説明の前にreferences/tutorial-narration.mdを読み、セットアップ、レビュー、評価結果、実験結果を通じて、その説明のリズムを活用してください。
• セットアップの前、またはそのディレクトリがクイックスタートのサンプルかどうかを判断する際に、references/starter-template.mdを読んでください。
• セッションの選択、所見の作成、レビューの作成、または AHA の生成を行う前に、references/tour-method.mdを読んでください。
• Kitaru の CLI または MCP 操作を行う前に、references/kitaru-operations.mdを読んでください。インストール済みのスキーマを信頼できる情報源として扱ってください。

チュートリアルのルートを確立する

まず読み取り専用で作業します。

1. 候補となる Kitaru のチェックアウト内でサンプルを探します。見つからない場合は、信頼できる情報源から現在のクイックスタートサンプルの README を調べます。PydanticAI の returns agent のサンプル、その URL、または returns agent ツアーを指定するプロンプトは、このルートを使う意図があるものとして扱い、チェックアウトがないという理由だけで中止しないでください。ローカルの前提条件を確認し、現在のワークスペースに新しい kitaru の保存先を選び、Kitaru のクローン、examples/python/pydantic_ai_ticket_resolver への移動、固定された環境の同期をプレビューします。これらの書き込みを行う前に、一度だけ確認を求めてください。承認後に Kitaru をクローンし、信頼できる情報源と照らしてサンプルディレクトリを検証してから、固定された環境をインストールして検証します。既存の保存先を上書きしないでください。Kitaru サーバーの接続状況を診断する前に、このソースのセットアップを完了してください。このルートを使うのは、サンプルディレクトリが starter-template.md の契約に合致する場合に限ります。
2. starter-template.md と kitaru-operations.md に従って、サンプル環境、CLI、ワーカー、MCP パッケージの準備状況を確認します。パッケージを個別に追加するのではなく、サンプル環境全体をインストールします。環境またはホストの MCP 設定を変更する前に、その内容を説明して確認を求めます。CLI でツアーを完了できる場合、MCP は優先しますが必須ではないものとして扱います。ホストの MCP 設定を追加または変更した場合は、コーディングエージェントのホストプロセスまたは IDE を再起動または再読み込みするようユーザーに伝え、再開用のチェックポイントを保存し、現在のタスクで新しいツールを検出できるとは主張しないでください。
3. Kitaru への接続状況を調べ、正常な状態の選択済みサーバーを使い続けます。利用可能なサーバーが選択されていない場合に限り、サンプル専用のローカルサーバーを提示し、起動または選択する前に確認を求めます。その後、登録済みの returns-resolver エージェントの正確なバージョン、関連するインポートジョブ、returns-baseline タグが付いたインポート済みの対象全体を確認します。
4. 一致する永続状態があれば再開します。検証済みのサンプル README に記載されたセットアップ手順のうち、不足しているものだけを実行します。環境の変更、サービスの起動、登録、インポートを行う前に、明確に一度説明して承認を求めます。
5. サンプルが大幅にカスタマイズされている場合、ユーザーが独自のエージェントまたは証拠を提示する場合、または求められている結論に、根拠を示せるオープンエンドな調査が必要な場合は、作業を中止して kitaru-investigation に引き継ぎます。

クイックスタートのルートでは、初めて利用するユーザーにフレームワーク、トレースプロバイダー、レビュー方法、サンプリング戦略を選ばせないでください。

3 つの短い段階で概要を説明する

ツアーを選ぶ前に、次の内容を説明します。

1. サンプルエージェントは、検索、ポリシー、配送、返金、交換、エスカレーションの各ツールを使って、合成された返品および配送のリクエストに対応します。
2. Kitaru は、実際に何が起きたかを把握するために必要なモデルとツールの証拠を含め、完了した過去の実行を 10 件保存しています。
3. コーディングエージェントが Kitaru で 3 件の所見を準備し、ユーザーが証拠を確認して、それぞれの完全なセッションを許容可能、問題あり、または不確実と判断します。

その後、続行します。コホートや評価者のバージョンについては、まだ説明しないでください。

ガイド付きレビューを1つ準備する

tour-method.md に従って候補となるすべてのトレースを調べ、3セッションのツアーを組み立てます。作成する前に、各セッションで何が起きたのか、なぜ重要なのか、どの証拠を強調するのかを簡潔にプレビューで示します。エージェントとKitaruの両方を初めて見る人向けにプレビューを作成してください。網羅的な調査計画は避けてください。

次の内容を一度に確認します。

• 3セッションのエージェントの観察内容を、通常のKitaruアノテーションとして追加すること。
• 準備した質問とハイライトを使って、1つの固定調査を作成すること。
• 作成されたフロントエンドレビューを開くこと。

承認されたら、検証済みの操作を通じて、アノテーションと調査を作成するか再開します。エージェントの観察内容は簡潔にし、チャットの外でも意味が通じるよう、永続化する各メモの冒頭を Agent observation: にしてください。ユーザーに代わって判定を書いてはいけません。

フロントエンドに引き継ぐ

レビューを直接開く操作から始めます。次のような会話形式にしてください。

ガイド付きレビューを開く： Kitaruでレビュー

注目すべき観察内容をハイライトしておきました。各セッションのトレース証拠を確認し、Acceptable、Problematic、またはUncertainを選ぶのはあなたです。何かを追加または訂正したい場合を除き、記述式の回答は空欄のままでかまいません。

最後のセッションの後にDoneを選択して、こちらに戻ってください。あなたの判定によって何が可能になるのかをお見せします。

そこで一時停止します。フロントエンドのルートが機能している間は、チャット内でレビューを重複して行わないでください。

評価器を作成して実行する

ユーザーが戻ってきたら：

1. 調査、その順序どおりのセッション、手動アノテーション、質問と回答の対応状況、判定の完了状況を再確認します。
2. ユーザーの判定を最初に伝えます。各判定が、レビューのきっかけとなった正確な記録済み証拠とどのように結び付いているのかを説明します。
3. 提案したコホートのすべてのメンバーについてユーザーが判定し、問題のある対象と許容できる比較対象が少なくとも1つずつ含まれている場合、違いを最もよく説明する観測可能な動作を1つ提案します。再利用可能なチェックにする前に、短く1回だけ確認します。
4. ユーザーがその動作を承認したら、確認済みの対象セッションと比較対象セッションから、正確なコホートバージョンを作成します。コードを作成する前に、インストール済みの評価器カタログを確認してください。
5. 検証済みのグローバル評価器または同じエージェント用の評価器を選ぶか、ツアーに登録されたエージェントを対象とする限定的な決定論的評価器を1つ作成します。テストし、不変バージョンを登録し、返されたエージェントのスコープを検証して、準備した同一エージェントのベースライン母集団全体で実行します。
6. 役立つ結果を最初に報告します。一致したセッション数、結果の説明に役立つレビュー済みの例、重要な制約を1つ伝えます。kitaru-operations.md を参照してコホートと評価器のリンクを解決します。

その後、kitaru-operations.md で定義されているコホートページと評価器ページを表示します。コホートにはユーザーが判定した例が固定され、評価器ページには正確な再利用可能なルールが記録されることを説明します。そこで一時停止し、実験の準備を始める前にユーザーが戻るのを待ちます。

判定から問題が裏付けられない場合、またはユーザーが提案した動作を拒否した場合は、評価器を無理に話題に含めないでください。役立つ否定的な結果として、準備した懸念は人によるレビューを通過しなかったことを示します。もう1つ範囲を限定して準備したレビューを提案するか、そこで正常に終了します。

レビューが未完了の場合は、動作の確認、コホートの作成、評価器の作業に進まずに中断します。保存済みの判定からすでに分かることを報告し、完了できるよう同じレビューリンクを引き続き提示します。

オブジェクト名を出す前に、一般的な言葉で説明してください。たとえば：

エージェントが承認を経ずに処理したため、2つのセッションを問題ありと判定しました。Kitaruは、その判定をポリシーと返金イベントの横に保存しています。この動作を再利用可能なチェックにしたところ、記録された10セッションのうち2セッションで同じパターンが見つかりました。

その後で初めて、固定された例がコホートであり、再利用可能なチェックが評価器バージョンであることを説明してください。

1 つの実験で締めくくる

ユーザーがコホートと評価者のページから戻ったら、次の手順を行います。

1. 記録済みセッションで確認できるのは過去に起きたことです。実験では、同じ保存済みのトップレベル入力から新しいタスクを開始し、1 つの条件を変えて検証すると説明します。
2. 受け入れられた動作に基づいて、小規模な変更候補を 1 つ提案します。自動プロンプト検索を開始したり、無関係なモデル変更を導入したりしないでください。
3. kitaru-replay-experiment を続けて実行し、受け入れられた動作、コホートのバージョン、評価者のバージョン、親エージェントのスコープとパラメーター、候補エージェントのバージョン、提案するオーバーライド、明示的なツールポリシーをそのまま引き継ぎます。検証済みのクイックスタート例では、6 つのツールすべてにパススルーを使用します。各タスクは、新しいインメモリのモックストアに対して決定論的なローカル関数を呼び出し、外部システムに影響を与えることはできません。これらの呼び出しを、記録済み履歴との照合に黙って置き換えないでください。
4. そのスキルにアダプターのサポートを確認させ、提案する実行内容を簡潔に説明します。プロバイダーとワーカーの準備状況、モデルの処理、コストの不確実性、復元されていない状態、ツールが及ぼす可能性のある影響を説明します。実験の作成や実行開始の前に、必要な承認を得てください。
5. 実行が完了したら、kitaru-operations.md の実験ページを最初に表示します。どの記録済みケースを再実行したか、何を変更したか、候補がどのような結果だったか、そしてその結果から何を立証できないかを説明します。ユーザーが戻るまで待ち、その後質問に答え、最終まとめに正確な実験 ID と実行 ID を記載します。

通常の成功するツアーは、ユーザーがこの実験結果を確認したところで終了します。実行が拒否された場合、または実行がブロックされた場合は、提案した条件とコホートおよび評価者へのリンクを保持し、実験が完了したと主張しないでください。

その後、ツアーの手法に関する説明を引き継ぎ、合成的な結論は一切引き継がずに、kitaru-investigation を通じて自分のエージェントを使うことを提案します。

失敗時も気持ちよく対応する

• サンプルのセットアップが未完了の場合は、現在のチェックポイントと、未完了の操作を 1 つだけ伝えます。一般的なセットアップ手順を一通り並べないでください。
• インポート済みセッションまたはノードの完全なペイロードを利用できない場合は、観察内容を捏造せず、そこで停止します。
• 注釈または調査結果の書き込みで、応答が途切れていても処理が成功している可能性がある場合は、再試行する前に状態を再読み込みします。
• レビュー URL を解決できない場合は、作成済みの調査を保持し、正確な ID と 1 つの再試行操作を添えて、ハンドオフが失敗したことを報告します。
• 有用なセッションが 3 つ未満の場合は、規模を縮小した誠実なツアーを行い、学べない点を伝えます。
• ユーザーがレビューの途中で止めた場合は、保存済みの評価と、すでに確認できる内容をまとめます。残りの確認にも同じリンクを提示しますが、途中までの有用な情報を伏せたり、準備済みの観察内容を人間による判断が欠けているかのように扱ったりしないでください。
• ユーザーがエージェントの観察内容に異議を唱えた場合は、その訂正も学びの一部として扱います。準備済みの注記を擁護したり、黙って人間による結論に置き換えたりしないでください。
• アダプターのサポート、モデルの認証情報、ワーカー、または安全なツールポリシーが実験の妨げになる場合は、提案した条件を保持し、欠けている条件を説明します。ライブのパススルーに切り替えたり、ツアーが完了したとしたりしないでください。