宣言型 API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

公開日: 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 をお試しになり、フィードバックがございましたら、ぜひお聞かせください。