Formulaires agentiques

Fonctionnalités Web : Attributs WebMCP associés à un formulaire

L'API déclarative transforme les éléments HTML <form> standards en outils WebMCP via des attributs. Le navigateur synthétise un schéma JSON à partir des entrées du formulaire et gère les interactions de l'agent.

Formulaires Angular Signal : n'ajoutez PAS toolname/tooldescription aux formulaires créés avec form() à partir de @angular/forms/signals. Ajoutez plutôt provideExperimentalWebMcpForms() aux fournisseurs de l'application et transmettez l'option experimentalWebMcpTool: { name, description } à form(). Angular enregistre ensuite le formulaire via l'API impérative, en créant le schéma à partir du modèle de signal et en le connectant à la validation et à l'envoi. Si vous utilisez les deux approches, le même formulaire sera enregistré deux fois.

Attributs de formulaire

  • toolname : nom unique de l'outil.
  • tooldescription : ce que fait l'outil et quand un agent doit l'utiliser. Ne listez pas les champs, les options ou les limites du formulaire : le navigateur les inclut déjà dans le schéma qu'il crée à partir des commandes du formulaire.
  • toolautosubmit : (facultatif) s'il est présent, l'agent peut envoyer le formulaire sans attendre l'interaction de l'utilisateur.
  • toolparamdescription : (facultatif) permet de définir une description de propriété dans le schéma JSON. Utilisez-le pour expliquer ce que signifie la valeur (par exemple, avec des exemples de valeurs), et non pour répéter les options ou les limites de la commande.
    • Ordre de résolution : le navigateur utilise toolparamdescription s'il est présent. En son absence, il utilise le textContent du <label> associé (en ignorant les descendants pouvant être étiquetés). Si aucune étiquette n'existe, il utilise aria-description.
    • Regroupement (Fieldsets) : pour associer une description à un groupe d'éléments associés (comme des boutons <input type="radio">), placez toolparamdescription sur l'élément parent <fieldset> le plus proche afin qu'il s'applique à l'ensemble du groupe de paramètres.

Exemple

<form toolname="search-cars" 
      tooldescription="Perform a car make/model search" 
      toolautosubmit>
  <label for="make">Vehicle Make</label>
  <input type="text" id="make" name="make" required>
  
  <label for="model">Vehicle Model</label>
  <input type="text" id="model" name="model" toolparamdescription="e.g., 330i, F-150" required>
  
  <button type="submit">Search</button>
</form>

Gérer les envois en JavaScript

Lorsqu'un agent envoie le formulaire, SubmitEvent inclut agentInvoked (booléen) et respondWith(promise).

document.querySelector('form').addEventListener('submit', (event) => {
  event.preventDefault();

  // Validate the form
  const formValidationErrors = myFormIsValid();

  if (formValidationErrors.length > 0) {
    if (event.agentInvoked) {
      const errorString =
        'Validation failed: ' +
        formValidationErrors
          .map((err) => `${err.field} (${err.message})`)
          .join(', ');

      event.respondWith(Promise.resolve(errorString));
    }
    return;
  }

  const resultPromise = performAsyncSearch(new FormData(event.target));

  // Return the result directly to the agent without navigation
  if (event.agentInvoked) {
    event.respondWith(resultPromise);
  }
});

Événements de cycle de vie

document.modelContext émet des événements lorsque les agents commencent ou arrêtent d'interagir avec un outil : toolactivated se déclenche lorsque l'exécution de l'outil commence, et toolcancel se déclenche lorsqu'elle est annulée.

// Starting in Chrome 156, these events are dispatched on `document.modelContext`.
// Older versions dispatch them on `window`. Feature-detect the event handler
// property to pick the right target for backward compatibility.
const targetFor = (type, listener, options) =>
  (`on${type}` in (document.modelContext ?? {}) ? document.modelContext : window)
    .addEventListener(type, listener, options);

targetFor('toolactivated', ({ toolName }) => {
  console.log(`Tool "${toolName}" started execution.`);
});

targetFor('toolcancel', ({ toolName }) => {
  console.log(`Tool "${toolName}" execution is cancelled.`);
});

Commentaires visuels (CSS)

Utilisez des pseudo-classes pour mettre en évidence les formulaires lorsqu'un agent interagit avec eux :

  • :tool-form-active : appliqué à l'élément <form> activement utilisé par l'agent.
  • :tool-submit-active : appliqué au bouton d'envoi lorsque le navigateur s'interrompt pour que l'utilisateur vérifie les informations (si toolautosubmit est omis).
form:tool-form-active {
  outline: 2px dashed blue;
  background-color: rgba(0, 0, 255, 0.05);
}

button:tool-submit-active {
  outline: 2px dashed red;
  animation: pulse 2s infinite;
}

Adéquation du formulaire (quand l'éviter)

L'API déclarative est idéale pour les formulaires standards autonomes. Il n'est pas adapté dans les scénarios suivants :

  • Champs fortement dépendants : formulaires dans lesquels les entrées modifient les options ou la visibilité en fonction d'autres entrées. Le schéma synthétisé ne peut pas exprimer correctement ces dépendances.
  • Composants d'interface utilisateur personnalisés : formulaires reposant sur des entrées non standards (par exemple, canevas, éditeurs de texte enrichi) qui ne sérialisent pas automatiquement les valeurs.
  • Assistants en plusieurs étapes : workflows complexes nécessitant l'envoi de plusieurs formulaires. L'API impérative ou l'interaction DOM standard sont plus adaptées ici.

Quand utiliser toolautosubmit

  • Opérations et requêtes en lecture seule : recherches, filtres, récupération d'informations ou vérification de l'état (par exemple, recherche d'un modèle de voiture, recherche dans un annuaire, vérification de la disponibilité des stocks).
  • Actions réversibles à faible risque : actions de formulaire qui peuvent être facilement annulées ou affinées manuellement par l'utilisateur (par exemple, ajouter des articles à un panier, appliquer un code promotionnel, enregistrer un brouillon ou définir des options de mise en page temporaires).

Quand omettre toolautosubmit

  • Actions destructrices ou irréversibles : suppression d'enregistrements, réinitialisation des configurations système ou effacement de bases de données.
  • Actions financières et transactionnelles : envoyer un formulaire de paiement, transférer des fonds, autoriser des paiements d'abonnement ou passer une commande finale.
  • Communication utilisateur à fort impact : envoyer une candidature finale, envoyer des e-mails/messages à d'autres utilisateurs réels ou publier du contenu destiné au public.
  • Paramètres de compte sensibles : modification des mots de passe, des rôles utilisateur/autorisations ou des informations de profil/facturation.

Stratégies de remplacement

L'API déclarative WebMCP peut être utilisée en toute sécurité dans tous les navigateurs. Les navigateurs qui ne sont pas compatibles avec WebMCP ignoreront les attributs tool*, et l'élément <form> continuera de fonctionner comme un formulaire HTML normal. Aucune détection de caractéristiques n'est requise.