Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Imperative API

Alexandra Klepper

François Beaufort

Gepubliceerd: 18 mei 2026, Laatste update: 16 oktober 2026

Uitlegvideo	Web	Extensies	Chrome-status	Intentie
GitHub	Origin-proefperiode		Bekijken	Intentie om te experimenteren

Je kunt de WebMCP Imperative API gebruiken om veel soorten tools te definiëren met standaard JavaScript. Je tools kunnen verschillende functies uitvoeren, zoals formulierinvoer, sitenavigatie en statusbeheer.

Lees voordat je deze API gebruikt meer over voorbeelden van use cases.

Modelcontext geven

Gebruik de modelContext-interface om tools te registreren. Voor toolregistratie zijn een naam, beschrijving en invoerschema met relevante eigenschappen vereist.

Gebruik registerTool om één tool toe te voegen aan de modelcontext.

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

Bestelstatus opvragen

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

Toolannotaties (optioneel)

Als je een tool registreert, kun je metadata toevoegen aan de property annotations. Deze annotaties helpen agents en browsers de veiligheidskenmerken, verwachte bijwerkingen, betrouwbaarheid van de uitvoer en de beoogde doelgroep van een tool te begrijpen:

readOnlyHint (Booleaans, standaard ingesteld op false): Als deze parameter is ingesteld op true, geeft dit aan dat de tool alleen informatie leest en de status van de app of het systeem niet wijzigt (bijvoorbeeld een productcatalogus doorzoeken of de bestelstatus ophalen). Zo kunnen agents bepalen of de tool veilig kan worden aangeroepen zonder bijwerkingen.
untrustedContentHint (boolean, standaard ingesteld op false): Als true, geeft dit aan dat de uitvoer van de tool niet-vertrouwde gegevens bevat vanuit het perspectief van de auteur van de tool (bijvoorbeeld content van gebruikers, reviews of externe webgegevens). Dit geeft aan de agent en client aan dat de geretourneerde payload een strengere beveiligingsafhandeling vereist, zoals opschoning of afbakening, om indirecte promptinjectie te beperken.
consequentialHint (booleaans, standaard ingesteld op false): Als deze waarde true is, geeft dit aan dat de uitvoering van de tool leidt tot significante, echte of onomkeerbare acties (bijvoorbeeld een vlucht boeken, geld overmaken of gegevens verwijderen). Zo kunnen agents en browsers verplichte bevestigingsprompts voor gebruikers afdwingen voordat ze tools met een hoog risico uitvoeren. Dit vermindert het risico op onbedoelde of schadelijke verkeerde voorstelling van de gebruikersintentie.
debugging (boolean, standaard ingesteld op false, beschikbaar vanaf Chrome 156): Als deze waarde true is, geeft dit aan dat de tool specifiek is ontworpen voor inspectie- en tools voor ontwikkelaars (bijvoorbeeld testframeworks of AI-ondersteuning van Chrome DevTools) in plaats van interacties met eindgebruikers. Zo kunnen agents voor algemene doeleinden en eindgebruikers tools voor ontwikkelaars wegfilteren.

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

Ga naar de voorbeeldextensie van WebMCP voor voorbeelden van hoe annotaties het gedrag van de agent kunnen beïnvloeden.

Registratie van tools ongedaan maken

Je kunt een tool verwijderen met AbortSignal als deze wordt doorgegeven als optionele parameter.

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

Vanaf Chrome 153 kun je de registratie van een tool ongedaan maken zonder actieve uitvoeringen te annuleren en te onderbreken. Zo voorkom je onverwachte bijwerkingen als je de levenscycli van tools beheert in componentframeworks.

Omgaan met annulering van tool

De functie execute krijgt een AbortSignal-parameter met de naam signal als 2e argument om annuleringen van de uitvoering die door de gebruiker of agent zijn gestart, op een nette manier af te handelen. Als je dit signaal doorgeeft aan langdurige asynchrone taken of netwerkbewerkingen (zoals fetch()), voorkom je onnodig werk, verbeter je het algemene resourcebeheer en voorkom je mogelijke lekken.

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

Tools ontdekken

Gebruik document.modelContext.getTools() om beschikbare tools op te halen. Deze asynchrone methode retourneert een alfabetisch geordende lijst met tools waartoe het aanroepende document toegang heeft.

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

Standaard retourneert getTools() alleen tools met dezelfde oorsprong die zijn geregistreerd door het aanroepende document of andere documenten met dezelfde oorsprong in de framestructuur. Als je cross-origin tools wilt ophalen, moet je de oorsprongen expliciet vermelden in de optie fromOrigins. Deze matrix ondersteunt alleen beveiligde herkomsten.

Tools uit cross-origin documenten worden alleen opgenomen als:

De hostingbron staat in de optie fromOrigins.
De tool is expliciet blootgesteld aan je oorsprong.

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

Bekijk de demo van de WebMCP Page Agent voor een voorbeeld van hoe je tools uit een iframe ophaalt en uitvoert in een online chatinterface. Ga naar de voorbeeldextensie van WebMCP om te zien hoe een agent in een browserextensie tools vindt en uitvoert in same-origin en cross-origin iframes.

Tool uitvoeren

Als je een tool die is ontdekt in getTools() handmatig wilt uitvoeren, roep je document.modelContext.executeTool() aan met een optioneel JavaScript-object voor invoerargumenten dat kan worden geserialiseerd naar een json-tekenreeks. Deze asynchrone methode retourneert het resultaat van de uitvoering van de tool of null als er een navigatie wordt geactiveerd.

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

// 'Added to-do: Buy milk'

Je kunt een tooluitvoering in behandeling annuleren met AbortSignal als deze wordt doorgegeven als een optionele parameter.

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

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

Evenementen

Frames kunnen luisteren naar de gebeurtenis toolchange op document.modelContext om een melding te krijgen wanneer de lijst met beschikbare tools is gewijzigd.

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

Cross-origin iframes

WebMCP ondersteunt cross-origin iframes die zowel rechtenbeleid als expliciete oorsprongspoorten gebruiken.

Beleid voor rechten

Toolregistratie staat standaard uit in cross-origin iframes. Een pagina moet toegang delegeren via het tools Beleid voor rechten:

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

Blootstelling aan oorsprong

Tools zijn standaard niet beschikbaar voor cross-origin-documenten. Je kunt de matrix exposedTo binnen registerTool gebruiken om specifieke oorsprongen te vermelden die een tool mogen bekijken en uitvoeren. Deze matrix ondersteunt alleen beveiligde herkomsten.

// https://partner.org

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

React-ondersteuning

React heeft experimentele ondersteuning voor WebMCP met het pakket use-webmcp-tool. Als je app al is geschreven met React, kun je tools registreren met de hook useWebMCP die is gekoppeld aan de levenscyclus van de koppeling en ontkoppeling van je component. De tool ondersteunt ook voorwaardelijke toolregistratie en normaliseert automatisch de uitvoeringsresultaten.

Angular-ondersteuning

Angular heeft experimentele ondersteuning voor WebMCP. Als je app al is geschreven met Angular, kun je tools registreren die zijn gekoppeld aan de levenscyclus van de dependency injection van de app en je Signal Forms omzetten in WebMCP-tools.

Vue-ondersteuning

Vue heeft experimentele ondersteuning voor WebMCP met het pakket @vueuse/core. Als je app al is geschreven met Vue, kun je tools registreren met de useWebMCP composable die is gekoppeld aan de huidige levenscyclus van het Vue-bereik. Het ondersteunt ook reactieve en voorwaardelijke toolregistratie en normaliseert automatisch de uitvoeringsresultaten.

Betrokkenheid en feedback delen

WebMCP wordt actief besproken en kan in de toekomst worden gewijzigd. Als je deze API probeert en feedback hebt, horen we dat graag.

Lees de uitleg over WebMCP, stel vragen en neem deel aan de discussie.
Lees hoe je effectieve WebMCP-tools maakt en best practices voor WebMCP.
Controleer de implementatie voor Chrome op Chrome-status.
Neem deel aan het programma voor vroege preview voor een vroege blik op nieuwe API's en toegang tot onze mailinglijst.
Als je feedback hebt over de implementatie van Chrome, dien je een Chromium-bug in.

Aan de slag

Declaratieve API