Formulare zu Werkzeugen machen

Voraussetzungen

Zum Ausprobieren brauchen Sie Chrome und das eingeschaltete Flag. Der Origin Trial läuft seit Chrome 149.0.7827.102 und ist bis Chrome 156 geplant.

1. Flag einschalten

   chrome://flags/#enable-webmcp-testing aufrufen, auf Enabled stellen, Chrome neu starten.

2. Erweiterung installieren

   Der Model Context Tool Inspector zeigt registrierte Werkzeuge an und führt sie manuell aus. Ohne ihn sehen Sie nicht, ob Ihre Annotationen greifen.

3. Am lebenden Objekt prüfen

   Der Playground registriert echte Werkzeuge und prüft zuerst, ob Ihr Browser sie überhaupt unterstützt.

Schritt 1: Basis-Attribute am form-Element

Damit ein Agent Ihr Formular als Werkzeug erkennt, braucht das form-Element zwei Pflichtattribute.

<form
  toolname="flight_search"
  tooldescription="Search for flights between two cities on a given date"
  action="/search"
>
  ...
</form>

Schritt 2: Feld-Annotationen

Diese Attribute auf input, select und textarea erklären dem Agenten die erwarteten Datenformate. Sie werden intern auf Eigenschaften eines JSON Schema abgebildet.

<label for="dest">Zielflughafen</label>
<input
  type="text"
  name="destination"
  id="dest"
  toolparamtitle="destination_airport_code"
  toolparamdescription="3-letter IATA code, e.g. LON or NYC"
>

Schritt 3: Event-Handling

WebMCP ändert das Submit-Verhalten, sobald ein Agent beteiligt ist. Statt die Seite neu zu laden, können Sie dem Agenten direkt ein Ergebnis zurückgeben. event.agentInvoked ist ein Boolean und true, wenn nicht der Nutzer, sondern ein Agent abgeschickt hat.

document.querySelector("form").addEventListener("submit", (e) => {
  if (e.agentInvoked) {
    e.preventDefault();           // Zwingend VOR respondWith
    const ergebnis = sucheAusfuehren(new FormData(e.target));
    e.respondWith(Promise.resolve({
      content: [{ type: "text", text: JSON.stringify(ergebnis) }]
    }));
  }
  // Ohne agentInvoked: normales Formularverhalten, nichts ändert sich.
});

Lifecycle-Ereignisse

Zwei Ereignisse feuern am window und sagen Ihnen, was der Agent gerade tut.

• toolactivated feuert, wenn der Agent beginnt, das Formular auszufüllen. Nützlich, um die Oberfläche zu sperren oder das Ereignis zu zählen.
• toolcancel feuert, wenn der Agent abbricht oder das Formular zurückgesetzt wird.

window.addEventListener("toolactivated", () => {
  // Der Agent beginnt auszufüllen: Oberfläche sperren, Ereignis zählen.
  document.body.dataset.agent = "aktiv";
});

window.addEventListener("toolcancel", () => {
  // Der Agent bricht ab oder setzt zurück.
  delete document.body.dataset.agent;
});

Schritt 4: sichtbares Feedback

Der Nutzer sieht zu, wie der Agent Felder ausfüllt. Zwei Pseudo-Klassen geben Ihnen die Möglichkeit, das sichtbar zu machen, ohne selbst Zustand zu verwalten.

• :tool-form-active gilt am form, solange der Agent arbeitet.
• :tool-submit-active gilt am Submit-Knopf während der Agent-Aktion.

form:tool-form-active {
  outline: 2px solid var(--rot-500);
  outline-offset: 4px;
  transition: outline-color 0.3s;
}

button[type="submit"]:tool-submit-active {
  opacity: 0.6;
  pointer-events: none;
}

Schritt 5: semantische Best Practices

Der Agent wählt anhand von Text. Diese drei Regeln senken die Fehlerquote spürbar.

• Positiv formulieren. Beschreiben Sie in tooldescription, was das Werkzeug kann, nicht was es nicht darf. Modelle arbeiten mit klaren Handlungsanweisungen besser als mit Verboten.
• Eingaben robust auslegen. Zwingen Sie den Agenten nicht zum Rechnen. Wenn ein Nutzer „nächsten Montag" sagt, sollte Ihr Werkzeug das verarbeiten können, oder das Feld muss so beschrieben sein, dass der Agent ein ISO-Datum erzeugt.
• Präzise Verben im Namen. create_event für die direkte Aktion, start_event_creation für einen Ablauf, der auf eine weitere Oberfläche führt. So setzt der Agent die richtigen Erwartungen.

Vollständiges Beispiel

Eine Flugsuche als Werkzeug, komplett: Attribute, Feld-Annotationen und Agent-Handling. Für Menschen bleibt es ein ganz normales Formular.

<form
  toolname="flight_search"
  tooldescription="Search for flights between two cities on a given date"
  action="/search"
>
  <p>
    <label for="dest">Zielflughafen</label>
    <input type="text" name="destination" id="dest" required
           toolparamtitle="destination_airport_code"
           toolparamdescription="3-letter IATA code, e.g. LON or NYC">
  </p>
  <p>
    <label for="tag">Abreisedatum</label>
    <input type="date" name="departure" id="tag" required
           toolparamdescription="Departure date as YYYY-MM-DD">
  </p>
  <p><button type="submit">Flüge suchen</button></p>
</form>

<script>
document.querySelector("form").addEventListener("submit", (e) => {
  if (!e.agentInvoked) return;    // Menschen: normales Verhalten
  e.preventDefault();
  const treffer = sucheAusfuehren(new FormData(e.target));
  e.respondWith(Promise.resolve({
    content: [{ type: "text", text: JSON.stringify(treffer) }]
  }));
});
</script>

Dasselbe Muster läuft live im Playground, dort mit Aktivitätsprotokoll: Sie sehen jeden Aufruf, während er passiert.