Agentische formulieren

Webfuncties: Aan formulieren gekoppelde WebMCP-kenmerken

De Declarative API transformeert standaard HTML-elementen van <form> naar WebMCP-tools via kenmerken. De browser synthetiseert een json-schema op basis van de formulierinvoer en verwerkt de interacties van de agent.

Angular Signal Forms: Voeg GEEN toolname/tooldescription toe aan formulieren die zijn gemaakt met form() van @angular/forms/signals. Voeg in plaats daarvan provideExperimentalWebMcpForms() toe aan de app-providers en geef de optie experimentalWebMcpTool: { name, description } door aan form(). Angular registreert het formulier dan via de Imperative API, maakt het schema op basis van het signaalmodel en koppelt het aan validatie en indiening. Als u beide benaderingen gebruikt, wordt hetzelfde formulier 2 keer geregistreerd.

Formulierkenmerken

  • toolname: Unieke naam voor de tool.
  • tooldescription: Wat de tool doet en wanneer een agent deze moet gebruiken. Vermeld de velden, opties of limieten van het formulier niet: de browser neemt deze al op in het schema dat wordt gemaakt op basis van de formulierbesturingselementen.
  • toolautosubmit: (Optioneel) Als dit aanwezig is, kan de agent het formulier indienen zonder te wachten op gebruikersinteractie.
  • toolparamdescription: (Optioneel) Biedt een manier om een propertybeschrijving te definiëren in het json-schema. Gebruik deze om uit te leggen wat de waarde betekent (bijvoorbeeld met voorbeeldwaarden), niet om de opties of limieten van de bedieningselementen te herhalen.
    • Oplossingsvolgorde: De browser gebruikt toolparamdescription indien aanwezig. Als deze ontbreekt, wordt de textContent van de bijbehorende <label> gebruikt (onderliggende items die kunnen worden gelabeld, worden overgeslagen). Als er geen label bestaat, wordt teruggevallen op de aria-description.
    • Groepering (Fieldsets): Als je een beschrijving wilt toevoegen aan een groep gerelateerde elementen (zoals <input type="radio">-knoppen), plaats je toolparamdescription op het dichtstbijzijnde bovenliggende <fieldset>-element, zodat deze van toepassing is op de parametergroep als geheel.

Voorbeeld

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

Inzendingen verwerken in JavaScript

Als een medewerker het formulier indient, bevat de SubmitEvent agentInvoked (boolean) en 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);
  }
});

Levenscyclusgebeurtenissen

document.modelContext stuurt gebeurtenissen wanneer agents interactie met een tool starten of stoppen: toolactivated wordt geactiveerd wanneer de uitvoering van de tool start en toolcancel wordt geactiveerd wanneer deze wordt geannuleerd.

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

Visuele feedback (CSS)

Gebruik pseudoklassen om formulieren te markeren wanneer een agent er interactie mee heeft:

  • :tool-form-active: Toegepast op het <form>-element dat actief wordt gebruikt door de agent.
  • :tool-submit-active: Wordt toegepast op de knop Verzenden als de browser pauzeert voor gebruikersbeoordeling (als toolautosubmit wordt weggelaten).
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;
}

Geschiktheid van formulier (wanneer te vermijden)

De Declarative API is het meest geschikt voor op zichzelf staande, standaard formulieren. In de volgende scenario's is dit een slechte keuze:

  • Zeer afhankelijke velden: Formulieren waarin invoer opties of zichtbaarheid wijzigt op basis van andere invoer. Het samengestelde schema kan deze afhankelijkheden niet goed uitdrukken.
  • Aangepaste UI-componenten: Formulieren die afhankelijk zijn van niet-standaard invoer (bijvoorbeeld canvas, RTF-editors) die waarden niet automatisch serialiseren.
  • Wizards met meerdere stappen: Complexe workflows waarvoor meerdere formulierinzendingen nodig zijn. De Imperative API of standaard DOM-interactie is hier beter geschikt voor.

Wanneer je toolautosubmit gebruikt

  • Alleen-lezen bewerkingen en query's: Zoekopdrachten, filters, gegevens ophalen of de status controleren (bijvoorbeeld een zoekopdracht naar een automodel, een directory doorzoeken, de voorraadbeschikbaarheid controleren).
  • Acties met een laag risico die kunnen worden teruggedraaid: Formulieracties die de gebruiker makkelijk handmatig ongedaan kan maken of verfijnen (bijvoorbeeld artikelen toevoegen aan een winkelwagen, een kortingscode toepassen, een concept opslaan of tijdelijke opmaakopties instellen).

Wanneer je toolautosubmit weglaat

  • Destructieve of onomkeerbare acties: Records verwijderen, systeemconfiguraties resetten of databases wissen.
  • Financiële en transactionele acties: een betaalformulier indienen, geld overboeken, abonnementsbetalingen autoriseren of definitieve bestellingen plaatsen.
  • Gebruikerscommunicatie met grote impact: Een definitieve sollicitatie indienen, e-mails/berichten naar andere echte gebruikers sturen of openbare content publiceren.
  • Gevoelige accountinstellingen: wachtwoorden wijzigen, gebruikersrollen/-rechten aanpassen of facturerings-/profielgegevens updaten.

Reservestrategieën

De WebMCP Declarative API kan veilig worden gebruikt in alle browsers. Browsers die WebMCP niet ondersteunen, negeren de tool*-kenmerken en de <form> blijft werken als een normaal HTML-formulier. Er is geen functiedetectie vereist.