Imperative API

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

Veröffentlicht: 18. Mai 2026, zuletzt aktualisiert: 16. Oktober 2026

Erklärvideo Web Erweiterungen Chrome-Status Absicht
GitHub Ursprungstest Ursprungstest Ansicht Intent to Experiment

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.

Bevor Sie diese API verwenden, sollten Sie sich die Beispielanwendungsfälle ansehen.

Modellkontext angeben

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

Verwenden Sie registerTool, um dem Modellkontext ein einzelnes Tool hinzuzufügen.

WebMCP

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-Annotationen (optional)

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

  • readOnlyHint (boolesch, Standardwert ist false): Wenn true, gibt dies an, dass das Tool nur Informationen liest und den Status der Anwendung oder des Systems nicht ändert (z. B. Suche in einem Produktkatalog oder Abrufen des Bestellstatus). So können Agenten feststellen, ob das Tool ohne Nebenwirkungen sicher 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 Agenten und dem Client, dass die zurückgegebene Nutzlast eine erhöhte Sicherheitsbehandlung erfordert, z. B. Bereinigung oder Begrenzung, um indirekte Prompt-Injection-Angriffe zu minimieren.
  • consequentialHint (boolesch, Standardwert: false): Wenn true, gibt dies an, dass die Ausführung des Tools zu signifikanten, realen oder nicht umkehrbaren Aktionen führt (z. B. Flug buchen, Geld überweisen oder Daten löschen). So können Agenten und Browser vor der Ausführung von Tools mit weitreichenden Folgen obligatorische Bestätigungsaufforderungen für Nutzer erzwingen. Das verringert das Risiko einer versehentlichen oder böswilligen Fehlinterpretation der Nutzerabsicht.
  • debugging (boolescher Wert, Standardwert ist false, verfügbar ab Chrome 156): Wenn true, gibt an, dass das Tool speziell für die Prüfung und Entwicklertools (z. B. Test-Frameworks oder KI-Unterstützung für Chrome-Entwicklertools) und nicht für Endnutzerinteraktionen entwickelt wurde. So können Agenten für allgemeine Zwecke und Endnutzer-Agenten entwicklerorientierte Tools herausfiltern.
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}.`;
  },
});

Beispiele dafür, wie sich Annotationen auf das Verhalten von Agenten auswirken können, finden Sie in der WebMCP-Beispielerweiterung.

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 und zu unterbrechen. So werden unerwartete Nebenwirkungen bei der Verwaltung von Tool-Lebenszyklen in Komponenten-Frameworks vermieden.

Abbruch des Tools verarbeiten

Die Funktion execute empfängt einen AbortSignal-Parameter namens signal als zweites Argument, um vom Nutzer oder Agenten initiierte Ausführungsabbrüche ordnungsgemäß zu verarbeiten. Wenn Sie dieses Signal an lang andauernde asynchrone Aufgaben oder Netzwerkvorgänge (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

Verwenden Sie document.modelContext.getTools(), um verfügbare Tools abzurufen. Diese asynchrone Methode gibt eine alphabetisch sortierte Liste von Tools zurück, auf die das aufrufende Dokument zugreifen darf.

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

Standardmäßig gibt getTools() nur Same-Origin-Tools zurück, die vom aufrufenden Dokument oder anderen Same-Origin-Dokumenten im Frame-Baum registriert wurden. Wenn Sie ursprungsübergreifende Tools abrufen möchten, müssen Sie deren 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 ist in der Option fromOrigins aufgeführt.
  2. Das Tool wurde explizit für Ihren Ursprung verfügbar gemacht.
// 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']
});

In der 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 können. Im Beispiel für eine WebMCP-Erweiterung sehen Sie, wie ein Agent in einer Browsererweiterung Tools in Same-Origin- und Cross-Origin-iFrames findet und ausführt.

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 Toolausfü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 Toolausfü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 das Ereignis toolchange auf document.modelContext überwachen, 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 explizites Origin Gating verwenden.

Berechtigungsrichtlinie

Die Toolregistrierung ist in ursprungsübergreifenden iFrames standardmäßig deaktiviert. Eine Seite muss den Zugriff mithilfe der tools-Berechtigungsrichtlinie delegieren:

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

Ursprungsrisiko

Tools sind für ursprungsübergreifende Dokumente standardmäßig nicht verfügbar. Mit dem Array exposedTo in registerTool können Sie bestimmte Ursprünge auflisten, die ein Tool aufrufen 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']
});

Unterstützung in gängigen JavaScript-Frameworks

React, Angular und Vue bieten experimentelle Unterstützung für WebMCP.

  • React: Verwenden Sie das Paket use-webmcp-tool. Registrieren Sie Tools mit dem useWebMCP-Hook, der an den Lebenszyklus des Ein- und Ausbindens Ihrer Komponente gebunden ist. Dieser Hook unterstützt die bedingte Toolregistrierung und normalisiert automatisch die Ausführungsergebnisse.
  • Angular: Registrieren Sie Tools, die an den Dependency-Injection-Lebenszyklus der Anwendung gebunden sind, und wandeln Sie Ihre Signal Forms in WebMCP-Tools um.
  • Vue: Verwenden Sie das useWebMCP-Composable aus dem @vueuse/core-Paket. Registrieren Sie Tools, die an den Lebenszyklus des aktuellen Vue-Bereichs gebunden sind. Die Vue-Implementierung unterstützt die reaktive und bedingte Toolregistrierung und normalisiert Ausführungsergebnisse automatisch.

Interagieren und Feedback geben

WebMCP wird derzeit aktiv diskutiert und kann sich in Zukunft ändern. Wenn Sie diese API ausprobieren und Feedback haben, freuen wir uns über Ihre Rückmeldung.

Zurück
Los gehts
Weiter
Deklarative API