API imperativa

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

Pubblicato: 18 maggio 2026, ultimo aggiornamento: 18 giugno 2026

Video esplicativo Web Estensioni Stato di Chrome Intenzione
GitHub Prova dell'origine Prova dell'origine Visualizza Intenzione di sperimentare

Puoi utilizzare l'API imperativa WebMCP per definire molti tipi di strumenti con JavaScript standard. Gli strumenti possono eseguire diverse funzioni, come l'inserimento di moduli, la navigazione del sito e la gestione dello stato.

Prima di utilizzare questa API, leggi gli esempi di casi d'uso.

Fornire il contesto del modello

Utilizza l'interfaccia modelContext per registrare gli strumenti. La registrazione dello strumento richiede un nome, una descrizione e uno schema di input con proprietà pertinenti.

Utilizza registertool per aggiungere un singolo strumento al contesto del modello.

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

Ottenere lo stato dell'ordine

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

Puoi rimuovere uno strumento con AbortSignal, se passato come parametro facoltativo.

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();

Scopri gli strumenti

Utilizza document.modelContext.getTools() per recuperare gli strumenti disponibili. Questo metodo asincrono restituisce un elenco in ordine alfabetico degli strumenti a cui il documento chiamante è autorizzato ad accedere.

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, ...},
// }

Per impostazione predefinita, getTools() restituisce solo gli strumenti della stessa origine registrati dal documento chiamante o da altri documenti della stessa origine nell'albero dei frame. Per recuperare gli strumenti multiorigine, devi elencare esplicitamente le loro origini nell'opzione fromOrigins. Questo array supporta solo origini sicure.

Gli strumenti dei documenti multiorigine vengono inclusi solo se:

  1. L'origine dell'hosting è elencata nell'opzione fromOrigins.
  2. Lo strumento è stato esposto esplicitamente alla tua 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']
});

Consulta la demo dell'agente di pagina WebMCP per un esempio di come recuperare gli strumenti da un iframe ed eseguirli all'interno di un'interfaccia di chat basata sul web.

Esegui strumento

Per eseguire manualmente uno strumento rilevato in getTools(), chiama document.modelContext.executeTool() con gli argomenti di input come stringa JSON valida. Questo metodo asincrono restituisce il risultato dell'esecuzione dello strumento o null quando viene attivata una navigazione.

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

// 'Added to-do: Buy milk'

Puoi annullare l'esecuzione di uno strumento in attesa con AbortSignal, se passato come parametro facoltativo.

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

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

Eventi

I frame possono rilevare l'evento toolchange su document.modelContext per ricevere una notifica quando l'elenco degli strumenti disponibili è cambiato.

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

Iframe multiorigine

WebMCP supporta gli iframe multiorigine che utilizzano sia le norme relative alle autorizzazioni sia il controllo esplicito delle origini.

Criteri relativi alle autorizzazioni

La registrazione degli strumenti è disattivata per impostazione predefinita negli iframe cross-origin. Una pagina deve delegare l'accesso utilizzando il tools criterio di autorizzazione:

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

Esposizione dell'origine

Per impostazione predefinita, gli strumenti non sono disponibili per i documenti multiorigine. Puoi utilizzare l'array exposedTo all'interno di registerTool per elencare le origini specifiche autorizzate a visualizzare ed eseguire uno strumento. Questo array supporta solo origini sicure.

// https://partner.org

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

Supporto di Angular

Angular offre il supporto sperimentale per WebMCP. Se la tua applicazione è già scritta con Angular, puoi registrare gli strumenti collegati al ciclo di vita dell'iniezione delle dipendenze dell'applicazione e trasformare i tuoi moduli di segnale in strumenti WebMCP.

Partecipare e condividere feedback

WebMCP è in fase di discussione e soggetto a modifiche in futuro. Se provi questa API e hai un feedback, saremo felici di riceverlo.