API impérative

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

Publié le 18 mai 2026. Dernière mise à jour le 15 octobre 2026.

Présentateur Web Extensions État de Chrome Intention
GitHub Essai Origin Trial Essai d'origine Afficher Intention de tester

Vous pouvez utiliser l'API impérative WebMCP pour définir de nombreux types d'outils avec JavaScript standard. Vos outils peuvent exécuter différentes fonctions, telles que la saisie de formulaires, la navigation sur le site et la gestion des états.

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

Fournir le contexte du modèle

Utilisez l'interface modelContext pour enregistrer des outils. L'enregistrement d'un outil nécessite un nom, une description et un schéma d'entrée avec les propriétés pertinentes.

Utilisez registerTool pour ajouter un seul outil au contexte du modèle.

WebMCPza Maker

await document.modelContext.registerTool({
  name: 'toggle_layer',
  description: 'Control pizza layers (sauce, cheese). Use "add", "remove", or "toggle".',
  inputSchema: {
    type: 'object',
    properties: {
      layer: { type: 'string', enum: ['sauce-layer', 'cheese-layer'] },
      action: { type: 'string', enum: ['add', 'remove', 'toggle'] },
    },
    required: ['layer'],
  },
  execute: async ({ layer, action }) => {
    await toggleLayer(layer, action);
    return `Performed ${action || 'toggle'} on layer: ${layer}`;
  },
});

Obtenir l'état de la commande

await document.modelContext.registerTool({
  name: 'get_order_status',
  description: 'Search orders in a given timeframe. Returns order number, shipping status and location',
  inputSchema: {
    "type": "object",
    "properties": {
      "timeframe": { "type": "string", "oneOf": [
        { "type": "string", "const": "today", "title": "Today" },
        { "type": "string", "const": "yesterday", "title": "Yesterday" },
        { "type": "string", "const": "last_7_days", "title": "Last 7 Days" },
        { "type": "string", "const": "last_30_days", "title": "Last 30 Days" },
        { "type": "string", "const": "last_6_months", "title": "Last 6 Months" }],
      "enum": [ "today", "yesterday", "last_7_days", "last_30_days", "last_6_months" ],
      "description": "Timeframe for the order lookup." }
    },
    "required": [ "timeframe" ]
  },
  execute: async ({ timeframe }) => {
    // Add your API or database logic here to fetch and return the order data as a string.
  },
});

Annotations d'outil (facultatif)

Lorsque vous enregistrez un outil, vous pouvez ajouter des métadonnées dans la propriété annotations. Ces annotations aident les agents et les navigateurs à comprendre les caractéristiques de sécurité d'un outil, les effets secondaires attendus, la fiabilité de la sortie et l'audience visée :

  • readOnlyHint (booléen, valeur par défaut false) : lorsque la valeur est true, indique que l'outil ne lit que des informations et ne modifie pas l'état de l'application ni du système (par exemple, la recherche dans un catalogue de produits ou la récupération de l'état de la commande). Cela aide les agents à déterminer si l'outil peut être appelé en toute sécurité sans effets secondaires.
  • untrustedContentHint (booléen, valeur par défaut false) : lorsque la valeur est true, indique que la sortie de l'outil contient des données non fiables du point de vue de l'auteur de l'outil (par exemple, du contenu généré par l'utilisateur, des avis ou des données Web externes). Cela signale à l'agent et au client que la charge utile renvoyée nécessite une gestion de la sécurité renforcée, telle que la désinfection ou la délimitation, afin d' atténuer l'injection indirecte d'invite.
  • consequentialHint (booléen, valeur par défaut false) : lorsque la valeur est true, indique que l'exécution de l'outil entraîne des actions importantes, réelles ou irréversibles (par exemple, la réservation d'un vol, le transfert d'argent ou la suppression de données). Cela permet aux agents et aux navigateurs d'appliquer des invites de confirmation obligatoires avant d'exécuter des outils à enjeux élevés, ce qui réduit le risque de fausse déclaration accidentelle ou malveillante de l'intention de l'utilisateur.
  • debugging (booléen, valeur par défaut false, disponible à partir de Chrome 156) : lorsque la valeur est true, indique que l'outil est conçu spécifiquement pour l'inspection et les outils de développement (par exemple, les frameworks de test ou l'assistance IA des Outils pour les développeurs Chrome) plutôt que pour les interactions avec l'utilisateur final. Cela permet aux agents à usage général et aux utilisateurs finaux de filtrer les outils axés sur les développeurs.
await document.modelContext.registerTool({
  name: 'book_flight',
  description: 'Book a flight for the user with confirmed flight details.',
  inputSchema: {
    type: 'object',
    properties: {
      flightId: { type: 'string', description: 'ID of the flight to book' },
      passengers: { type: 'number', description: 'Number of tickets to purchase' },
    },
    required: ['flightId', 'passengers'],
  },
  annotations: {
    readOnlyHint: false,
    consequentialHint: true,
    untrustedContentHint: false,
    debugging: false,
  },
  execute: async ({ flightId, passengers }) => {
    // Add your flight booking transaction logic here.
    return `Booked ${passengers} passenger(s) on flight ${flightId}.`;
  },
});

Pour obtenir des exemples de l'influence des annotations sur le comportement des agents, consultez l'exemple d'extension WebMCP.

Annuler l'enregistrement des outils

Vous pouvez supprimer un outil avec AbortSignal, lorsqu'il est transmis en tant que paramètre facultatif.

const addTodoTool = {
  name: "addTodo",
  description: "Add a new item to the to-do list",
  inputSchema: {
    type: "object",
    properties: { text: { type: "string" } },
  },
  execute: async ({ text }) => {
    // You should handle the persistence logic here (omitted for demo)
    return `Added to-do: ${text}`;
  },
  annotations: {
    readOnlyHint: false,
    untrustedContentHint: true
  },
};
const controller = new AbortController();
await document.modelContext.registerTool(addTodoTool, { signal: controller.signal });

// Unregister the tool later...
controller.abort();

À partir de Chrome 153, vous pouvez annuler l'enregistrement d'un outil sans annuler ni interrompre les exécutions en cours. Cela évite les effets secondaires inattendus lors de la gestion des cycles de vie des outils dans les frameworks de composants.

Gérer l'annulation d'un outil

La fonction execute reçoit un paramètre AbortSignal nommé signal comme deuxième argument pour gérer correctement les annulations d'exécution initiées par l'utilisateur ou l'agent. La transmission de ce signal à des tâches asynchrones ou à des opérations réseau de longue durée (telles que fetch()) permet d'éviter un travail inutile, d'améliorer la gestion globale des ressources et d'éviter les fuites potentielles.

await document.modelContext.registerTool({
  name: 'fetch_tool',
  description: 'Fetch the text content of a URL and stream the response.',
  inputSchema: {
    type: 'object',
    properties: {
      url: { type: 'string', description: 'The URL to fetch' },
      priority: { type: 'string', enum: ['high', 'low', 'auto'] },
    },
    required: ['url'],
  },
  execute: async ({ url, priority }, { signal }) => {
    // Abort the fetch request when tool execution is aborted.
    const response = await fetch(url, { priority, signal });
    const stream = response.body.pipeThrough(new TextDecoderStream());
    for await (const chunk of stream) {
      document.querySelector('pre').textContent += chunk;
    }
    return 'Success';
  },
});

Découvrent les outils

Utilisez document.modelContext.getTools() pour récupérer les outils disponibles. Cette méthode asynchrone renvoie une liste alphabétique des outils auxquels le document appelant est autorisé à accéder.

const [tool] = await document.modelContext.getTools();
console.log(tool);

// {
//   annotations: { consequentialHint: false, debugging: false, readOnlyHint: false, untrustedContentHint: true }, // Optional hints
//   description: "Add a new item to the to-do list",
//   inputSchema: {"type":"object","properties":{…}},
//   name: "addTodo",
//   origin: "https://example.com",
//   title: ""
//   window: Window {window: Window, self: Window, …},
// }

Par défaut, getTools() ne renvoie que les outils de même origine enregistrés par le document appelant ou d'autres documents de même origine dans l'arborescence de frames. Pour récupérer des outils inter-origines, vous devez lister explicitement leurs origines dans l'option fromOrigins. Ce tableau n'accepte que les origines sécurisées.

Les outils provenant de documents inter-origines ne sont inclus que si :

  1. L'origine d'hébergement est listée dans l'option fromOrigins.
  2. L'outil a été explicitement exposé à votre origine.
// https://example.com

// Get same-origin tools only
const sameOriginTools = await document.modelContext.getTools();

// Get same-origin tools plus tools from specific cross-origin documents
const allTools = await document.modelContext.getTools({
  fromOrigins: ['https://partner.org']
});

Consultez la démonstration de l'agent de page WebMCP pour obtenir un exemple de récupération d'outils à partir d'un iFrame et de leur exécution dans une interface de chat Web. Consultez l'exemple d'extension WebMCP pour découvrir comment un agent d'une extension de navigateur trouve et exécute des outils dans des iFrames de même origine et inter-origines.

Exécuter l'outil

Pour exécuter manuellement un outil découvert dans getTools(), appelez document.modelContext.executeTool() avec un objet JavaScript facultatif pour les arguments d'entrée sérialisables en chaîne JSON. Cette méthode asynchrone renvoie le résultat de l'exécution de l'outil ou la valeur "null" lorsqu'une navigation est déclenchée.

const result = await document.modelContext.executeTool(tool, { text: "Buy milk" });
console.log(result);

// 'Added to-do: Buy milk'

Vous pouvez annuler une exécution d'outil en attente avec AbortSignal, lorsqu'il est transmis en tant que paramètre facultatif.

const controller = new AbortController();
document.modelContext.executeTool(tool, { text: "Buy milk" }, { signal: controller.signal });

// Cancel tool execution later...
controller.abort();

Événements

Les frames peuvent écouter l'événement toolchange sur document.modelContext pour être averties lorsque la liste des outils disponibles a changé.

document.modelContext.addEventListener("toolchange", (event) => {
  // Tools have changed.
});

iFrames inter-origines

WebMCP est compatible avec les iFrames inter-origines qui utilisent à la fois des règles d'autorisation et un contrôle d'origine explicite.

Règle d'autorisation

L'enregistrement des outils est désactivé par défaut dans les iFrames inter-origines. Une page doit déléguer l'accès à l'aide de la tools règle d'autorisation :

<iframe src="https://example.com" allow="tools"></iframe>

Exposition de l'origine

Les outils ne sont pas disponibles pour les documents inter-origines par défaut. Vous pouvez utiliser le tableau exposedTo dans registerTool pour lister les origines spécifiques autorisées à afficher et à exécuter un outil. Ce tableau n'accepte que les origines sécurisées.

// https://partner.org

await document.modelContext.registerTool({
  name: 'my_shared_tool',
  description: 'Shared across origins',
  // ...
}, {
  exposedTo: ['https://example.com']
});

Compatibilité avec React

React est compatible, à titre expérimental, avec WebMCP à l'aide du package usewebmcp. Si votre application est déjà écrite avec React, vous pouvez enregistrer des outils à l'aide de hooks autonomes liés au cycle de vie de montage et de démontage de votre composant. Le hook useWebMCP fournit également une inférence de type basée sur le schéma et expose l'état d'exécution local.

Compatibilité avec Angular

Angular est compatible, à titre expérimental, avec WebMCP. Si votre application est déjà écrite avec Angular, vous pouvez enregistrer des outils liés au cycle de vie de l'injection de dépendances de l'application et transformer vos formulaires de signaux en outils WebMCP.

Compatibilité avec Vue

Vue est compatible, à titre expérimental, avec WebMCP à l'aide du package @vueuse/core. Si votre application est déjà écrite avec Vue, vous pouvez enregistrer des outils à l'aide du composable useWebMCP lié au cycle de vie de la portée Vue actuelle. Il est également compatible avec l'enregistrement réactif et conditionnel des outils, et normalise automatiquement les résultats d'exécution.

Participer et envoyer des commentaires

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

Précédent
Premiers pas
Suivant
API déclarative