Deklarative API

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

Veröffentlicht am 18. Mai 2026

Erläuterung Web Erweiterungen Chrome-Status Absicht
GitHub Testversion für Entwickler Entwicklertest Testversion für Entwickler Entwicklertest Ansicht Absicht zum Testen

Mit der deklarativen API können Sie Standard-HTML-Formulare in WebMCP-Tools umwandeln, indem Sie Anmerkungen hinzufügen. In den Anmerkungen werden der Name und der Zweck des Tools im <form> Element definiert, während die Felder als Toolparameter dienen. Der Browser übersetzt diese Elemente in eine strukturierte Darstellung, die von Agenten ähnlich wie imperative Tools verwendet werden kann.

Lesen Sie vor der Verwendung dieser API die Anwendungsbeispiele.

Toolregistrierung

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 die Aktion, die das Tool ausführt, und seinen Zweck.

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 verbessern, fügen Sie den einzelnen Formularelementen die folgenden HTML-Attribute hinzu:

  • toolparamdescription: Ordnen Sie Elemente einer Eigenschaftsbeschreibung 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, verwendet der Browser die 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 das folgende JSON 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 zu senden:

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

Die SubmitEvent-Schnittstelle führt das boolesche Attribut agentInvoked ein. Dieses Attribut wird auf „true“ gesetzt, wenn ein Formular von einem KI-Agenten ausgelöst wird, um das Verhalten Ihrer Webanwendung speziell an agentenbasierte Interaktionen anzupassen.

Außerdem enthält SubmitEvent die Methode respondWith(Promise<any>), mit der Sie ein Promise an den Browser ü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. Um diese Methode zu verwenden, müssen Sie zuerst preventDefault() aufrufen, um das standardmäßige Senden des Formulars durch den Browser zu verhindern.

<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 mit dem "toolactivated" Ereignis, dass ein KI-Agent ein Tool ausgeführt hat. Dieses Ereignis wird im Fenster ausgelöst, sobald die Formularfelder vorab ausgefüllt wurden. Wenn ein Nutzer den agentenbasierten Vorgang abbricht oder die Methode reset() aufgerufen wird, wird das "toolcancel" Ereignis ausgelöst. Beide Ereignisse können nicht abgebrochen werden und enthalten ein toolName-Attribut zur Identifizierung.

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

Eine sichtbare Fokusanzeige ist wichtig, um Nutzern und Agenten zu zeigen, wo sie sich auf einer Seite befinden. Wenn ein Agent ein Tool erfolgreich aufruft, das zugehörige Formular in den Fokus rückt und die 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 die Schaltfläche zum Senden des Formulars angewendet, falls vorhanden.

Diese Klassen werden deaktiviert, sobald das Formular gesendet wird, der Agent 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 Stilen für den Fokus.

Mitmachen und Feedback geben

WebMCP wird aktiv diskutiert und kann sich in Zukunft ändern. Wenn Sie diese API testen und Feedback haben, freuen wir uns darauf.