kitaru-adapter-builder

Kitaru アダプタービルダー

まず、サポート対象となる統合のうち、要件を満たす最小限のものを選択してください。サポート対象の方法では求められる記録とリプレイの境界を満たせない場合に限り、ユーザーのプロジェクト内にアダプターを構築してください。フレームワークの公開エントリーポイントを維持し、選択したアダプターまたはカスタムアダプターで何を観測、記録、リプレイでき、何から復旧できるのかを正確に報告してください。

すべてのフレームワークで同じ忠実度を実現できるとは限りません。有用な成果は、ローカルでテスト済みのアダプター、またはインストール済みバージョンと公開フックに関連付けた明確な阻害要因のいずれかです。

コア契約

• ユーザーのプロジェクトとインストール済みパッケージの読み取り専用の調査から始めてください。
• 求められる記録とリプレイの要件を満たす場合は、サポート対象の Kitaru アダプター、インポーター、または OTLP エクスポートを優先してください。重複する統合を作成しないでください。
• すでに Langfuse、Braintrust、LangSmith、Logfire、または Arize Phoenix を使用して計測されている Python エージェントについては、カスタムコードを提案する前に、そのプロバイダーのインポーター対応アダプターを確認してください。パッケージと機能の契約については、Python アダプターのリファレンスを参照してください。
• ユーザーがインストールした SDK とフレームワークを正としてください。Kitaru のリファレンスアダプターはパターンとして扱い、コピー元として、または公開 API の根拠として使用しないでください。
• フレームワークの公開フックのみを使用してください。完全なカバレッジに非公開の内部実装が必要な場合は、より粗い境界を提示するか、作業を中止してください。
• まずユーザーのプロジェクト内で実装してください。ユーザーが別途承認しない限り、Kitaru のコアを編集したり、上流へのコントリビューションを準備したりしないでください。
• 実行ごとのセッション ID、クライアント、ノードインデックス、バッファー、リプレイ状態、フレームワークコンテキストを分離してください。共有ラッパーに呼び出し状態を保存しないでください。
• 部分的に記録された実行は、不完全または失敗した証拠として扱ってください。アプリケーションが正常に戻ったという理由だけで、完全なトレースと呼ばないでください。
• リプレイはトランザクションではなく実行として扱ってください。選択したポリシーとユーザーの承認によって安全性が確保されていない限り、未知の副作用や書き込み可能な副作用をブロックしてください。
• 関連する承認なしに、依存関係をインストールしたり、認証情報を必要とするプロバイダーを呼び出したり、リモートの Kitaru セッションを作成したり、書き込み可能なツールを実行したり、変更を公開したりしないでください。
• すべての Kitaru CLI コマンドと SDK スクリプトは、サーバーが生成されたアクティビティをこのスキルに関連付けられるよう、KITARU_ACTIVE_SKILL=kitaru-adapter-builder を設定して実行してください。
• ユーザーが制御するワーカーを起動または再起動するときは、--concurrency 10 を指定してください。起動方法で CLI オプションではなく環境変数を通じてワーカー設定を公開している場合に限り、KITARU_WORKER_CONCURRENCY=10 を使用してください。

プロジェクトからルートをたどる

実際のエージェントのエントリーポイントを含むプロジェクトから始めます。

1. リポジトリの指示を読み、作業ツリーを確認します。既存の変更と並行して行われている変更はすべて保持してください。
2. パッケージマネージャー、ロックファイル、ランタイム、言語、フレームワークとそのバージョン、Kitaru パッケージとそのバージョン、公開エージェントのエントリーポイント、アプリケーションが実際に使用する呼び出しモードを特定します。
3. エントリーポイントのランタイムに応じてルートを選びます。
   • Python の場合は、Python アダプターのリファレンスを読みます。
   • TypeScript の場合は、 TypeScript アダプターのリファレンスを読みます。
   • その他のランタイムの場合は、対応していない言語として報告し、作業を終了します。
4. アダプターの手法を読み、プロジェクト、インストール済みパッケージ、最新の Kitaru ドキュメントを検索して、互換性のあるアダプター、インポーター、OTLP 経路を探し、コードを編集する前にアダプターの評価を作成します。
5. 設計を確定する、またはテストを作成する前に、検証と報告を読みます。

複数の言語が存在するリポジトリでは、エージェントを実行するプロセスを起点にルートを選びます。リポジトリ内に両方の言語が存在するというだけで、両方の言語のリファレンスを読み込まないでください。

対応するインポーターを利用するアダプターが、プロバイダー、公開 Python エントリーポイント、要求された記録境界に適合する場合は、承認を得てからインストールし、そのエントリーポイントをラップします。実行後にプロバイダートレースから Kitaru セッションを作成しますが、モデル呼び出しやツール呼び出しをインターセプトするものではありません。記録するためだけに、重複するアダプターを構築しないでください。ランタイムのオーバーライドや、パススルーではないツールポリシーが必要な場合は、代わりにネイティブアダプターを使用します。

フレームワークが、組み込みインポーターでは対応していない形式でトレースをすでにエクスポートしており、事後的な証拠でユーザーの目的を満たせる場合は、ライブのエントリーポイントをラップせずに kitaru-importer-builder を使用します。リポジトリとリビジョン、公開エントリーポイント、フレームワークとそのバージョン、エクスポート元と形式、Kitaru パッケージとそのバージョン、対象エージェントとそのバージョン、要求された証拠を引き継ぎます。このルートを選んだら、インポーターが代替案としてアダプターに言及しているというだけで元に戻らないでください。

要求された忠実度を確認する

実装を選ぶ前に、次の点を分けて検討します。

質問	回答例
記録境界	呼び出し全体、ターン、モデルステップ、ツール呼び出し、サブエージェント呼び出し、またはより粗いスパン
リプレイの段階	入力の再実行、ターンのリプレイ、フレームワーク固有の境界リプレイ、より細かなチェックポイントのリプレイ、またはリプレイを保証しない
ツールの可視性	ローカルツール、MCP ツール、プロバイダー固有のツール、フレームワーク内の非公開ツール、または不明
呼び出しモード	非同期、同期、ストリーミング、手動イテレーション、バッチ、ハンドオフ、再開、中断、または永続実行
失敗ポリシー	Kitaru の失敗によって呼び出しが失敗する、または劣化した結果を明示したうえで記録はベストエフォートとする

「リプレイ」という言葉を使う場合は、段階を明記します。同じルート入力を再度実行するのは入力の再実行であり、決定論的なリプレイではありません。

ストリーミングでは、次の3つの主張を分けてください。

1. アプリケーションが引き続きトークンまたはイベントを生成すること。
2. アダプターが、完了、失敗、キャンセル、中断までストリームを監視すること。
3. リプレイによって元のチャンクやタイミングが再現されること。

いずれかをサポートしているからといって、ほかもサポートしているとは限りません。

必要な場合はコードを書く前に中止する

次のいずれかに該当する場合は中止し、理由を正確に伝えてください。

• 既存の互換アダプター、インポーター、または OTLP ルートで要件を満たせる場合。
• プロジェクトが Python または TypeScript ではない場合。
• 利用可能な公開 Kitaru SDK コントラクトがインストールされておらず、インストールも承認されていない場合。
• フレームワークに、必要な境界で利用できる公開フックがない場合。
• Python のエントリーポイントが同期処理のみで、利用可能な Kitaru コントラクトが非同期処理であり、ドキュメント化された安全な非同期フレームワークフックもない場合。
• 要求された動作が、隠れたプロバイダーまたはフレームワークの処理に依存する場合。
• リプレイの安全性に、インストール済み SDK が公開していない Kitaru コントラクト（マッチ件数、出現識別子など）が必要な場合。
• 不完全なインポート済みベースラインでは、エフェクトを伴うリプレイに必要な呼び出しを証明できない場合。
• 必要な依存関係が公開されておらず、ユーザーがローカル tarball またはワークスペースリンクの使用を承認していない場合。

不足している SDK コントラクトを、手書きの REST 呼び出し、即席のイベントループブリッジ、非公開のフレームワークインポート、またはコピーしたドラフト版プラグインコードで代用しないでください。

明示的な承認ゲートを設ける

読み取り専用の調査には、個別の承認は必要ありません。ユーザーの環境または外部状態を変更する各操作の前に、承認を求めてください。

操作	必要な承認
依存関係のインストールまたは変更	正確なパッケージ、バージョン、パッケージマネージャーコマンド
公開されていない TypeScript アーティファクトのローカル使用	正確な tarball またはワークスペースリンクのパス
モデルまたはその他の認証情報が必要なプロバイダーの呼び出し	プロバイダー、想定される呼び出し回数、コストまたはデータへの影響
リモート Kitaru セッションの作成	エンドポイント、テナント、キャプチャするカテゴリ、テストの目的
ツールのライブパススルーの許可	正確なツール、エフェクトクラス、ミス時の条件
OSS コントリビューションの準備	対象リポジトリ、ファイル、コントリビューションの範囲

いずれかの行に対する承認は、他の行を許可するものではありません。

範囲を限定したチェックポイントに分けて実装する

次の順序で進めてください。

1. 決定論的なローカルプローブで、公開フレームワークフックを確認します。
2. アダプターの評価と機能に関する主張を確定します。
3. 実行ごとの状態とセッション／ルートのライフサイクルを実装します。
4. 公開フックで確認できる範囲に限り、モデル、ツール、サブエージェント、ストリームの監視を追加します。
5. ベースラインの適格性と副作用に関するゲートを通過した後にのみ、リプレイを追加します。
6. 広範なシリアライズの前に、範囲を限定した許可リスト方式のペイロード射影を定義します。
7. フェイクを使って、成功、主要なアプリケーション障害、Kitaru の書き込み障害、並行実行、キャンセル、および主張するすべてのリプレイポリシーをテストします。
8. アプリケーションの結果だけを信頼せず、記録されたセッションとノードツリーを調査します。
9. 機能レポートを作成します。

フレームワークの公開シグネチャ、戻り値、設定済みコールバック、例外動作、型サーフェスを維持してください。それらを維持できない場合は、実装前に API の変更を報告してください。

失敗を証拠として扱う

最初に発生したアプリケーションまたはアダプターの失敗を保持してください。その失敗を覆い隠さずに終端失敗の記録を試み、その後に発生した記録またはクリーンアップのエラーは別途報告してください。

セッションの作成に成功した後で書き込みが失敗した場合：

• すでに確認済みのノードを保持します。
• 最後に確認済みの書き込みを記録します。
• ルートとセッションを失敗としてマークすることを試みます。
• トレースが完全であると主張しないでください。
• アプリケーションの呼び出しには、アダプターでドキュメント化された Kitaru 利用可否ポリシーを適用します。

ここでは、不完全なインポート済みトレースはリプレイ入力の問題です。評価し、安全でないリプレイを中止してください。このスキル内でインポーターを修正したり再設計したりしないでください。

安全に再開する

再開した実行では、プロジェクト、作業ツリー、インストール済みバージョン、アダプター評価、テストを再度読み取ってください。選択したフックと SDK シンボルが引き続き存在することを再確認してください。以前のトランスクリプトを利用できないという理由だけで、ユーザーの変更を上書きしたり、依存関係のインストールやリモートスモークテストを繰り返したりしないでください。

正直な引き継ぎで締めくくる

検証と報告の機能レポート形式を使用します。 フェイクを使って検証した内容、実際の Kitaru セッションで検証した内容、引き続きサポートされていない、または未検証の内容を明記します。

主張するすべてのモードがローカルでパスした後に、別途、任意のコントリビューション手順を案内します。ハッピーパスが動作しただけで、プロジェクト固有のアダプターがアップストリームに取り込める状態であるかのように示してはいけません。