Agentic HIL

Agentic HIL

AI を現実につなぎましょう。

エージェントがファームウェアを自律的に開発、テスト、改善できるようにします。現実の世界で実現します。Agentic HIL は厳格な安全境界を適用し、実際のハードウェアで結果を検証する必須ゲートとして、これを可能にします。

https://github.com/user-attachments/assets/8d39ba93-beeb-484e-b9e9-d9ce79538523

エージェントが新しいファームウェアプロジェクトをセットアップし、ファームウェアを書き込み、インストール後に一度再起動して、ボードに Hello World と表示させる様子をご覧ください。この録画には、ゲートを介した実際のハードウェアからのフィードバックが映っています。エージェントはテスト計画を保存し、正しい期待値と、意図的に誤った期待値の両方で実行します。テスト計画、レポート、テストが成功する場合と失敗する場合の証拠が得られます。実行はリースが解放され、安全な状態が確認され、隔離されたものがない状態で終了します。

はじめに

1 つのコマンドで Agentic HIL をユーザー環境にインストールできます。管理者権限は不要です。

Linux / macOS（すべてのシェル）：

curl -LsSf https://agentic-hil.github.io/install.sh | sh

Windows、PowerShell の場合：

irm https://agentic-hil.github.io/install.ps1 | iex

インストーラーは、PATH 上で検出した、サポート対象のすべてのエージェント CLI にスキルと MCP サーバーを登録します。インストール先はリポジトリの外部です。エージェントを一度再起動してから、最初のハードウェアに関する質問をしてください。エージェントは MCP を通じてプロジェクトのベンチをセットアップします。

claude、codex、opencode の CLI が見つからない場合、インストーラーは次の手順を表示します。エージェント CLI をインストールしてから、agentic-hil agent-install --agent <claude-code|codex|opencode> を実行して登録してください。

インストーラーはパッケージマネージャーにユーザー用 bin ディレクトリの場所を問い合わせ、必要に応じてそのディレクトリをシェルの起動ファイルまたは Windows ユーザーの Path に追加します。このコマンドを使用するには、新しいシェルを開いてください。この変更を自分で管理する場合は --no-path（PowerShell では -NoPath）を渡してください。インストーラーは追加する行を表示します。

新規インストールでは PyPI から agentic-hil[can] を取得します。リリースを固定するには --version <x.y.z> を使用してください。インストーラーを再実行すると既存のインストールが修復されます。.devN バージョンを報告する編集可能なチェックアウトは維持され、パス、URL、または git 参照からインストールされた uv ツールは、記録されたソースから更新されます。インストーラーを実行する前に確認および検証するには、インストールに記載されているチェックサムを使う方法に従ってください。同じリリースからスクリプトとチェックサムをダウンロードし、ファイルを確認してから、そのファイルを実行します。

初回実行をガイド付きで試すには、STM32 スターターをお試しください。Nucleo-F446RE で 3 ステップの手順を進められるよう、ファームウェア、テスト計画、仕込まれた不具合が用意されています。

Claude Code では、プラグインマーケットプレイスからスキルをインストールすることもできます。 /plugin marketplace add agentic-hil/agentic-hil を実行し、続けて /plugin install agentic-hil@agentic-hil を実行してください。 上記のインストールコマンドは、リポジトリ外の検証済み絶対実行パスを使用して、引き続き MCP サーバーを提供、登録します。

cmd.exe の使用、1 つのエージェントの登録、独自のパッケージマネージャーの使用、接続済みベンチのセットアップ、オプションのコンポーネント、アップグレードについては、インストールをご覧ください。agentic-hil upgrade が失敗した場合は、同じインストーラーコマンドでインストールを修復できます。トラブルシューティングでは、起動時の問題を扱っています。

このリポジトリのクローン内で、ボードを使わずに最初のチェックを試すには、次のコマンドを実行します。

agentic-hil check-plan examples/nucleo-f446re_demo/testconfig.yaml

All 1 test plan(s) load through the reactor's loader. と表示され、終了コード 0 で終了します。ベンチの設定は読み込まず、ハードウェアにも触れません。

エージェントにループを完結させましょう

目標を設定します。エージェントがファームウェアを作成してビルドします。Agentic HIL はボードに書き込み、デバイスを動作させ、テスト基準に照らして応答を確認します。テストに失敗すると、エージェントは問題の診断、コードの変更、再試行に利用できる具体的な結果を受け取ります。

Agentic HIL は、この開発ループを可能にするハードウェア実行機能とフィードバックを提供します。ベンチで行う書き込み、テスト、確認の多くが、エージェントのワークフローの一部になります。実行内容、合格したテスト、失敗したテストの記録とともにコードをレビューし、要件、設計上の判断、テストカバレッジに集中できます。

Agentic Hardware-in-the-Loop（Agentic HIL）は、MCP ツールを通じてコーディングエージェントをベンチに接続し、pytest プラグインを通じて CI スイートに接続します。Claude Code、Codex、OpenCode 向けのセットアップを利用できます。

各ハードウェア操作は、結果、診断情報、レポートとログのパスを含む構造化された結果を返します。エージェントは実際の操作に活用できるフィードバックを受け取り、実行記録をたどって結果を確認できます。

ベンチをループに組み込む

Agentic HIL はバックエンドを通じてプローブに接続します。ST-Link は OpenOCD または STM32CubeProgrammer CLI 経由で、CMSIS-DAP プローブは pyOCD 経由で接続します。また、デバッグセッションを開始することなく、esptool と USB-UART ブリッジを通じて ESP32 ターゲットに書き込み、リセットできます。ハードウェアのサポート状況は、プローブとバックエンドによって異なります。

PCAN、SocketCAN、またはカスタムブリッジを使用して、シリアルポートや CAN バス経由でコマンドを送信し、応答を読み取れます。複数の実行で、ブローカー経由で CAN バスを共有できます。

Agentic HIL は Python 3.10 以降を使用して Linux、macOS、Windows で動作し、3 つすべてのプラットフォームで CI によるテストを行っています。Nucleo-F446RE の例では、ループのデモに使用するボードで一連の実行を行う方法を説明しています。バックエンドとプラットフォームの詳細については、インストールを参照してください。

ファームウェアをテストする

レビュー可能な YAML テストプランに、デバイスがどのように動作するべきかを記述します。テストリアクターはハードウェアに触れる前にプランを検証し、その後、指定した順序でデバイスへの書き込み、リセット、動作確認を行います。チェックでは、実際の応答を正確な値、パターン、または数値範囲と比較します。デバイスが期待どおりに動作すると、チェックは合格します。

プランでは論理デバイスを指定し、ベンチ設定でそれらを実際のハードウェアに接続します。デスクでも CI でも同じプランを使用できます。ステップに失敗すると実行は停止します。セッションはクリーンアップされ、設定済みの復旧アクションとその結果がテスト結果とともに記録されます。初めてのハードウェアテストを書く

境界を確実に守る

エージェントが使用できるデバイスと操作は、ユーザーが決定します。Agentic HIL は、ドライバーを開く前に、宣言されていないデバイスを拒否します。権限を適用し、リクエストを検証し、タイムアウトを設定して、実行内容を記録します。CLI、MCP ツール、pytest プラグイン、テストリアクターは、すべて同じゲートを通過します。

信頼できる設定は、ワークスペースの外、つまりエージェント自身のファイルツールが届かない場所にあります。設定で許可されている権限を確認してください。個別の権限を変更するには、自分のシェルから agentic-hil revoke <key> または agentic-hil grant <key> を実行します。MCP 経由では、エージェントは自身の権限を狭めることしかできません。allow_raw_debugger_commands または allow_mass_erase のいずれかが有効な場合、フラッシュは拒否されます。

デバイスリースは、マシン全体で実行同士が干渉しないよう保護し、SHA-256 監査チェーンはハードウェアの記録が改ざんされていないことを検証可能にします。実行に失敗した場合も、その失敗判定は維持され、設定済みの復旧処理によってベンチの復旧を試み、結果を記録します。監査証跡が破損した場合、オペレーターが復旧するまでベンチは停止します。別のハードウェアテストでは、失われた証拠を再構築できないためです。

概要については安全性モデルを、詳細な設計意図についてはセキュリティ設計をお読みください。

実機のボードで試す

まず Nucleo-F446RE のデモから始めましょう。ボードを接続し、ファームウェアをビルドして、サンプルのディレクトリから Agentic HIL を設定します。

cd examples/nucleo-f446re_demo
cmake --preset Debug && cmake --build --preset Debug   # → build/Debug/nucleo-f446re_demo.elf
agentic-hil setup --agent claude-code                  # or: codex / opencode
agentic-hil doctor

doctor は、接続されたベンチに照らして設定を確認し、フラッシュする前に不足しているツールやハードウェアを報告します。設定後にボードを接続した場合は、agentic-hil adopt-hardware を実行すると、未設定のプローブ ID、バックエンドの実行ファイル、COM デバイスが補完されます。まず変更内容を確認するには、--dry-run を使用します。OpenOCD はあるものの STM32CubeProgrammer がないホストでは、ホストの USB インベントリから接続されている ST-Link を特定できます。複数のプローブが接続されている場合は、--probe-id <serial> を使用して選択します。

サンプルのハードウェアテストプランを実行します。

agentic-hil test-reactor --test-config testconfig.yaml

プランは、ファームウェアをフラッシュし、シリアルポートを開き、ボードをリセットして、起動時の出力に Hello World が含まれているかを確認します。起動メッセージがない場合や正しくない場合、テストは失敗し、診断用にデバイスの出力を返します。ステップが失敗した場合も含め、実行中に開いたセッションは終了時に閉じられます。

エージェントは、MCP ツールを通じて同じステップを実行できます。サンプルのディレクトリから pytest tests/ を実行すると、起動確認を回帰テストスイートに追加できます。サンプルガイドでは 3 つすべての方法を説明しており、ハードウェアテストでは独自のデバイス用プランの作成方法を紹介しています。

さらに詳しく

次のステップ	読む
CAN、pyOCD、esptool のサポートをインストール、アップグレード、または追加する	docs/installation.md
ベンチとその権限を定義する	docs/configuration.md
MCP 経由でハードウェアを操作する	docs/mcp-tools.md
特定の MCP ホストに接続する	docs/mcp-hosts.md
YAML または pytest でハードウェアテストを作成する	docs/testing.md
安全性の境界と復旧の仕組みを理解する	docs/safety-model.md と docs/security-design.md
プラットフォームと応答時間に関するコミットメントを確認する	docs/support.md
失敗した実行を診断する	TROUBLESHOOTING.md
このプロジェクト用にエージェントを設定する	AI_AGENT_QUICKSTART.md と AGENTS.md

パッケージのインストール、CLI コマンド、リポジトリ URL、MCP サーバー名には agentic-hil を使用します。Python のインポート、pytest プラグイン名、フィクスチャ、Python のサンプルには agentic_hil を使用します。

開発

Agentic HIL 自体を開発するには、次の手順に従います。

python -m pip install -e '.[dev]'
ruff check src tests evals tools
pytest
python -m build
twine check dist/*

リリースは、.github/workflows/workflow.yml の GitHub Trusted Publishing を通じて PyPI に公開されます。貢献についてはCONTRIBUTING.mdをご覧ください。

セキュリティ

ポリシーの回避は脆弱性として扱われます。詳細は SECURITY.md をご覧ください。

サポート

Linux、macOS、Windows は同等にサポートされています。ハードウェアのサポートはプローブとバックエンドに応じて異なります。OpenOCD または STM32CubeProgrammer 経由の ST-Link、pyOCD 経由の CMSIS-DAP、esptool 経由の ESP32 USB-UART ブリッジに対応しています。

平日は24時間以内に問題への返信があり、セキュリティに関する報告には7日以内に対応します。サポート範囲と対応内容の詳細については、サポートポリシーをご覧ください。

Discussions Q&Aで質問したり、Show and tellで実行結果を共有したり、成功・失敗を問わず初回実行レポートを送信したりできます。

ライセンス

Apache-2.0。LICENSEをご覧ください。