Deklarative API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky
François Beaufort
François Beaufort
GitHub

Veröffentlicht am 18. Mai 2026

Erklärung Web Erweiterungen Chrome-Status Absicht
GitHub Ursprungstest Ursprungstest Ansicht Absichtserklärung für Tests

Mit der deklarativen API können Sie Standard-HTML-Formulare in WebMCP-Tools umwandeln, indem Sie Anmerkungen hinzufügen. Mit Anmerkungen werden der Name und der Zweck des Tools im <form>-Element definiert, während die Felder als Tool-Parameter fungieren. Der Browser übersetzt diese Elemente in eine strukturierte Darstellung, die Agents ähnlich wie imperative Tools verwenden können.

Lesen Sie sich vor der Verwendung dieser API die Beispielanwendungsfälle durch.

Tool-Registrierung

Fügen Sie Ihrem Formular die folgenden HTML-Attribute hinzu:

  • toolname: Geben Sie dem Tool einen eindeutigen Namen, der auf seinem Zweck basiert.
  • tooldescription: Beschreiben Sie, welche Aktion das Tool ausführt und welchen Zweck es hat.

Das folgende Formular befindet sich beispielsweise unter example.com/get-customer-support:

<form toolname="createSupportRequest" tooldescription="Submits a request for customer support.">
</form>

Wenn ein Agent toolname aufruft, wird das Formular im Browser in den Fokus gerückt und das Feld wird ausgefüllt. Das Formular bleibt für den Nutzer sichtbar.

Wenn Sie das HTML-Attribut toolname oder tooldescription entfernen, wird die Registrierung des Tools aufgehoben.

(Optional) Toolparameter

Um die Genauigkeit zu erhöhen, fügen Sie den einzelnen Formularelementen die folgenden HTML-Attribute hinzu:

  • toolparamdescription: Ordnet Elemente einer Property-Beschreibung im JSON-Schema zu. Ohne dieses Attribut verwendet der Browser den Inhalt des zugehörigen <label> und überspringt untergeordnete Elemente, die mit einem Label versehen werden können. Wenn kein Label vorhanden ist, verweist der Browser auf aria-description.

Im folgenden Formular werden die optionalen Parameter für das <select>-Element verwendet.

<form toolname="supportRequestTool"
  tooldescription="Submit a request for support."
  action="/submit">

  <label for="firstName">First Name</label>
  <input type=text name=firstName>

  <label for="lastName">Last Name</label>
  <input type=text name=lastName>

  <select name="select" required 
    toolparamdescription="Determines what team this request is routed to.">
    <option value="Customer happiness team">Return my purchase.</option>
    <option value="Distribution team">Check where my package is.</option>
    <option value="Website support team">Get help on the website.</option>
  </select>

  <button type=submit>Submit</button>
</form>

Der Browser interpretiert dieses Formular als Tool, das durch den folgenden JSON-Code dargestellt wird:

[
  {
    "name": "supportRequestTool",
    "description": "Submit a request for support.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "firstName": {
          "type": "string"
        },
        "lastName": {
          "type": "string"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "type": "string",
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "type": "string",
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "type": "string",
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "description": "Determines what team this request is routed to."
        }
      },
      "required": [
        "select"
      ]
    }
  }
]

Formular senden

Sie haben zwei Möglichkeiten, das Formular einzureichen:

  • Der Nutzer muss manuell auf Senden klicken, um die Aufgabe abzuschließen.
  • Fügen Sie toolautosubmit hinzu, um die Einreichung und eine Navigation auszulösen, wenn das Modell dieses Tool aufruft.

Mit der SubmitEvent-Schnittstelle wird das boolesche Attribut agentInvoked eingeführt. Dieses Attribut wird auf „true“ gesetzt, wenn ein Formular von einem KI-Agenten ausgelöst wird. So können Sie das Verhalten Ihrer Web-App speziell für agentenbasierte Interaktionen anpassen.

Außerdem enthält SubmitEvent die Methode respondWith(Promise<any>). Sie können also ein Promise an den Browser übergeben, das Sie mit den Ergebnissen des Formulars auflösen. Der resultierende Wert wird dann serialisiert und als Ausgabe des Tools an das Modell zurückgegeben. Wenn Sie diese Methode verwenden möchten, müssen Sie zuerst preventDefault() aufrufen, um die standardmäßige Formularübermittlung des Browsers zu beenden.

<form toolautosubmit toolname="search_tool"
  tooldescription="Search the web" action="/search">
  <input type=text name=query>
</form>
<script>
  document.querySelector("form").addEventListener("submit", (e) => {
    e.preventDefault();
    if (!myFormIsValid()) {
      if (e.agentInvoked) { e.respondWith(myFormValidationErrorPromise) };
      return;
    }
    if (e.agentInvoked) { e.respondWith(Promise.resolve("Search is done!")); }
  });
</script>

Der Browser signalisiert, dass ein KI-Agent ein Tool mit dem "toolactivated"-Ereignis ausgeführt hat. Dieses Ereignis wird im Fenster ausgelöst, sobald die Formularfelder vorausgefüllt sind. Wenn ein Nutzer den Agent-Vorgang abbricht oder die Methode reset() aufgerufen wird, wird ein "toolcancel"-Ereignis ausgelöst. Beide Ereignisse können nicht abgebrochen werden und haben zur Identifizierung das Attribut toolName.

window.addEventListener('toolactivated', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was activated.`);
  // TODO: Update UI or validate form if needed.
});

window.addEventListener('toolcancel', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was cancelled.`);
  // TODO: Let the user know. Update UI.
});

Fokusanzeige ändern

Ein sichtbarer Fokusindikator ist wichtig, um Nutzer und Kundenservicemitarbeiter darüber zu informieren, wo sie sich auf einer Seite befinden. Wenn ein Kundenservicemitarbeiter ein Tool erfolgreich aufruft, das zugehörige Formular fokussiert und die Felder automatisch ausfüllt, löst der Browser bestimmte CSS-Pseudoklassen für visuelles Feedback aus:

  • :tool-form-active wird auf das form-Element des Tools angewendet.
  • :tool-submit-active wird auf die Schaltfläche zum Senden des Formulars angewendet, sofern eine vorhanden ist.

Diese Klassen werden deaktiviert, sobald das Formular gesendet wird, der Kundenservicemitarbeiter die Aktion abbricht oder der Nutzer das Formular zurücksetzt. Sie können das CSS für diese Status anpassen oder sich auf einen Standardbrowserstil verlassen.

/* Chrome default declarative form styles. */
form:tool-form-active {
  outline: light-dark(blue, cyan) dashed 1px;
  outline-offset: -1px;
}

input:tool-submit-active {
  outline: light-dark(red, pink) dashed 1px;
  outline-offset: -1px;
}

Weitere Informationen zu Best Practices und Stil für den Fokus

Feedback geben

WebMCP wird derzeit aktiv diskutiert und kann sich in Zukunft ändern. Wenn Sie diese API ausprobieren und Feedback dazu haben, würden wir uns freuen, wenn Sie uns dieses mitteilen.