API imperativa

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

Pubblicato il 18 maggio 2026, ultimo aggiornamento il 15 ottobre 2026

Esplicativo Web Estensioni Stato di Chrome Intenzione
GitHub Origin trial Origin trial Visualizza Intenzione di sperimentare

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

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

Fornisci 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

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

Visualizza lo stato dell'ordine

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

Annotazioni dello strumento (facoltative)

Quando registri uno strumento, puoi aggiungere metadati nella proprietà annotations. Queste annotazioni aiutano gli agenti e i browser a comprendere le caratteristiche di sicurezza, gli effetti collaterali previsti, l'affidabilità dell'output e il pubblico di destinazione di uno strumento:

  • readOnlyHint (valore booleano, il valore predefinito è false): se true, indica che lo strumento legge solo le informazioni e non modifica lo stato dell'applicazione o del sistema (ad esempio, la ricerca di un catalogo di prodotti o il recupero dello stato dell'ordine). Questo aiuta gli agenti a determinare se lo strumento può essere chiamato in sicurezza senza effetti collaterali.
  • untrustedContentHint (valore booleano, il valore predefinito è false): se true, indica che l'output dello strumento contiene dati non attendibili dal punto di vista dell'autore dello strumento (ad esempio, contenuti generati dagli utenti, recensioni o dati web esterni). Questo indica all'agente e al client che il payload restituito richiede una gestione della sicurezza più elevata, ad esempio la sanificazione o la delimitazione, per mitigare l'iniezione indiretta di prompt.
  • consequentialHint (valore booleano, il valore predefinito è false): se true, indica che l'esecuzione dello strumento comporta azioni significative, reali o non reversibili (ad esempio, la prenotazione di un volo, il trasferimento di denaro o l'eliminazione di dati). In questo modo, gli agenti e i browser possono applicare i prompt di conferma obbligatori dell'utente prima di eseguire strumenti ad alto rischio, mitigando il rischio di rappresentazione errata accidentale o dannosa dell'intenzione dell'utente.
  • debugging (valore booleano, il valore predefinito è false, disponibile da Chrome 156): se true, indica che lo strumento è progettato specificamente per l'ispezione e gli strumenti per sviluppatori (ad esempio, framework di test o assistenza AI di Chrome DevTools) anziché per le interazioni con gli utenti finali. In questo modo, gli agenti per uso generico e per gli utenti finali possono filtrare gli strumenti incentrati sugli sviluppatori.
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}.`;
  },
});

Per esempi di come le annotazioni possono influenzare il comportamento degli agenti, consulta l'estensione WebMCP di esempio.

Annulla la registrazione degli strumenti

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

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

A partire da Chrome 153, puoi annullare la registrazione di uno strumento senza annullare e interrompere le esecuzioni in corso. In questo modo si evitano effetti collaterali imprevisti durante la gestione dei cicli di vita degli strumenti nei framework dei componenti.

Gestisci l'annullamento dello strumento

La funzione execute riceve un parametro AbortSignal denominato signal come secondo argomento per gestire correttamente le annullamenti dell'esecuzione avviati dall'utente o dall'agente. Il passaggio di questo segnale a attività asincrone o operazioni di rete a lunga esecuzione (ad esempio fetch()) aiuta a evitare lavoro non necessario, migliora la gestione complessiva delle risorse ed evita potenziali perdite.

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

Scopri gli strumenti

Utilizza document.modelContext.getTools() per recuperare gli strumenti disponibili. Questo metodo asincrono restituisce un elenco ordinato alfabeticamente di strumenti a cui il documento chiamante è autorizzato ad accedere.

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

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 di 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. Consulta l'estensione WebMCP di esempio per scoprire come un agente in un'estensione del browser trova ed esegue strumenti in iframe della stessa origine e multiorigine.

Esegui lo strumento

Per eseguire manualmente uno strumento rilevato in getTools(), chiama document.modelContext.executeTool() con un oggetto JavaScript facoltativo per gli argomenti di input serializzabile in una stringa JSON. 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 ascoltare 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 policy di autorizzazione sia il gating esplicito dell'origine.

Policy di autorizzazione

Per impostazione predefinita, la registrazione degli strumenti è disattivata negli iframe multiorigine. Una pagina deve delegare l'accesso utilizzando la tools policy 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

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

Supporto di React

React ha un supporto sperimentale per WebMCP utilizzando il pacchetto usewebmcp. Se la tua applicazione è già scritta con React, puoi registrare gli strumenti utilizzando hook autonomi collegati al ciclo di vita di montaggio e smontaggio del componente. L'hook useWebMCP fornisce anche l'inferenza del tipo basata sullo schema ed espone lo stato di esecuzione locale.

Supporto di Angular

Angular ha un 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 moduli di segnale in strumenti WebMCP.

Supporto di Vue

Vue ha un supporto sperimentale per WebMCP utilizzando il pacchetto @vueuse/core. Se la tua applicazione è già scritta con Vue, puoi registrare gli strumenti utilizzando il composable useWebMCP collegato al ciclo di vita dell'ambito Vue corrente. Supporta anche la registrazione di strumenti reattivi e condizionali e normalizza automaticamente i risultati dell'esecuzione.

Interagisci e condividi il tuo feedback

WebMCP è in fase di discussione attiva ed è soggetto a modifiche in futuro. Se provi questa API e hai feedback, non esitare a comunicarcelo.

Indietro
Per iniziare
Avanti
API dichiarativa