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 2 juin 2026

Présentateur Web Extensions État de Chrome Intention
GitHub Essai pour les développeurs Essai pour les développeurs 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, comme la saisie de formulaires, la navigation sur le site et la gestion de l'état.

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

Fournir le contexte du modèle

Utilisez l'interface modelContext pour enregistrer les outils. Pour enregistrer un outil, vous devez fournir 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

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 d'une commande

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

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();
document.modelContext.registerTool(addTodoTool, { signal: controller.signal });

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

Découvrir les outils

Pour afficher les outils disponibles, utilisez document.modelContext.getTools(). Cette méthode asynchrone renvoie une liste des outils auxquels le document appelant est autorisé à accéder.

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

// {
//   annotations: { readOnlyHint: false, untrustedContentHint: true },
//   description: "Add a new item to the to-do list",
//   inputSchema: '{"type":"object","properties":{"text":{"type":"string"}}}',
//   name: "addTodo",
//   origin: "https://example.com",
//   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 d'origine croisée, vous devez lister explicitement leurs origines dans l'option fromOrigins. Ce tableau n'accepte que les origines sécurisées.

Les outils des documents d'origine croisée ne sont inclus que si :

  1. L'origine de l'hébergement est indiqué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.

Exécuter l'outil

Pour exécuter manuellement un outil découvert dans getTools(), appelez document.modelContext.executeTool() avec des arguments d'entrée sous forme de chaîne JSON valide. 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 cadres peuvent écouter l'événement toolchange sur document.modelContext pour être avertis lorsque la liste des outils disponibles a changé.

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

iFrame inter-origines

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

Règles sur les autorisations

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

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

Exposition de l'origine

Par défaut, les outils ne sont pas disponibles pour les documents d'origine croisée. 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

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

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.