Formulir Agentic

Fitur web: Atribut WebMCP terkait formulir

Declarative API mengubah elemen <form> HTML standar menjadi alat WebMCP melalui atribut. Browser akan menyintesis Skema JSON dari input formulir dan menangani interaksi agen.

Formulir Sinyal Angular: JANGAN tambahkan toolname/tooldescription ke formulir yang dibuat dengan form() dari @angular/forms/signals. Sebagai gantinya, tambahkan provideExperimentalWebMcpForms() ke penyedia aplikasi dan teruskan opsi experimentalWebMcpTool: { name, description } ke form(). Angular kemudian mendaftarkan formulir melalui Imperative API, membangun skema dari model sinyal, dan menghubungkannya ke validasi dan pengiriman. Menggunakan kedua pendekatan tersebut akan mendaftarkan formulir yang sama dua kali.

Atribut Formulir

  • toolname: Nama unik untuk alat.
  • tooldescription: Fungsi alat dan kapan agen harus menggunakannya. Jangan cantumkan kolom, opsi, atau batas formulir: browser sudah menyertakannya dalam skema yang dibuatnya dari kontrol formulir.
  • toolautosubmit: (Opsional) Jika ada, agen dapat mengirimkan formulir tanpa menunggu interaksi pengguna.
  • toolparamdescription: (Opsional) Menyediakan cara untuk menentukan deskripsi properti dalam Skema JSON. Gunakan untuk menjelaskan arti nilai (misalnya, dengan nilai sampel), bukan untuk mengulangi opsi atau batas kontrol.
    • Urutan Resolusi: Browser menggunakan toolparamdescription jika ada. Jika tidak ada, elemen ini akan menggunakan textContent dari <label> terkait (melewati turunan yang dapat diberi label). Jika tidak ada label, label akan kembali ke aria-description.
    • Pengelompokan (Fieldset): Untuk melampirkan deskripsi ke grup elemen terkait (seperti tombol <input type="radio">), tempatkan toolparamdescription di elemen <fieldset> induk terdekat sehingga berlaku untuk grup parameter secara keseluruhan.

Contoh

<form toolname="search-cars" 
      tooldescription="Perform a car make/model search" 
      toolautosubmit>
  <label for="make">Vehicle Make</label>
  <input type="text" id="make" name="make" required>
  
  <label for="model">Vehicle Model</label>
  <input type="text" id="model" name="model" toolparamdescription="e.g., 330i, F-150" required>
  
  <button type="submit">Search</button>
</form>

Menangani Pengiriman di JavaScript

Saat agen mengirimkan formulir, SubmitEvent akan menyertakan agentInvoked (boolean) dan respondWith(promise).

document.querySelector('form').addEventListener('submit', (event) => {
  event.preventDefault();

  // Validate the form
  const formValidationErrors = myFormIsValid();

  if (formValidationErrors.length > 0) {
    if (event.agentInvoked) {
      const errorString =
        'Validation failed: ' +
        formValidationErrors
          .map((err) => `${err.field} (${err.message})`)
          .join(', ');

      event.respondWith(Promise.resolve(errorString));
    }
    return;
  }

  const resultPromise = performAsyncSearch(new FormData(event.target));

  // Return the result directly to the agent without navigation
  if (event.agentInvoked) {
    event.respondWith(resultPromise);
  }
});

Peristiwa Siklus Proses

document.modelContext memunculkan peristiwa saat agen mulai atau berhenti berinteraksi dengan alat: toolactivated diaktifkan saat eksekusi alat dimulai, dan toolcancel diaktifkan saat eksekusi alat dibatalkan.

// Starting in Chrome 156, these events are dispatched on `document.modelContext`.
// Older versions dispatch them on `window`. Feature-detect the event handler
// property to pick the right target for backward compatibility.
const targetFor = (type, listener, options) =>
  (`on${type}` in (document.modelContext ?? {}) ? document.modelContext : window)
    .addEventListener(type, listener, options);

targetFor('toolactivated', ({ toolName }) => {
  console.log(`Tool "${toolName}" started execution.`);
});

targetFor('toolcancel', ({ toolName }) => {
  console.log(`Tool "${toolName}" execution is cancelled.`);
});

Masukan Visual (CSS)

Gunakan pseudo-class untuk menandai formulir saat agen berinteraksi dengannya:

  • :tool-form-active: Diterapkan ke elemen <form> yang digunakan secara aktif oleh agen.
  • :tool-submit-active: Diterapkan ke tombol kirim saat browser dijeda untuk peninjauan pengguna (jika toolautosubmit dihilangkan).
form:tool-form-active {
  outline: 2px dashed blue;
  background-color: rgba(0, 0, 255, 0.05);
}

button:tool-submit-active {
  outline: 2px dashed red;
  animation: pulse 2s infinite;
}

Kesesuaian Formulir (Kapan Harus Dihindari)

Declarative API paling cocok untuk formulir standar yang mandiri. Pilihan ini tidak cocok dalam skenario berikut:

  • Kolom yang Sangat Bergantung: Formulir yang inputnya mengubah opsi atau visibilitas berdasarkan input lain. Skema yang disintesis tidak dapat mengekspresikan dependensi ini dengan baik.
  • Komponen UI Kustom: Formulir yang mengandalkan input non-standar (misalnya, kanvas, editor rich text) yang tidak melakukan serialisasi nilai secara otomatis.
  • Wizard Multi-Langkah: Alur kerja kompleks yang memerlukan beberapa pengiriman formulir. API Imperatif atau interaksi DOM standar lebih cocok di sini.

Kapan harus menggunakan toolautosubmit

  • Operasi & Kueri Hanya Baca: Penelusuran, filter, pengambilan detail, atau pemeriksaan status (misalnya, penelusuran model mobil, penelusuran direktori, pemeriksaan ketersediaan stok).
  • Tindakan Berisiko Rendah dan Dapat Dibatalkan: Tindakan formulir yang dapat dengan mudah diurungkan atau disesuaikan oleh pengguna secara manual (misalnya, menambahkan item ke keranjang, menerapkan kode kupon, menyimpan draf, atau menetapkan opsi tata letak sementara).

Kapan harus menghilangkan toolautosubmit

  • Tindakan Merusak atau Tidak Dapat Dibatalkan: Menghapus data, mereset konfigurasi sistem, atau menghapus database.
  • Tindakan Keuangan & Transaksional: Mengirimkan formulir checkout, mentransfer dana, mengizinkan pembayaran langganan, atau melakukan pemesanan akhir.
  • Komunikasi Pengguna Berdampak Tinggi: Mengirimkan lamaran pekerjaan akhir, mengirim email/pesan kepada pengguna sungguhan lainnya, atau memublikasikan konten yang ditampilkan kepada publik.
  • Setelan Akun Sensitif: Mengubah sandi, mengubah peran/izin pengguna, atau memperbarui info penagihan/profil.

Strategi penggantian

WebMCP Declarative API aman digunakan di semua browser. Browser yang tidak mendukung WebMCP akan mengabaikan atribut tool*, dan <form> akan terus berfungsi sebagai formulir HTML normal. Deteksi fitur tidak diperlukan.