Declarative API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Dipublikasikan: 18 Mei 2026

Penjelasan Web Ekstensi Status Chrome Intent
GitHub Uji coba developer Uji coba developer Uji coba developer Uji coba developer View Niat untuk Bereksperimen

Gunakan Declarative API untuk mengubah formulir HTML standar menjadi alat WebMCP dengan menambahkan anotasi. Anotasi menentukan nama dan tujuan alat dalam elemen <form>, sementara kolom bertindak sebagai parameter alat. Browser menerjemahkan elemen ini menjadi representasi terstruktur yang dapat digunakan agen mirip dengan alat imperatif.

Sebelum menggunakan API ini, baca contoh kasus penggunaan.

Pendaftaran alat

Tambahkan atribut HTML berikut ke formulir Anda:

  • toolname: Beri nama alat dengan jelas, berdasarkan tujuannya.
  • tooldescription: Jelaskan tindakan yang dilakukan alat dan tujuannya.

Misalnya, formulir berikut berada di example.com/get-customer-support:

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

Saat agen memanggil toolname, browser akan memfokuskan formulir dan mengisi kolomnya. Formulir tetap terlihat oleh pengguna.

Jika Anda menghapus atribut HTML toolname atau tooldescription, alat akan dibatalkan pendaftarannya.

(Opsional) Parameter alat

Untuk meningkatkan akurasi, tambahkan atribut HTML berikut ke setiap elemen formulir:

  • toolparamdescription: Memetakan elemen ke deskripsi properti dalam Skema JSON. Tanpa atribut ini, browser menggunakan konten dalam <label> terkait dan melewati turunan yang dapat diberi label. Jika tidak ada label, browser akan merujuk ke aria-description.

Formulir berikut menggunakan parameter opsional untuk elemen <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>

Browser menafsirkan formulir ini sebagai alat, yang diwakili oleh JSON berikut:

[
  {
    "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"
      ]
    }
  }
]

Kirim formulir

Anda memiliki dua pilihan untuk pengiriman formulir:

  • Pengguna harus mengklik Kirim secara manual untuk menyelesaikan tugas.
  • Tambahkan toolautosubmit untuk memicu pengiriman dan perubahan navigasi.

Antarmuka SubmitEvent memperkenalkan atribut boolean agentInvoked. Atribut ini disetel ke benar (true) setiap kali formulir dipicu oleh agen AI, untuk menyesuaikan perilaku aplikasi web Anda secara khusus untuk interaksi berbasis agen.

Selain itu, SubmitEvent menyertakan metode respondWith(Promise<any>), sehingga Anda dapat meneruskan promise ke browser yang Anda selesaikan dengan hasil formulir. Nilai yang dihasilkan kemudian diserialisasi dan ditampilkan ke model sebagai output alat. Untuk menggunakan metode ini, Anda harus memanggil preventDefault() terlebih dahulu untuk menghentikan pengiriman formulir standar browser.

<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>

Browser memberi sinyal bahwa agen AI menjalankan alat dengan peristiwa "toolactivated". Peristiwa ini diaktifkan di jendela setelah kolom formulir diisi otomatis. Sebaliknya, jika pengguna membatalkan operasi agentik atau metode reset() dipanggil, peristiwa "toolcancel" akan dipicu. Kedua peristiwa ini tidak dapat dibatalkan dan menyediakan atribut toolName untuk identifikasi.

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.
});

Mengubah indikator fokus

Indikator fokus yang terlihat sangat penting untuk memberi tahu pengguna dan agen di mana mereka berada di halaman. Saat agen berhasil memanggil alat, memfokuskan formulir terkait, dan mengisi otomatis kolomnya, browser akan memicu pseudo-class CSS tertentu untuk memberikan masukan visual:

  • :tool-form-active diterapkan ke elemen form HTML alat.
  • :tool-submit-active diterapkan ke tombol kirim formulir, jika ada.

Class ini dinonaktifkan setelah formulir dikirimkan, agen membatalkan tindakan, atau pengguna mereset formulir. Anda dapat menyesuaikan CSS untuk status ini atau mengandalkan gaya browser default.

/* 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;
}

Pelajari lebih lanjut praktik terbaik dan gaya fokus.

Berinteraksi dan memberikan masukan

WebMCP sedang dalam tahap pembahasan aktif dan dapat berubah sewaktu-waktu. Jika Anda mencoba API ini dan memiliki masukan, kami ingin mendengarnya.