Deklarative API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Veröffentlicht am 18. Mai 2026

Erklärung Web Erweiterungen Chrome-Status Absicht
GitHub Testversion für Entwickler Entwicklertestzeitraum Testversion für Entwickler Entwicklertestzeitraum 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 Element <form> 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="supportRequestTool" tooldescription="Submit a request for 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: Elemente einer Karte einer Eigenschaftsbeschreibung im JSON-Schema zuordnen. 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 toolparamtitle="Support type" 
    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": {
        "text": {
          "type": "string",
          "title": "firstName",
          "description": "First name"
        },
        "text": {
          "type": "string",
          "title": "lastName",
          "description": "Last name"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "title": "Support type",
          "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 Navigationsänderung auszulösen.

Mit der Schnittstelle SubmitEvent 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>), sodass Sie dem Browser ein Promise übergeben können, 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. Damit Sie diese Methode verwenden können, 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 für das Fenster ausgelöst, sobald Formularfelder vorausgefüllt sind. Wenn ein Nutzer den agentenbasierten Vorgang abbricht oder die Methode reset() aufgerufen wird, wird ein "toolcancel"-Ereignis ausgelöst. Beide Ereignisse können nicht abgebrochen werden und enthalten 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, damit Nutzer und Kundenservicemitarbeiter wissen, wo sie sich auf einer Seite befinden. Wenn ein Agent ein Tool erfolgreich aufruft, das zugehörige Formular fokussiert und seine Felder automatisch ausfüllt, löst der Browser bestimmte CSS-Pseudoklassen für visuelles Feedback aus:

  • :tool-form-active wird auf das HTML-Element form des Tools angewendet.
  • :tool-submit-active wird auf den Senden-Button des Formulars angewendet, sofern vorhanden.

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 einen Standardbrowserstil verwenden.

/* 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 befindet sich in der aktiven Diskussion und kann sich daher in Zukunft ändern. Wenn Sie diese API ausprobieren und Feedback dazu haben, würden wir uns freuen, wenn Sie uns dieses mitteilen.