PREFLIGHT — URL Routing for AI Agents

PREFLIGHT

AI エージェントが URL にアクセスする前に、最適なアクセス方法を確認しましょう。

PREFLIGHT は、ブラウザー、調査、ショッピングの各エージェント向けのルーティングインテリジェンスです。URL を指定すると、最初に試すべき最も低コストと思われるルートとして、HTTP、BROWSER、MACHINE_ENDPOINT、AVOID のいずれかを推奨します。

長期的な目標は、ウェブのマシンマップです。ウェブ上に「何があるか」ではなく、「マシンはこのアクセス先とどのようにやり取りすべきか」を示します。

ライブサービス

ベース URL：

https://preflight-api-production-01a2.up.railway.app

REST — エージェントがこれからアクセスする実際の URLを使用してください：

GET /v1/check?url=<encoded-actual-destination-url>

たとえば、エージェントが商品、ドキュメントページ、記事、予約ページ、SaaS サイトを調べる場合は、まず実際のアクセス先を PREFLIGHT に渡してください。example.com はドキュメント上のプレースホルダーにすぎません。実際のタスク URL がある場合は使用しないでください。

リモート MCP：

https://preflight-api-production-01a2.up.railway.app/mcp

MCP サーバーは 2 つのツールを公開します：

• preflight_check — 見慣れない実際の URL を取得またはブラウザーでレンダリングする前に呼び出します。
• preflight_feedback — 選択したルートが機能したかどうかを報告し、PREFLIGHT が今後の推奨を改善できるようにします。

ツールの使用例：

現在のタスクに含まれる URL を開く前に、PREFLIGHT を使用して、通常の HTTP、ブラウザー、機械可読エンドポイント、アクセス回避のどれを最初に試すのが最適か判断してください。

エージェントが PREFLIGHT を呼び出す理由

最初に取得すると、無駄が生じる場合があります。アクセス先は、HTTP で直接読み取れる場合もあれば、ブラウザーでのレンダリングが必要な場合、より小さな機械向けエンドポイントを公開している場合、自動化をブロックしている場合、認証や支払いが必要な場合、取得が望ましくないことを示すアクセスシグナルがある場合もあります。PREFLIGHT は、コストのかかる処理に進む前に、このルーティングの判断を支援します。

レスポンスには、直接プローブのシグナル、キャッシュされたドメイン知識、十分に強い観測済みルートフィードバックが組み合わされます。ステータス、リダイレクト、robots／アクセスに関するヒント、推定トークンサイズ、JavaScript シェルのヒント、構造化データのシグナル、機械向けエンドポイント、レイテンシー、信頼度、キャッシュの経過時間、学習済みルートのエビデンスなどが含まれる場合があります。

フィードバックループ

POST /v1/feedback
Content-Type: application/json
Authorization: Bearer <feedback-key>   # when protection is enabled

{
  "url": "https://merchant.example/product/123",
  "route": "BROWSER",
  "outcome": "success",
  "latencyMs": 840
}

PREFLIGHT は、ページのコンテンツやユーザー ID ではなく、集約した成功／失敗のエビデンスを保存します。URL 単位の学習には、成功率 80% 以上で少なくとも 5 件のサンプルが必要です。ドメイン単位の学習には、成功率 85% 以上で少なくとも 10 件のサンプルが必要です。フィードバックが、ライブの安全性／アクセス／robots のシグナルによる現在の AVOID 判断を覆すことはありません。

エージェントによる検出

• AGENTS.md は、PREFLIGHT をいつ使うべきかをコーディングエージェント／AI エージェントに明確に伝えます。
• llms.txt は、LLM 向けに簡潔な機械可読の説明、ライブエンドポイント、使用ルールを提供します。
• openapi.json は、ツールインポーターや生成クライアント向けに、OpenAPI 3.1 形式で REST 操作を公開します。
• mcp.json には、汎用リモート MCP クライアントの設定が含まれます。
• docs/AGENT-INTEGRATIONS.md には、ブラウザー、調査、ショッピング、コーディング、MCP、REST の各エージェント向けに、コピーして貼り付けて使える統合パターンが含まれます。
• server.json には、公開 Streamable HTTP サーバーの公式 MCP Registry メタデータが含まれます。
• /mcp は、MCP の initialize、initialized 通知、ping、tools/list、tools/call をサポートします。
• MCP を使用しないクライアントでも、通常の REST エンドポイントを引き続き利用できます。

検索／検出の概念：AI エージェントの URL ルーティング、ブラウザーエージェントの事前チェック、HTTP とブラウザーの選択、機械可読エンドポイントの検出、エージェントのブラウジングトークンを削減、エージェントのウェブルーティング、取得前のルーティングインテリジェンス、AI ブラウザーのコスト削減、クロール前のルーティング、エージェント向け URL アクセスインテリジェンス。

公開デプロイ

GET /ready は、データディレクトリに書き込み可能かどうかを確認します。Railway のデプロイでは /data を使用します。フィードバックを長期保存する必要がある場合は、ここに永続ボリュームをマウントしてください。PREFLIGHT_FEEDBACK_KEY を設定すると、ルートチェックを公開したまま、フィードバックの書き込みをベアラートークンで保護できます。npm run smoke:live は、公開ルート／フィードバックの一連の処理をテストします。

実環境ベンチマーク

benchmarks/sites.json には、カテゴリ横断型のライブコーパスが含まれています。npm run benchmark を実行してください。定期ベンチマークでは、ルート、ステータス、レイテンシ、トークンの推定値、マシンのエンドポイントが記録され、傾向分析用の機械可読レポートが保存されます。

安全性の境界

PREFLIGHT は、localhost、プライベート／リンクローカルネットワークアドレス、認証情報を含む URL、HTTP 以外のプロトコル、安全でないリダイレクト先をブロックします。エンドポイントの検出とネゴシエーションプローブは、同じ SSRF 対策済みのフェッチ層を経由します。MCP はブラウザーの Origin を検証し、ルートフィードバックによって有効な AVOID の結果が緩和されることはありません。

ローカルで実行する

Node.js 20 以降が必要です。

npm test
npm start

製品の境界

PREFLIGHT は、クローラー、ブラウザーファーム、検索エンジン、サイト所有者向けの監査ツールではありません。その役割は、より限定的です。

実際の URL を入力 → 最も低コストで信頼できるマシン向けルートを出力。