宣言型 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="supportRequestTool" tooldescription="Submit a request for 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 toolparamtitle="Support type" 
    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": {
        "text": {
          "type": "string",
          "title": "firstName",
          "description": "First name"
        },
        "text": {
          "type": "string",
          "title": "lastName",
          "description": "Last name"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "title": "Support type",
          "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>

ブラウザは、AI エージェントが "toolactivated" イベントでツールを実行したことを通知します。これは、フォーム フィールドが事前入力されるとウィンドウで発生します。逆に、ユーザーがエージェント操作をキャンセルした場合、または 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 をお試しになり、フィードバックをお寄せください。