API déclarative

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Publié le 18 mai 2026

Présentateur Web Extensions État de Chrome Intention
GitHub Essai pour les développeurs Essai pour les développeurs Essai pour les développeurs Essai pour les développeurs Afficher Intention de tester

Utilisez l'API déclarative pour transformer des formulaires HTML standards en outils WebMCP en ajoutant des annotations. Les annotations définissent le nom et l'objectif de l'outil dans l' <form> élément, tandis que les champs font office de paramètres d'outil. Le navigateur traduit ces éléments en une représentation structurée que les agents peuvent utiliser de la même manière que les outils impératifs.

Avant d'utiliser cette API, consultez des exemples de cas d'utilisation.

Enregistrement de l'outil

Ajoutez les attributs HTML suivants à votre formulaire :

  • toolname : nommez clairement l'outil en fonction de son objectif.
  • tooldescription : décrivez l'action effectuée par l'outil et son objectif.

Par exemple, le formulaire suivant se trouve à l'adresse example.com/get-customer-support :

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

Lorsqu'un agent appelle toolname, le navigateur met le formulaire en évidence et remplit son champ. Le formulaire reste visible pour l'utilisateur.

Si vous supprimez l'attribut HTML toolname ou tooldescription, l'outil est désenregistré.

(Facultatif) Paramètres de l'outil

Pour améliorer la précision, ajoutez les attributs HTML suivants à des éléments de formulaire individuels :

  • toolparamdescription : mappez les éléments à une description de propriété dans le schéma JSON. Sans cet attribut, le navigateur utilise le contenu de l'élément <label> associé et ignore les descendants qui peuvent être libellés. S'il n'y a pas de libellé, le navigateur fait référence à aria-description.

Le formulaire suivant utilise les paramètres facultatifs pour l'élément <select>.

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

Le navigateur interprète ce formulaire comme un outil, représenté par le JSON suivant :

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

Envoyer le formulaire

Vous avez deux possibilités pour envoyer le formulaire :

  • L'utilisateur doit cliquer manuellement sur Envoyer pour effectuer la tâche.
  • Ajoutez toolautosubmit pour déclencher l'envoi et un changement de navigation.

L'interface SubmitEvent introduit l'attribut booléen agentInvoked. Cet attribut est défini sur "true" chaque fois qu'un formulaire est déclenché par un agent IA, afin d'adapter le comportement de votre application Web spécifiquement aux interactions basées sur un agent.

De plus, SubmitEvent inclut la méthode respondWith(Promise<any>), ce qui vous permet de transmettre une promesse au navigateur que vous résolvez avec les résultats du formulaire. La valeur résultante est ensuite sérialisée et renvoyée au modèle en tant que sortie de l'outil. Pour utiliser cette méthode, vous devez d'abord appeler preventDefault() pour arrêter l'envoi standard du formulaire par le navigateur.

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

Le navigateur signale qu'un agent d'IA a exécuté un outil avec l'"toolactivated" événement. Cet événement se déclenche dans la fenêtre une fois les champs du formulaire préremplis. À l'inverse, si un utilisateur annule l'opération de l'agent ou si la méthode reset() est appelée, un événement "toolcancel" est déclenché. Ces deux événements ne peuvent pas être annulés et fournissent un attribut toolName pour l'identification.

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

Modifier l'indicateur de focus

Un indicateur de focus visible est essentiel pour informer les utilisateurs et les agents de leur position sur une page. Lorsqu'un agent appelle un outil, met le formulaire associé en évidence et remplit automatiquement ses champs, le navigateur déclenche des pseudo-classes CSS spécifiques pour fournir un retour visuel :

  • :tool-form-active est appliqué à l'élément HTML form de l'outil.
  • :tool-submit-active est appliqué au bouton d'envoi du formulaire, le cas échéant.

Ces classes sont désactivées une fois le formulaire envoyé, l'agent annule l'action ou l'utilisateur réinitialise le formulaire. Vous pouvez personnaliser le code CSS de ces états ou vous appuyer sur un style de navigateur par défaut.

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

En savoir plus sur les bonnes pratiques et le style en matière de focus.

Participer et partager vos commentaires

WebMCP fait l'objet de discussions actives et est susceptible d'être modifié à l'avenir. Si vous essayez cette API et que vous avez des commentaires, n'hésitez pas à nous en faire part.