Declaratieve API

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Gepubliceerd: 18 mei 2026

Uitleg Web Uitbreidingen Chrome-status Intentie
GitHub Ontwikkelaarsproef Ontwikkelaarsproef Ontwikkelaarsproef Ontwikkelaarsproef Weergave Voornemen om te experimenteren

Gebruik de Declarative API om standaard HTML-formulieren om te zetten in WebMCP-tools door annotaties toe te voegen. Annotaties definiëren de naam en het doel van de tool in het <form> -element, terwijl de velden fungeren als toolparameters. De browser vertaalt deze elementen naar een gestructureerde weergave die agents kunnen gebruiken, vergelijkbaar met imperatieve tools .

Voordat u deze API gebruikt, lees dan eerst meer over voorbeelden van gebruiksscenario's .

Toolregistratie

Voeg de volgende HTML-attributen toe aan uw formulier:

  • toolname : Geef de tool een duidelijke naam op basis van het doel ervan.
  • tooldescription : Beschrijf welke actie de tool uitvoert en wat het doel ervan is.

Het volgende formulier is bijvoorbeeld te vinden op example.com/get-customer-support :

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

Wanneer een agent toolname aanroept, brengt de browser het formulier in focus en vult het bijbehorende veld in. Het formulier blijft zichtbaar voor de gebruiker.

Als je het HTML-attribuut toolname of tooldescription verwijdert, wordt de tool gederegistreerd.

(Optioneel) Gereedschapsparameters

Om de nauwkeurigheid te verbeteren, voegt u de volgende HTML-attributen toe aan de afzonderlijke formulierelementen:

  • toolparamdescription : Koppelt elementen aan een eigenschapsbeschrijving binnen het JSON-schema. Zonder dit attribuut gebruikt de browser de inhoud van het bijbehorende <label> en slaat afstammelingen over die een label kunnen krijgen. Als er geen label is, verwijst de browser naar de aria-description .

Het volgende formulier maakt gebruik van de optionele parameters voor het <select> -element.

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

De browser interpreteert dit formulier als een hulpmiddel, weergegeven door de volgende JSON:

[
  {
    "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"
      ]
    }
  }
]

Dien het formulier in

Je hebt twee opties om het formulier in te dienen:

  • De gebruiker moet handmatig op 'Verzenden' klikken om de taak te voltooien.
  • Voeg toolautosubmit toe om het verzenden van een bericht en een navigatiewijziging te activeren.

De SubmitEvent interface introduceert het booleaanse attribuut agentInvoked . Dit attribuut wordt op true gezet wanneer een formulier wordt geactiveerd door een AI-agent, om het gedrag van uw webapplicatie specifiek aan te passen aan interacties via een agent.

Daarnaast bevat de SubmitEvent de methode respondWith(Promise<any>) , waarmee je een promise aan de browser kunt doorgeven die je vervolgens oplost met de resultaten van het formulier. De resulterende waarde wordt vervolgens geserialiseerd en als uitvoer van de tool naar het model teruggestuurd. Om deze methode te gebruiken, moet je eerst preventDefault() aanroepen om de standaard formulierinzending van de browser te stoppen.

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

De browser geeft aan dat een AI-agent een tool heeft uitgevoerd met de gebeurtenis "toolactivated" . Deze gebeurtenis wordt geactiveerd zodra formuliervelden zijn ingevuld. Omgekeerd, als een gebruiker de agentbewerking annuleert of de reset() methode wordt aangeroepen, wordt de gebeurtenis "toolcancel" geactiveerd. Beide gebeurtenissen kunnen niet worden geannuleerd en hebben een toolName attribuut ter identificatie.

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.
});

Focusindicator wijzigen

Een zichtbare focusindicator is essentieel om gebruikers en agenten te laten weten waar ze zich op een pagina bevinden. Wanneer een agent een tool succesvol oproept, het bijbehorende formulier selecteert en de velden automatisch invult, activeert de browser specifieke CSS-pseudoklassen voor visuele feedback:

  • :tool-form-active wordt toegepast op het HTML- form van de tool.
  • :tool-submit-active wordt toegepast op de verzendknop van het formulier, indien aanwezig.

Deze CSS-klassen worden gedeactiveerd zodra het formulier is verzonden, de agent de actie annuleert of de gebruiker het formulier opnieuw invult. U kunt de CSS voor deze statussen aanpassen of vertrouwen op een standaard browserstijl.

/* 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;
}

Leer meer over de beste werkwijzen en stijlen voor focus .

Betrek de deelnemers en deel je feedback.

WebMCP is onderwerp van actieve discussie en kan in de toekomst nog veranderen. Als u deze API uitprobeert en feedback heeft, horen we dat graag.