Practonaut

Practonaut

実際のアプリを使った、AI エージェント向けのローカル練習場です。 タスクを一度実演すれば、あらゆる MCP エージェントが練習でき、独立した再現可能なスコアを取得できます。npx コマンドを 1 つ実行するだけで、VM も Docker も不要です。

Practonaut は、実際のアプリケーション（現在は Excalidraw）を練習環境に変えます。タスクは開始時の図と目標で構成されます。あなた自身、または MCP 経由のエージェントが、図を一つずつ操作します。各操作は実際の固定バージョンの Excalidraw エンジンに適用され、完了としてカウントされる前に読み戻されます。試行が終わると、独立したチェッカーが目標の達成状況を判定します。人とエージェントは同じセッションで同時に作業できるため、ブラウザーでエージェントの作業を見守れます。履歴では、変更が自分によるものかエージェントによるものかが表示されます（Agent · claude-code）。

60 秒で始める

Node.js 22.18 以降が必要です（macOS、Linux、Windows）。

npx practonaut                 # opens the example task in your browser at once
npx practonaut setup           # once: the Chromium headless shell for the real Excalidraw engine (about 105–130 MB)

Player でデモを見ると、サンプルタスクを一度解決します。操作がボードに反映されるたびに、実際の Excalidraw が確認し、最後に結果チェックが判定します。これはあなたの結果ではありません。Stop または Escape で終了できます。setup の前はすべてモデルのみで動作します。操作は実際のアプリでは確認されず、その旨とダウンロード先を示すバナーが表示されます。

エージェントに練習させます（Claude Code の例です。どの MCP クライアントでも動作します）。

claude mcp add practonaut -- npx -y practonaut mcp --task excalidraw/connect

ネイティブ Windows（WSL ではない環境）では、npx は .cmd ファイルであり、MCP クライアントから直接起動できません。先頭に cmd /c を追加してください：claude mcp add practonaut -- cmd /c npx -y practonaut mcp --task excalidraw/connect

タスクのスコアを取得します。実行ごとに新しいセッションを使用し、独立したチェックを行います。

npx practonaut bench --agent claude-code --tasks excalidraw/connect

詳しくはスタートガイドをご覧ください。

独自のタスクを作成する

Excalidraw で開始時の図と目標を描いてから、次のコマンドを実行します。

npx practonaut tasks from-scenes start.excalidraw goal.excalidraw --out my-task
npx practonaut play my-task/world

差分が目標になります（手順、ラベル、図形、色、フレーム、グループ、矢印）。Practonaut は、目標が独自のチェックに合格し、開始時の図が不合格となり、生成された参照解が合格し、生成されたニアミスが不合格になる場合にのみタスクを保存します。Player の Create でも同じ操作ができます。ここでは実際のエディターでデモを記録し、2 回目の記録でルールを確認することもできます。タスク作成ガイドをご覧ください。

エージェントをベンチマークする

npx practonaut bench --agent oracle --tasks all --seeds 2            # reference solutions: the score's ceiling
npx practonaut bench --agent random --tasks all --max-actions 30       # random actions: the floor
npx practonaut bench --agent claude-code --tasks excalidraw/insert-between --repeats 3
npx practonaut bench --agent "my-agent --mcp {mcp_config} --prompt {prompt}"   # any agent
npx practonaut bench --agent claude-code --world my-task/world --oracle my-task/oracle.json   # your own task
npx practonaut report ~/.practonaut/bench/<id>/report.json --html report.html
npx practonaut report ~/.practonaut/bench/<id>/report.json --verify     # re-judge from the run files
npx practonaut compare before/report.json after/report.json --fail-on-regression   # did a change break an instance?
npx practonaut report ~/.practonaut/bench/<id>/report.json --junit runs.xml --card card --badge badge.svg

実行ごとに専用のセッションとデータフォルダーが用意され、エージェントは Practonaut MCP ツールを通してのみセッションにアクセスします。また、人に提示されるものと同じ公開タスクを受け取ります。claude-code プリセットは、環境にあるプロバイダーキー、トークン、課金設定を Claude Code に渡しません（ANTHROPIC_API_KEY が設定されていると、API 課金にひそかに切り替わります）。そのため、Claude Code はログイン済みのアカウントを使用します。サブスクリプションでログインしている場合は、そのサブスクリプションが使われます。キーを意図的に渡すには、--keep-env ANTHROPIC_API_KEY を指定します。スコアはホストの履歴と独立したチェッカーに基づき、エージェントの発言内容には基づきません。指標は pass@1、pass^k、アクション数、参照解に対する効率です。JSON レポートにはスキーマがあります。report は、すべての合格判定と数値がファイル内の判定結果に基づいているかを確認します。これは整合性の確認であり、証明ではありません。ファイルを整合するように編集すれば、やはり検証に通ります。report には「整合性を確認済み。再検証はしていません」と表示されます。report --verify は、ベンチマークフォルダーに保存されたセッションと実アプリのエクスポートを使ってチェッカーを再実行します。レポートにはそのエクスポートの SHA-256 が記録されます。フォルダー内に保存されたワールドと参照解を基に検証するため、フォルダーを移動しても検証できます。また、各実行のアクション数と参照解の長さを再導出し、差異があれば項目名とともに拒否します。ホスト呼び出しと所要時間は、ランナーから報告された値として記録されます。署名はありません。ベンチマークフォルダーに書き込める人は、これらのファイルも置き換えられます。

レポートには、実行が失敗したことだけでなく、その理由も記載されます。割合は 95 % 区間とともに分数で示され、失敗した実行が先に並びます。未達成の各目標条件について、最後に失われたアクションが示されます（チェッカーは各アクションの後に判定します）。エラークラスとその説明、軌跡、最終盤面（実際の Excalidraw 自身のエクスポート、または模式図であることを明記した図）、目標の例、呼び出しログ、そしてクライアントが自己申告するトークン数、ターン数、コストも掲載されます。compare は 2 つのレポートをインスタンスごとに並べて比較します。比較できないレポートは拒否し、インスタンスごとの性能低下（前は 3 回すべて成功、後はすべて失敗）を特定します。正確な McNemar 検定で 2 つを区別できない場合は、「この n では区別できません」と表示します。両方のレポートは、同じ種類のエージェントから生成されたものでなければなりません。oracle と random はスコアの両端を示し、比較対象は組み込みのものに限られます。コマンドテンプレートは、コマンドテンプレートとのみ比較できます。エージェントのベースラインとしては、信頼できるそのエージェントの設定をベンチマークしてください。

CI では、examples/ci/practonaut-bench.yml が独自の認証情報でエージェントをベンチマークし、コミット済みのベースラインと比べていずれかのインスタンスで性能低下があればジョブを失敗させます。--junit を指定すると、CI のテスト表示用に実行ごとに 1 件のテストケースを出力します。--card と --badge は、ヘッダー行を 1280 × 640 のカード（SVG と PNG、ライトとダーク）およびバッジに描画します。カードとバッジには、n、区間、検証ステータス、分離レベルが表示されます。

レポートの例は、Claude Code で 3 つのタスクをそれぞれ 2 回実行した実際の結果です （JSON、HTML）。シードは 1 つ、実行は 6 回です。形式の例を示すものであり、モデルの順位付けではありません。詳細： ベンチマーク。

タスクライブラリ

チャレンジレベルではなく、ライブラリです。 これらのタスクはサンプルセットであり、共通のスモークテストです。能力を測るものではありません。現在の Claude モデルはこれらを解けます。また、より難しい候補となる 5 つのファミリーを試しましたが、Practonaut 自体のアクションでは 0.2.0 において改善の余地が見つかりませんでした（ゲートレポート）。事前登録された段階的なゲートに合格したファミリーのみが、チャレンジレベルになります。

Excalidraw 0.18.1 向けの 16 個のタスクがあり、それぞれ英語とドイツ語、3 種類のラベルバリエーション、参照解答、惜しい誤答が用意されています。npx practonaut tasks list で一覧を表示し、npx practonaut play <task> でタスクを開きます。mcp と bench では excalidraw/<task> として指定します。

タスク	レベル	参照アクション数	目標
add-step	●○○	1	ステップを追加する
connect	●○○	1	2 つのステップを接続する
disconnect	●○○	1	近道の矢印を削除する
recolor	●○○	1	エラーのステップに印を付ける
remove-step	●○○	1	ステップを削除する
rename-frame	●○○	1	フレームに名前を付ける
rename-step	●○○	1	ラベルを修正する
align	●●○	3	1 行に整列させる
close-chain	●●○	1	チェーンの隙間を埋める
group	●●○	2	サブプロセスをグループ化する
insert-between	●●○	4	2 つのステップの間にステップを挿入する
reconnect	●●○	1	矢印をつなぎ直す
reorder	●●○	4	ステップを順番に並べる
decision	●●●	6	2 つの出口を持つ判断を作成する
restyle-flow	●●●	6	リストをスタイル付きのフローに変える
two-frames	●●●	4	2 つのサブプロセスをフレームに分ける

スコアリングの仕組み

1. ホストが履歴を保持します。 すべてのアクションは 1 つのセッションホストを経由します。ホストは各アクションを状態ハッシュと実行者とともに記録します。エージェントも人も、それ以外の方法で状態を書き換えることはできません。
2. 実際のエンジンが各アクションを確認します。 Chromium がインストールされている場合、各アクションはヘッドレスで実行中の固定バージョンの Excalidraw に適用され、その結果が読み戻されます。実際のアプリが認めないアクションは拒否されます。
3. 別のチェッカーが判定します。 試行後、別のプロセスが独自のインタープリターで履歴を再生し、独自のパーサーで実際の Excalidraw のエクスポートを読み込み、目標を評価します。まず、空の提出、変更のない提出、誤った提出がすべて失敗することを確認します。

エージェントには、Player を使う人と同じタスクと、同じ公開目標条件が与えられます。各条件は 1 文と、その条件を明示した目標述語である形式表現で示され、同じ Check ボタンも使えます。エージェントは GUI ではなく、MCP 経由で Practonaut のセマンティックアクションを実行します。参照解答、惜しい誤答、保留されたチェッカーデータが MCP 経由でエージェントに渡されることはありません。

制限事項

• アプリケーションは 1 つです。 現時点では Excalidraw 0.18.1 のみです。アダプターの契約は、より多くのアプリケーションに対応することを想定しています（アダプターガイド）。まだほかのアプリケーションはありません。
• ピクセルではなく、セマンティックアクションです。 エージェントは画面をクリックするのではなく、Practonaut のアクション（ステップの追加、接続、名前の変更など）を実行します。これはアプリのモデル上で目標を達成できるかを測るものであり、GUI を操作できるかを測るものではありません。
• 問題が漏れないよう保護されてはいません。 エージェントは OS のユーザーとして実行されます。独自のファイルツールやシェルツールを持つエージェントは、参照解答を含むタスクライブラリをディスク上で読み取れる可能性があります。claude-code プリセットでは Practonaut のツールのみが許可されますが、ほかのエージェントについてはご自身で設定してください。
• 現時点の証拠は限られています。 サンプルレポートには、各タスクにつき 2 回分の実行結果が含まれています。ここで練習すると実際のツールの使用が上達するかどうかは、まだ研究されていません。
• Chromium がない場合、Practonaut はモデルのみで実行されます。タスクは動作しますが、実際のアプリとの照合は行われず、その旨が表示されます。
• 人によるスクリーンリーダーと 200 % ズームの確認は、現時点で 1 回のみです（2026-10-17、Chrome を使用した macOS の VoiceOver）。問題は見つかりませんでしたが、ほかのスクリーンリーダーと、普段からスクリーンリーダーを使用する人については、まだテストされていません（手動チェック）。

要件

• Node.js ≥ 22.18 と npm。
• 任意：npx practonaut setup を実行すると、実際のエンジンで使用する Playwright の Chromium ヘッドレスシェルが一度だけダウンロードされます。インストール時にダウンロードされるものはなく、このパッケージにはインストールスクリプトがありません。
• ローカルデータは ~/.practonaut（または PRACTONAUT_HOME）に保存されます。テレメトリーもアカウントもありません。Practonaut 自体のプロセスは練習中にネットワーク呼び出しを行いません（npx によるパッケージの取得と、setup による Chromium の取得はそれぞれ一度だけです）。接続したエージェントは、そのエージェント自身のモデルプロバイダーと通信します。

ドキュメント

はじめに · エージェントガイド · ベンチマーク · 作成ガイド · ワールド形式 · アーキテクチャ · アダプターガイド · セッションホスト · 脅威モデル · 用語集 · すべてのドキュメント

コントリビューション

イシューやプルリクエストを歓迎します。新しいタスク、バグ修正、そして特に2つ目のアプリケーションアダプターをお待ちしています。まずは CONTRIBUTING.md をご覧ください。セットアップは3つのコマンドで完了します。セキュリティに関する報告は SECURITY.md からお寄せください。

ライセンス

Apache License 2.0。NOTICE もご覧ください。同梱の Excalidraw エンジンとフォントには、それぞれ独自のライセンスがあります（パッケージに同梱されています）。サンプルワールドとタスクライブラリは CC0-1.0 です。