AIチュートリアル

Dot Reflex 14Bでエージェントの安全な復旧ループを構築する

Dot Reflex 14Bのインストール方法、CLIまたはHTTPサービス経由でエージェントの軌跡を送信する方法、10種類の制御アクションの解釈方法、そしてデプロイと評価の制限を踏まえて推奨事項を実行ハーネスに接続する方法を学びます。

2026年8月29日約17分で読了

Dot Reflex 14Bの機能

Dot Reflex 14Bは、コーディングエージェントやツールを使用するエージェント向けの実行リカバリーコントローラーです。ワーカーエージェントを置き換えるものではありません。代わりに、エージェントの軌跡を要約したコンパクトなJSONを確認し、実行の次の段階を周辺ハーネスがどのように制御すべきかを推奨します。

このコントローラーは、正規化された実行イベントを処理するため、ワーカーモデルの内部アーキテクチャに依存せず、GPT、Claude、Gemini、Qwen、Llamaなど、さまざまなモデルで動作するエージェントを監督できます。今回のリリースは、Qwen3-14B-Base向けのランク64 QLoRAアダプターです。

Dot Reflexは、次の10種類のアクションのいずれかを返します。

continue：妥当な計画を続行する。
verify：主張やリスクのある前提を裏付ける証拠を求める。
retry_differently：別のコマンド、パラメータ、または方法で直前の試行を繰り返す。
replan：中核となる前提が破綻したアプローチを置き換える。
rollback：有害な変更の後に、正常な状態へ復元する。
branch：複数の実行可能性があるアプローチを別々の環境で分離する。
switch_model：能力不足やプロバイダー障害が継続した場合、次の試行を別のモデルへ振り分ける。
ask_human：権限、秘密情報、確認、または外部の判断が必要な場合に一時停止する。
stop_successfully：十分な証拠によって完了が裏付けられた場合に終了する。
stop_failure：安全かつ承認済みのリカバリー手段が残っていない場合に停止する。

出力は承認ではなく推奨です。権限、ポリシーの適用、ツールの実行、ロールバックの仕組み、そして停止する最終判断については、引き続きハーネスが責任を負います。

主な機能

フレームワークに依存しない入力：コントローラーは、エージェントフレームワークがすでに記録した実行イベントから組み立てられた通常のJSONを受け付けます。
機械可読な出力：有効な応答にはすべて、アクション、理由、信頼度、リカバリー手順、解析ステータスが含まれます。
決定論的な生成：リファレンスランタイムでは貪欲法による生成を使用します。
フェイルクローズ動作：入力スキーマまたは生成されたアクションが無効な場合、CLIはゼロ以外のステータスで終了します。
複数のインターフェース：コマンドラインから1回の判断を実行したり、標準入力経由でJSONをパイプしたり、ローカルHTTPエンドポイントをホストしたりできます。
モデル横断の監督：ワーカーエージェントがQwenを使用したり、コントローラーと同じアーキテクチャを共有したりする必要はありません。

要件とインストール

リファレンスの4ビットランタイムには、LinuxとNVIDIA GPUが必要です。一度に1リクエストを処理する場合、実用上の最低要件は24 GB GPUですが、40～48 GBあればさらに余裕があります。このリリースには、GGUF、Ollama、MLX、CPU版、または重みを統合したビルドは含まれていません。

リポジトリをクローンし、Python仮想環境を作成して、ランタイムの依存関係をインストールします。

git clone https://github.com/usedotai/dot-reflex.git
cd dot-reflex
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

GitHubリポジトリには、ランタイム、テスト、サンプル、ドキュメント、評価レシートが含まれています。約1.03 GBのアダプターはHugging Faceでホストされており、初回使用時に自動的にダウンロードされます。固定されたQwen3ベースモデルの重みも、Hugging Faceによってダウンロードおよびキャッシュされます。

リリースを検証する

リポジトリのルートから、Linux上でソースペイロードを検証します。

sha256sum --check SHA256SUMS

macOSでは、以下の同等のコマンドを使用します。ただし、macOSはリファレンスGPUランタイムのサポート対象プラットフォームには含まれていません。

shasum -a 256 -c SHA256SUMS

モデルを読み込まずに、ソースマニフェスト、固定されたベースモデルの識別情報、JSONサンプル、スキーマ、チャートのレシートを検証できます。

python3 scripts/validate_release.py

エージェントの軌跡を準備する

Dot Reflexが必要とするのは、生のトランスクリプトではなく、コンパクトなスナップショットです。入力コントラクトの詳細はtrajectory.schema.jsonで定義されています。多くのエージェントシステムでは、フレームワーク固有のイベントをこの構造にマッピングする小さなアダプターが必要です。

たとえば、エージェントがパスワードリセットのコードを編集し、テストを実行せずに完了を主張したとします。軌跡は次のようになります。

{
  "task_summary": "Add password-reset token validation",
  "execution_history": [
    {
      "step": 1,
      "actor": "agent",
      "action": "Modified auth/reset.py and declared completion.",
      "result": "Patch applied; no verification was run."
    }
  ],
  "tool_results": [
    {
      "tool": "pytest",
      "status": "not_run",
      "summary": "Tests were never executed."
    }
  ],
  "current_state": "Code changed, but there is no evidence it works.",
  "detected_failure_signals": ["false_completion_risk"]
}

その後、コントローラーは不足している証拠を特定し、次のような構造化された判断を返せます。

{
  "action": "verify",
  "rationale": "The agent claimed completion without test evidence.",
  "confidence": 0.98,
  "recovery_instructions": "Run the targeted reset-token tests, then the relevant auth suite.",
  "parse_valid": true
}

ハーネスが正確に裏付けられる証拠だけを含めてください。不足しているイベント、古いイベント、または誤解を招くイベントがあると、誤った推奨につながる可能性があります。

基本的な判断を実行する

リポジトリには、誤った完了判定のシナリオ用の軌跡の例が含まれています。ワンショットCLIに渡します：

python3 inference.py examples/trajectory_false_completion.json \
  --adapter usedot/Dot-Reflex-14B

入力パスに-を指定すると、標準入力経由で軌跡をパイプすることもできます：

python3 inference.py - --adapter usedot/Dot-Reflex-14B \
  < examples/trajectory_false_completion.json

オーケストレーターでは、プロセスの終了ステータスと返されたparse_validフィールドの両方を確認してください。ゼロ以外の終了ステータスは、入力スキーマまたは生成されたアクションが無効であることを示すため、自動的な継続を रोक止してください。

Dot ReflexをローカルHTTPサービスとして実行する

トレーニングの動態

追加のサーバー依存関係をインストールし、UvicornでFastAPIアプリケーションを起動します：

python3 -m pip install -r requirements-server.txt
uvicorn serve:app --host 127.0.0.1 --port 8080

同じ軌跡を意思決定エンドポイントに送信します：

curl --fail-with-body \
  -H 'content-type: application/json' \
  --data @examples/trajectory_false_completion.json \
  http://127.0.0.1:8080/v1/decision

この例ではlocalhostにバインドします。サービスをネットワークに公開する前に、認証、TLS、レート制限、リクエストサイズ制限、監査ログを追加してください。

コントローラーをエージェントループに統合する

生成されたすべてのトークンの後ではなく、意味のある証拠ゲートでDot Reflexを呼び出します。役立つチェックポイントには、失敗したツール呼び出し、アクションの繰り返し、コード編集、テストまたはビルド結果、環境の変更、完了の主張などがあります。

trajectory = harness.snapshot_for_supervisor()
decision = reflex.predict(trajectory)

if decision["action"] == "continue":
    harness.resume()
elif decision["action"] == "verify":
    harness.require_verification(
        decision["recovery_instructions"]
    )
elif decision["action"] == "ask_human":
    harness.pause_for_user(decision["rationale"])
elif decision["action"].startswith("stop_"):
    harness.stop(decision)
else:
    harness.apply_recovery_control(decision)

このパターンでは責任を分離できます。Dot Reflexは復旧の必要性を分類し、ハーネスは実際の操作を実行します。たとえば、rollbackの推奨は、ハーネスが事前に定義し、承認したロールバックプリミティブだけを呼び出すようにしてください。

コントローラーは、イベントを正規化することで、LangGraph、OpenAI Agents SDK、OpenHands、AutoGen、CrewAI、Google ADK、またはカスタムツールループに接続できます。ラッパーまたはフックがイベントストリームを取得しない限り、Cursor、Claude Code、Codex CLI、Aider向けのそのまま使えるミドルウェアではありません。マッピング例と互換性に関する注意事項は、INTEGRATION.mdを参照してください。

高度な統合のヒント

最小限で決定的な検証を使用する

アクションがverifyの場合は、主張を確認または却下できる最も狭い範囲のチェックを優先します。コーディングワークフローでは、大規模なスイートの前に対象を絞ったテストを実行することなどが考えられます。結果を記録し、次の証拠ゲートで新しい軌跡を送信してください。

すべてのアクションを明示的にマッピングする

未知または未対応のアクションをcontinueとして扱わないでください。10種類すべてのアクションに対するハーネスの動作を定義し、生成されたアクションを検証し、解析またはポリシーチェックに失敗した場合は安全に停止してください。

実際の復旧プリミティブを提供する

ハーネスが強制できなければ、推奨事項は役に立ちません。branchに対応するシステムでは、分離されたworktreeまたはサンドボックスを作成する必要があります。rollbackに対応するシステムでは、既知の正常な復旧可能状態を維持する必要があります。マルチモデルルーターでswitch_modelを実装するには、実際のルーティング機構が必要です。

機密性の高い意思決定は人間が管理する

エージェントに権限、秘密情報、明確化、または外部の意思決定が不足している場合は、ask_humanを使用してください。モデルの出力だけで、破壊的、金銭的、医療、法務、セキュリティ関連、その他影響の大きいアクションを承認できるようにしてはいけません。

信頼度をローカル環境で調整する

返される信頼度の値は生成テキストであり、安全性を保証するものではありません。しきい値や自動化ポリシーを適用する前に、自分の環境を代表する軌跡を使って測定し、再調整してください。

証拠と監査証跡を保持する

入力軌跡、コントローラーの応答、実行した復旧アクション、その後の結果を保存してください。これらの記録により、障害の調査が容易になり、コントローラーが自分のワークロードに適用できるかどうかの評価にも役立ちます。

評価の範囲を理解する

Dot Reflexは6,000件の合成軌跡でトレーニングされ、600件の合成軌跡で検証されました。公開されているAgent Recovery Bench v0の評価には、バランス調整された保留用の合成軌跡1,000件と、別個の状態を持つ合成復旧エピソード200件が含まれています。

この合成ベンチマークで、アダプターは復旧精度1.000、マクロF1 1.000、シミュレーション復旧1.000を達成しました。報告された平均レイテンシはNVIDIA H200上で6.13秒でしたが、これは実行ごとの測定値であり、普遍的なサービス性能を示すものではありません。

合成環境での100%という結果は、普遍的な信頼性を証明するものではありません。このベンチマークは、SWE-benchでも、エンドツーエンドのリポジトリ課題解決テストでも、本番環境での試行でもありません。

公開されたデータはベンチマーク分布への適合性を示すものであり、独立して作成された障害や本番環境の障害への信頼できる転移を示すものではありません。結果を引用したり、デプロイポリシーを設計したりする前に、EVALUATION.mdを確認してください。

モデルとランタイムの詳細

ベースモデル： Qwen/Qwen3-14B-Base。
手法： BF16計算を用いた4ビットNF4 QLoRA。
LoRA設定：ランク64、アルファ128、ドロップアウト0.05。
対象モジュール：アテンションおよびMLPの射影レイヤー。
学習コンテキスト： 2,048トークン。
学習可能なパラメータ： 256,901,120（ベースモデルの1.710%）。
ライセンス：リポジトリおよびアダプターファイルはApache-2.0。

Qwenのベースモデルは、別個の上流依存関係です。結合したシステムを配布またはデプロイする前に、そのモデルカードとライセンスを確認してください。

結論

Dot Reflex 14Bは、エージェント実行ループに構造化されたリカバリーレイヤーを追加します。まずGPUランタイムをインストールし、既存のイベントを軌跡スキーマに変換して、CLIから1つの判断をテストしてください。その後、HTTPサービスを追加するか、カスタムハーネスのエビデンスゲートでコントローラーを呼び出せます。実行権限はハーネスに保持し、すべての応答を検証し、監査証拠を保持してください。自動化を有効にする前に、独自のワークロードで性能を評価してください。