API déclarative

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

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'élément <form>, tandis que les champs servent 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 les exemples de cas d'utilisation.

Enregistrement des outils

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="createSupportRequest" tooldescription="Submits a request for customer support.">
</form>

Lorsqu'un agent appelle toolname, le navigateur met le formulaire au premier plan et remplit son champ. Le formulaire reste visible pour l'utilisateur.

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

(Facultatif) Paramètres de l'outil

Pour améliorer la précision, ajoutez les attributs HTML suivants aux é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 pouvant être associés à un libellé. S'il n'y a pas de libellé, le navigateur se réfère à aria-description.

Le formulaire suivant utilise les paramètres facultatifs de 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

Deux options s'offrent à vous pour l'envoi du formulaire :

  • L'utilisateur doit cliquer manuellement sur Envoyer pour terminer la tâche.
  • Ajoutez toolautosubmit pour déclencher l'envoi et une navigation lorsque le modèle appelle cet outil.

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 des agents.

De plus, SubmitEvent inclut la méthode respondWith(Promise<any>). Vous pouvez donc transmettre une promesse au navigateur que vous résolvez avec les résultats du formulaire. La valeur obtenue 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 du 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'événement "toolactivated". 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 agentique 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 sélection visible est essentiel pour informer les utilisateurs et les agents de leur position sur une page. Lorsqu'un agent appelle un outil, se concentre sur le formulaire associé 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 form HTML 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 concernant la mise au point

Participer et envoyer des 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.