Formularze agentowe

Funkcje internetowe: Atrybuty WebMCP powiązane z formularzem

Interfejs Declarative API przekształca standardowe elementy HTML <form> w narzędzia WebMCP za pomocą atrybutów. Przeglądarka syntetyzuje schemat JSON z danych wejściowych formularza i obsługuje interakcje agenta.

Formularze Angular Signal: NIE dodawaj toolname/tooldescription do formularzy utworzonych za pomocą form() z @angular/forms/signals. Zamiast tego dodaj provideExperimentalWebMcpForms() do dostawców aplikacji i przekaż opcję experimentalWebMcpTool: { name, description } do form(). Następnie Angular rejestruje formularz za pomocą interfejsu Imperative API, tworząc schemat na podstawie modelu sygnału i łącząc go z walidacją i przesyłaniem. Użycie obu metod spowoduje dwukrotne zarejestrowanie tego samego formularza.

Atrybuty formularza

  • toolname: unikalna nazwa narzędzia.
  • tooldescription: do czego służy narzędzie i kiedy agent powinien go używać. Nie podawaj pól, opcji ani limitów formularza: przeglądarka uwzględnia je już w schemacie, który tworzy na podstawie elementów sterujących formularza.
  • toolautosubmit: (opcjonalnie) jeśli jest obecny, agent może przesłać formularz bez czekania na interakcję użytkownika.
  • toolparamdescription: (opcjonalnie) umożliwia zdefiniowanie opisu właściwości w schemacie JSON. Użyj go, aby wyjaśnić, co oznacza wartość (np. za pomocą przykładowych wartości), a nie powtarzać opcje lub limity elementu sterującego.
    • Kolejność rozwiązywania: przeglądarka używa toolparamdescription, jeśli jest obecny. Jeśli nie ma tej wartości, używa textContent powiązanego elementu <label> (pomijając elementy podrzędne, które można oznaczyć etykietą). Jeśli nie ma etykiety, używana jest etykieta aria-description.
    • Grupowanie (zestawy pól): aby dołączyć opis do grupy powiązanych elementów (np. przycisków <input type="radio">), umieść toolparamdescription w najbliższym elemencie nadrzędnym <fieldset>, tak aby dotyczył całej grupy parametrów.

Przykład

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

Obsługa przesyłania w języku JavaScript

Gdy agent przesyła formularz, SubmitEvent zawiera agentInvoked (wartość logiczna) i 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);
  }
});

Zdarzenia cyklu życia

document.modelContext emituje zdarzenia, gdy agenty rozpoczynają lub kończą interakcję z narzędziem: toolactivated jest wywoływane, gdy rozpoczyna się wykonywanie narzędzia, a toolcancel – gdy zostaje ono anulowane.

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

Informacje wizualne (CSS)

Użyj pseudoklas, aby wyróżnić formularze, gdy agent wchodzi z nimi w interakcję:

  • :tool-form-active: stosowany do elementu <form> aktywnie używanego przez agenta.
  • :tool-submit-active: stosowany do przycisku przesyłania, gdy przeglądarka wstrzymuje działanie, aby użytkownik mógł sprawdzić dane (jeśli pominięto toolautosubmit).
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;
}

Zastosowanie formularza (kiedy go unikać)

Interfejs Declarative API najlepiej sprawdza się w przypadku samodzielnych, standardowych formularzy. Nie jest to dobry wybór w tych sytuacjach:

  • Pola silnie zależne: formularze, w których dane wejściowe zmieniają opcje lub widoczność na podstawie innych danych wejściowych. Zsyntetyzowany schemat nie może dobrze wyrazić tych zależności.
  • Niestandardowe komponenty interfejsu: formularze korzystające z niestandardowych danych wejściowych (np. canvas, edytory tekstu sformatowanego), które nie są automatycznie serializowane.
  • Wieloetapowe kreatory: złożone procesy wymagające przesłania wielu formularzy. W tym przypadku lepiej sprawdzi się interfejs API Imperative lub standardowa interakcja z DOM.

Kiedy używać parametru toolautosubmit

  • Operacje i zapytania tylko do odczytu: wyszukiwanie, filtrowanie, pobieranie szczegółów lub sprawdzanie stanu (np. wyszukiwanie modelu samochodu, wyszukiwanie w katalogu, sprawdzanie dostępności w magazynie).
  • Działania o niskim ryzyku, które można cofnąć: działania związane z formularzem, które użytkownik może łatwo cofnąć lub poprawić ręcznie (np. dodanie produktów do koszyka, zastosowanie kodu kuponu, zapisanie wersji roboczej lub ustawienie tymczasowych opcji układu).

Kiedy pominąć parametr toolautosubmit

  • Działania destrukcyjne lub nieodwracalne: usuwanie rekordów, resetowanie konfiguracji systemu lub czyszczenie baz danych.
  • Działania finansowe i transakcyjne: przesłanie formularza płatności, przelanie środków, autoryzowanie płatności za subskrypcję lub złożenie zamówienia.
  • Komunikacja z użytkownikami o dużym wpływie: przesyłanie ostatecznego podania o pracę, wysyłanie e-maili lub wiadomości do innych prawdziwych użytkowników albo publikowanie treści publicznych.
  • Ustawienia konta związane z poufnymi danymi: zmiana haseł, modyfikowanie ról lub uprawnień użytkowników albo aktualizowanie informacji rozliczeniowych lub informacji na profilu.

Strategie zastępcze

Interfejs WebMCP Declarative API jest bezpieczny we wszystkich przeglądarkach. Przeglądarki, które nie obsługują WebMCP, będą ignorować atrybuty tool*, a <form> będzie nadal działać jako normalny formularz HTML. Nie jest wymagane wykrywanie funkcji.