Imperative API

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

Veröffentlicht: 18. Mai 2026, zuletzt aktualisiert: 11. September 2026

Erklärvideo Web Erweiterungen Chrome-Status Absicht
GitHub Ursprungstest Ursprungstest Ansicht Absichtserklärung für Tests

Mit der WebMCP Imperative API können Sie viele Arten von Tools mit Standard-JavaScript definieren. Ihre Tools können verschiedene Funktionen ausführen, z. B. Formulareingabe, Websitenavigation und Statusverwaltung.

Lesen Sie sich vor der Verwendung dieser API die Beispielanwendungsfälle durch.

Kontext für das Modell angeben

Verwenden Sie die modelContext-Schnittstelle, um Tools zu registrieren. Für die Toolregistrierung sind ein Name, eine Beschreibung und ein Eingabeschema mit relevanten Attributen erforderlich.

Mit registerTool können Sie dem Modellkontext ein einzelnes Tool hinzufügen.

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

Bestellstatus abrufen

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

Tool-Anmerkungen (optional)

Wenn Sie ein Tool registrieren, können Sie in der Eigenschaft annotations Metadatenhinweise hinzufügen. Diese Hinweise helfen Agenten und Browsern, die Sicherheitsmerkmale, die erwarteten Nebenwirkungen und die Vertrauenswürdigkeit der Ausgabe eines Tools zu verstehen:

  • readOnlyHint (boolescher Wert, Standardwert: false): Wenn true, gibt an, dass das Tool nur Informationen liest und den Status der Anwendung oder des Systems nicht ändert (z. B. beim Suchen in einem Produktkatalog oder beim Abrufen des Bestellstatus). So können Kundenservicemitarbeiter feststellen, ob das Tool ohne Nebenwirkungen aufgerufen werden kann.
  • untrustedContentHint (boolescher Wert, Standardwert ist false): Wenn true, gibt dies an, dass die Ausgabe des Tools aus Sicht des Tool-Autors nicht vertrauenswürdige Daten enthält (z. B. von Nutzern erstellte Inhalte, Rezensionen oder externe Webdaten). Dies signalisiert dem Kundenservicemitarbeiter und dem Kunden, dass die zurückgegebene Nutzlast eine erhöhte Sicherheitsbehandlung erfordert, z. B. Bereinigung oder Begrenzung, um indirekte Prompt-Injections zu verhindern.
  • consequentialHint (boolescher Wert, Standardwert: false): Wenn true, gibt dies an, dass die Ausführung des Tools zu wichtigen, realen oder nicht rückgängig zu machenden Aktionen führt (z. B. einen Flug buchen, Geld überweisen oder Daten löschen). So können Agents und Browser obligatorische Aufforderungen zur Nutzerbestätigung erzwingen, bevor Tools mit hohem Risiko ausgeführt werden. Dadurch wird das Risiko einer versehentlichen oder böswilligen Falschdarstellung der Nutzerabsicht verringert.
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,
  },
  execute: async ({ flightId, passengers }) => {
    // Add your flight booking transaction logic here.
    return `Booked ${passengers} passenger(s) on flight ${flightId}.`;
  },
});

Tools abmelden

Sie können ein Tool mit AbortSignal entfernen, wenn es als optionaler Parameter übergeben wird.

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

Ab Chrome 153 können Sie die Registrierung eines Tools aufheben, ohne laufende Ausführungen abzubrechen. So werden unerwartete Nebeneffekte bei der Verwaltung von Tool-Lebenszyklen in Komponenten-Frameworks verhindert.

Umgang mit dem Abbruch von Tools

Die Funktion execute empfängt als zweites Argument einen AbortSignal-Parameter namens signal, um Ausführungsabbrüche, die vom Nutzer oder KI-Agenten initiiert wurden, ordnungsgemäß zu verarbeiten. Wenn Sie dieses Signal an asynchrone Langzeitaufgaben oder Netzwerkoperationen (z. B. fetch()) übergeben, können Sie unnötige Arbeit vermeiden, die allgemeine Ressourcenverwaltung verbessern und potenzielle Lecks vermeiden.

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 entdecken

Mit document.modelContext.getTools() können Sie verfügbare Tools abrufen. Diese asynchrone Methode gibt eine alphabetisch sortierte Liste der Tools zurück, auf die das aufrufende Dokument zugreifen darf.

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

// {
//   annotations: { consequentialHint: 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, …},
// }

Standardmäßig gibt getTools() nur Tools mit demselben Ursprung zurück, die vom aufrufenden Dokument oder anderen Dokumenten mit demselben Ursprung im Framebaum registriert wurden. Wenn Sie Tools für ursprungsübergreifende Anfragen abrufen möchten, müssen Sie ihre Ursprünge explizit in der Option fromOrigins auflisten. Dieses Array unterstützt nur sichere Ursprünge.

Tools aus ursprungsübergreifenden Dokumenten werden nur berücksichtigt, wenn:

  1. Der Hosting-Ursprung wird in der Option fromOrigins aufgeführt.
  2. Das Tool wurde explizit für Ihren Ursprung freigegeben.
// 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']
});

Im WebMCP Page Agent-Demo finden Sie ein Beispiel dafür, wie Sie Tools aus einem iFrame abrufen und in einer webbasierten Chat-Oberfläche ausführen.

Tool ausführen

Wenn Sie ein in getTools() gefundenes Tool manuell ausführen möchten, rufen Sie document.modelContext.executeTool() mit einem optionalen JavaScript-Objekt für Eingabeargumente auf, das in einen JSON-String serialisiert werden kann. Diese asynchrone Methode gibt das Ergebnis der Tool-Ausführung zurück oder „null“, wenn eine Navigation ausgelöst wird.

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

// 'Added to-do: Buy milk'

Sie können eine ausstehende Tool-Ausführung mit AbortSignal abbrechen, wenn dieser Parameter als optionaler Parameter übergeben wird.

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

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

Ereignisse

Frames können auf das toolchange-Ereignis in document.modelContext warten, um benachrichtigt zu werden, wenn sich die Liste der verfügbaren Tools geändert hat.

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

Ursprungsübergreifende iFrames

WebMCP unterstützt ursprungsübergreifende iFrames, die sowohl Berechtigungsrichtlinien als auch explizite Ursprungsbeschränkungen verwenden.

Richtlinie für Berechtigungen

Die Toolregistrierung ist in ursprungsübergreifenden iFrames standardmäßig deaktiviert. Auf einer Seite muss der Zugriff über die tools Berechtigungsrichtlinie delegiert werden:

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

Ursprungsrisiko

Tools sind für ursprungsübergreifende Dokumente standardmäßig nicht verfügbar. Mit dem exposedTo-Array in registerTool können Sie bestimmte Ursprünge auflisten, die ein Tool ansehen und ausführen dürfen. Dieses Array unterstützt nur sichere Ursprünge.

// https://partner.org

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

React-Unterstützung

React bietet experimentelle Unterstützung für WebMCP mit dem Paket usewebmcp. Wenn Ihre Anwendung bereits mit React geschrieben wurde, können Sie Tools mit eigenständigen Hooks registrieren, die an den Mount- und Unmount-Lebenszyklus Ihrer Komponente gebunden sind. Der useWebMCP-Hook bietet auch schemabasierte Typinferenz und macht den lokalen Ausführungsstatus verfügbar.

Angular-Unterstützung

Angular bietet experimentelle Unterstützung für WebMCP. Wenn Ihre Anwendung bereits mit Angular geschrieben wurde, können Sie Tools registrieren, die an den Dependency Injection-Lebenszyklus der Anwendung gebunden sind, und Ihre Signal Forms in WebMCP-Tools umwandeln.

Feedback geben

WebMCP wird derzeit aktiv diskutiert und kann sich in Zukunft ändern. Wenn Sie diese API ausprobieren und Feedback dazu haben, würden wir uns freuen, von Ihnen zu hören.

Zurück
Los gehts
Weiter
Deklarative API