Agentische Formulare

Die Declarative API wandelt standardmäßige HTML-<form>-Elemente über Attribute in WebMCP-Tools um. Der Browser synthetisiert ein JSON-Schema aus den Formulareingaben und verarbeitet die Interaktionen des KI-Agenten.

Angular Signal Forms: Fügen Sie KEINE toolname/tooldescription zu Formularen hinzu, die mit form() aus @angular/forms/signals erstellt wurden. Fügen Sie stattdessen provideExperimentalWebMcpForms() zu den App-Anbietern hinzu und übergeben Sie die Option experimentalWebMcpTool: { name, description } an form(). Angular registriert das Formular dann über die imperative API, erstellt das Schema aus dem Signalmodell und verknüpft es mit der Validierung und dem Senden. Wenn Sie beide Ansätze verwenden, wird dasselbe Formular zweimal registriert.

Formularattribute

• toolname: Eindeutiger Name für das Tool.
• tooldescription: Was das Tool tut und wann ein Agent es verwenden sollte. Listen Sie die Felder, Optionen oder Einschränkungen des Formulars nicht auf. Der Browser fügt sie bereits in das Schema ein, das er aus den Formularsteuerelementen erstellt.
• toolautosubmit: (Optional) Wenn vorhanden, kann der Agent das Formular senden, ohne auf eine Nutzerinteraktion zu warten.
• toolparamdescription: (Optional) Ermöglicht die Definition einer Attributbeschreibung im JSON-Schema. Erläutern Sie damit, was der Wert bedeutet (z. B. mit Beispielwerten), anstatt die Optionen oder Limits des Steuerelements zu wiederholen.
  • Auflösungsreihenfolge: Der Browser verwendet toolparamdescription, falls vorhanden. Wenn dieser nicht vorhanden ist, wird der textContent des zugehörigen <label> verwendet (untergeordnete Elemente, die mit Labels versehen werden können, werden übersprungen). Wenn kein Label vorhanden ist, wird auf die aria-description zurückgegriffen.
  • Gruppierung (Fieldsets): Wenn Sie einer Gruppe zusammengehöriger Elemente (z. B. <input type="radio">-Buttons) eine Beschreibung hinzufügen möchten, platzieren Sie toolparamdescription im nächstgelegenen übergeordneten <fieldset>-Element, damit sie für die gesamte Parametergruppe gilt.

Beispiel

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

Einreichungen in JavaScript verarbeiten

Wenn ein Agent das Formular einreicht, enthält die SubmitEvent agentInvoked (boolescher Wert) und 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);
  }
});

Lifecycle-Events

document.modelContext gibt Ereignisse aus, wenn Agenten mit einem Tool interagieren oder die Interaktion beenden: toolactivated wird ausgelöst, wenn die Toolausführung beginnt, und toolcancel, wenn sie abgebrochen wird.

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

Visuelles Feedback (CSS)

Verwenden Sie Pseudoklassen, um Formulare hervorzuheben, wenn ein Agent mit ihnen interagiert:

• :tool-form-active: Wird auf das <form>-Element angewendet, das vom Agenten aktiv verwendet wird.
• :tool-submit-active: Wird auf die Schaltfläche „Senden“ angewendet, wenn der Browser für die Überprüfung durch den Nutzer pausiert (wenn toolautosubmit weggelassen wird).

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

Eignung von Formularen (wann sie vermieden werden sollten)

Die Declarative API eignet sich am besten für eigenständige Standardformulare. In den folgenden Szenarien ist es eine schlechte Wahl:

• Stark abhängige Felder: Formulare, bei denen sich die Optionen oder die Sichtbarkeit von Eingaben je nach anderen Eingaben ändern. Das synthetisierte Schema kann diese Abhängigkeiten nicht gut darstellen.
• Benutzerdefinierte UI-Komponenten: Formulare, die auf nicht standardmäßigen Eingaben basieren (z.B. Canvas, Rich-Text-Editoren), bei denen Werte nicht automatisch serialisiert werden.
• Mehrstufige Assistenten: Komplexe Workflows, die mehrere Formulareinreichungen erfordern. Die imperative API oder die Standard-DOM-Interaktion ist hier besser geeignet.

Wann „toolautosubmit“ verwendet werden sollte

• Schreibgeschützte Vorgänge und Abfragen: Suchen, Filtern, Abrufen von Details oder Prüfen des Status (z.B. Suche nach einem Automodell, Suche in einem Verzeichnis, Prüfen der Verfügbarkeit von Artikeln).
• Aktionen mit geringem Risiko, die rückgängig gemacht werden können: Formularaktionen, die vom Nutzer leicht manuell rückgängig gemacht oder angepasst werden können (z.B. Artikel in den Einkaufswagen legen, Gutscheincode anwenden, Entwurf speichern oder temporäre Layoutoptionen festlegen).

Wann „toolautosubmit“ weggelassen werden sollte

• Destruktive oder irreversible Aktionen: Löschen von Datensätzen, Zurücksetzen von Systemkonfigurationen oder Löschen von Datenbanken.
• Finanz- und Transaktionsaktionen: Einreichen eines Bezahlformulars, Überweisen von Geld, Autorisieren von Abozahlungen oder endgültige Bestellungen.
• Nutzerkommunikation mit hoher Wirkung: Einreichen einer endgültigen Bewerbung, Senden von E‑Mails/Nachrichten an andere echte Nutzer oder Veröffentlichen von öffentlich zugänglichen Inhalten.
• Sensible Kontoeinstellungen: Ändern von Passwörtern, Ändern von Nutzerrollen/-berechtigungen oder Aktualisieren von Zahlungs-/Profilinformationen.

Fallback-Strategien

Die deklarative WebMCP API kann in allen Browsern sicher verwendet werden. Browser, die WebMCP nicht unterstützen, ignorieren die tool*-Attribute und das <form>-Element funktioniert weiterhin als normales HTML-Formular. Es ist keine Featureerkennung erforderlich.