宣言型 API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky
François Beaufort
François Beaufort
GitHub

公開日: 2026 年 5 月 18 日

商品の解説 ウェブ 拡張機能 Chrome ステータス インテント
GitHub オリジン トライアル オリジン トライアル 表示 テストの目的

Declarative API を使用して、アノテーションを追加することで標準の HTML フォームを WebMCP ツールに変換します。アノテーションは、<form> 要素でツールの名前と目的を定義し、フィールドはツール パラメータとして機能します。ブラウザはこれらの要素を、エージェントが命令型ツールと同様に使用できる構造化された表現に変換します。

この API を使用する前に、ユースケースの例をご覧ください。

ツールの登録

フォームに次の HTML 属性を追加します。

  • toolname: ツールをその目的に基づいて明確に命名します。
  • tooldescription: ツールが実行するアクションとその目的を説明します。

たとえば、次のフォームは example.com/get-customer-support にあります。

<form toolname="createSupportRequest" tooldescription="Submits a request for customer support.">
</form>

エージェントが toolname を呼び出すと、ブラウザはフォームにフォーカスを当て、そのフィールドに入力します。フォームはユーザーに表示されたままになります。

toolname または tooldescription HTML 属性のいずれかを削除すると、ツールは登録解除されます。

（省略可）ツールのパラメータ

精度を高めるには、個々のフォーム要素に次の HTML 属性を追加します。

  • toolparamdescription: JSON スキーマ内のプロパティの説明に要素をマッピングします。この属性がない場合、ブラウザは関連付けられた <label> 内のコンテンツを使用し、ラベル付け可能な子孫をスキップします。ラベルがない場合、ブラウザは aria-description を参照します。

次のフォームでは、<select> 要素の省略可能なパラメータを使用しています。

<form toolname="supportRequestTool"
  tooldescription="Submit a request for support."
  action="/submit">

  <label for="firstName">First Name</label>
  <input type=text name=firstName>

  <label for="lastName">Last Name</label>
  <input type=text name=lastName>

  <select name="select" required 
    toolparamdescription="Determines what team this request is routed to.">
    <option value="Customer happiness team">Return my purchase.</option>
    <option value="Distribution team">Check where my package is.</option>
    <option value="Website support team">Get help on the website.</option>
  </select>

  <button type=submit>Submit</button>
</form>

ブラウザはこのフォームをツールとして解釈し、次の JSON で表します。

[
  {
    "name": "supportRequestTool",
    "description": "Submit a request for support.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "firstName": {
          "type": "string"
        },
        "lastName": {
          "type": "string"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "type": "string",
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "type": "string",
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "type": "string",
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "description": "Determines what team this request is routed to."
        }
      },
      "required": [
        "select"
      ]
    }
  }
]

フォームを送信

フォームの送信には次の 2 つの方法があります。

  • タスクを完了するには、[送信] を手動でクリックする必要があります。
  • モデルがこのツールを呼び出したときに送信とナビゲーションをトリガーする toolautosubmit を追加します。

SubmitEvent インターフェースは、agentInvoked ブール値属性を導入します。この属性は、AI エージェントによってフォームがトリガーされるたびに true に設定され、エージェントベースのインタラクションに合わせてウェブアプリの動作を調整します。

また、SubmitEvent には respondWith(Promise<any>) メソッドが含まれているため、フォームの結果で解決する Promise をブラウザに渡すことができます。結果の値はシリアル化され、ツールの出力としてモデルに返されます。このメソッドを使用するには、まず preventDefault() を呼び出して、ブラウザの標準のフォーム送信を停止する必要があります。

<form toolautosubmit toolname="search_tool"
  tooldescription="Search the web" action="/search">
  <input type=text name=query>
</form>
<script>
  document.querySelector("form").addEventListener("submit", (e) => {
    e.preventDefault();
    if (!myFormIsValid()) {
      if (e.agentInvoked) { e.respondWith(myFormValidationErrorPromise) };
      return;
    }
    if (e.agentInvoked) { e.respondWith(Promise.resolve("Search is done!")); }
  });
</script>

ブラウザは、"toolactivated" イベントで AI エージェントがツールを実行したことを通知します。これは、フォーム フィールドが事前入力されるとウィンドウで発生します。逆に、ユーザーがエージェント操作をキャンセルするか、reset() メソッドが呼び出されると、"toolcancel" イベントがトリガーされます。これらのイベントはどちらもキャンセルできず、識別用の toolName 属性を提供します。

window.addEventListener('toolactivated', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was activated.`);
  // TODO: Update UI or validate form if needed.
});

window.addEventListener('toolcancel', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was cancelled.`);
  // TODO: Let the user know. Update UI.
});

フォーカス インジケータを変更する

ユーザーとエージェントにページ上の現在位置を知らせるには、フォーカス インジケーターを表示することが重要です。エージェントがツールを正常に呼び出し、関連するフォームにフォーカスして、そのフィールドに自動入力すると、ブラウザは特定の CSS 疑似クラスをトリガーして視覚的なフィードバックを提供します。

  • :tool-form-active はツールの HTML form 要素に適用されます。
  • :tool-submit-active は、フォームの送信ボタン（存在する場合）に適用されます。

これらのクラスは、フォームが送信されたとき、エージェントがアクションをキャンセルしたとき、またはユーザーがフォームをリセットしたときに無効になります。これらの状態の CSS をカスタマイズすることも、デフォルトのブラウザ スタイルを使用することもできます。

/* Chrome default declarative form styles. */
form:tool-form-active {
  outline: light-dark(blue, cyan) dashed 1px;
  outline-offset: -1px;
}

input:tool-submit-active {
  outline: light-dark(red, pink) dashed 1px;
  outline-offset: -1px;
}

詳しくは、フォーカスのベスト プラクティスとスタイルをご覧ください。

意見交換とフィードバックの提供

WebMCP は現在活発な議論が行われており、今後変更される可能性があります。この API をお試しになり、フィードバックがございましたら、ぜひお聞かせください。