Deklarative API

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

Veröffentlicht: 18. Mai 2026, Letzte Aktualisierung: 25. September 2026

Erklärvideo 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 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 ist beispielsweise unter example.com/get-customer-support verfügbar:

<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: 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 keine Bezeichnung 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 für document.modelContext ausgelöst, sobald 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 storniert werden und enthalten zur Identifizierung das Attribut toolName.

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

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

Fokusanzeige ändern

Ein sichtbarer Fokusindikator ist entscheidend, um Nutzer und Agents darüber zu informieren, 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 form-Element des Tools im HTML-Code angewendet.
  • :tool-submit-active wird auf den Button zum Senden des Formulars angewendet, sofern ein solcher 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 befindet sich in der aktiven Diskussion und kann sich daher ändern. Wenn Sie diese API ausprobieren und Feedback dazu haben, würden wir uns freuen, von Ihnen zu hören.

Zurück
Imperative API
Weiter
WebMCP im Vergleich zu MCP