Agentische JavaScript-Tools

Die Imperative API verwendet document.modelContext.registerTool(), um JavaScript-Tools programmatisch zu definieren. Das ist ideal für Single-Page-Anwendungen (SPAs), bei denen Tools je nach aktueller Route oder Nutzerstatus hinzugefügt oder entfernt werden müssen.

WebMCP basiert auf einer Producer/Consumer-Architektur:

• Webseiten sind Tool-Produzenten: Sie definieren und registrieren Tools mit document.modelContext.registerTool(). Das ist alles, was auf einer Webseite implementiert werden muss. Sie müssen getTools() oder executeTool() nicht auf der Seite aufrufen, um Tools für KI-Agenten verfügbar zu machen.
• Browser- und Erweiterungs-Agents sind die primären Nutzer: Agents, die vom oder über den Browser bereitgestellt werden, einschließlich des integrierten Agents des Browsers, Browsererweiterungen, Entwicklertools und Assistenten auf Systemebene, finden und rufen registrierte Tools Out-of-Band über interne Plattformmechanismen auf.
• In-Page-Agenten und Test-Harnische: getTools() und executeTool() sind speziell für In-Page-JavaScript-Assistenten (z.B. ein eingebettetes Chat-Widget oder <iframe>) und automatisierte Test-Suites gedacht, die Tools direkt im Seitenkontext erkennen und aufrufen müssen.

Registrierung und Lebenszyklus

Tools werden registriert, indem ein Tooldefinitionsobjekt und ein optionales Optionsobjekt (ModelContextRegisterToolOptions) übergeben werden. Das Optionsobjekt unterstützt zwei optionale Elemente:

• signal: Ein AbortSignal, mit dem die Registrierung des Tools aufgehoben wird, wenn es nicht mehr benötigt wird.
• exposedTo: Ein Array von Ursprungsstrings, die steuern, welche Dokumente im Dokumentbaum das Tool über Framegrenzen hinweg erkennen und ausführen dürfen.

Lebenszyklusverwaltung mit AbortController

WebMCP bietet keine unregisterTool()-Methode. Wenn Sie die Registrierung eines Tools aufheben möchten, müssen Sie bei der Registrierung ein AbortSignal übergeben und dieses Signal abbrechen, wenn das Tool nicht mehr benötigt wird.

const controller = new AbortController();

await document.modelContext.registerTool({
  name: "get_user_preferences",
  description: "Retrieves the user's saved preferences.",
  inputSchema: { type: "object", properties: {} },
  execute() {
    const prefs = localStorage.getItem("user_prefs");
    return prefs ? JSON.parse(prefs) : { theme: "light" };
  },
  annotations: { readOnlyHint: true }
}, { signal: controller.signal });

// To unregister the tool (e.g., on component unmount):
controller.abort();

Durch das Abbrechen des Registrierungssignals wird nur die Registrierung des Tools aufgehoben. Bereits laufende Ausführungen werden nicht abgebrochen. Tools, die lang andauernde Aufgaben starten, müssen auch das unten beschriebene Signal pro Ausführung berücksichtigen. Andernfalls bleiben nach der Abmeldung verwaiste Anfragen und veraltete UI-Updates zurück.

Ursprungsübergreifende Tool-Verfügbarkeit mit exposedTo steuern

Standardmäßig ist ein registriertes Tool nur für das registrierende Dokument und Frames mit demselben Ursprung sichtbar. Wenn Ihre Anwendung in ein <iframe> eingebettet ist (oder Widgets von Drittanbietern einbettet) und Sie übergeordnete oder gleichgeordnete Frames benötigen, um das Tool zu finden und aufzurufen, geben Sie die zulässigen Ursprünge mit exposedTo an.

const controller = new AbortController();

await document.modelContext.registerTool({
  name: "get_cart_items",
  description: "Retrieves items currently in the user's shopping cart.",
  inputSchema: { type: "object", properties: {} },
  async execute(input, { signal }) {
    return await cartService.getItems({ signal });
  },
  annotations: { readOnlyHint: true },
}, {
  signal: controller.signal,
  exposedTo: ["https://checkout.example.com"],
});

• Gegenseitiges Opt-in: Die ursprungsübergreifende Toolerkennung ist ein beidseitiges Opt-in. Der Frame des Toolanbieters autorisiert den Ursprung des Nutzers über exposedTo und der Frame des Nutzers muss diesen Anbieterursprung explizit über getTools({ fromOrigins: [...] }) anfordern. Ohne fromOrigins fragt getTools() nur Dokumente mit demselben Ursprung ab.
• Ursprungsabgleich: Der Ursprung des registrierenden Dokuments hat immer Zugriff. In exposedTo angegebene Ursprünge erhalten die Berechtigung, das Tool über document.modelContext.getTools({ fromOrigins: [...] }) zu finden und über document.modelContext.executeTool() auszuführen.
• Sicherheitsanforderung: Jeder Ursprung in exposedTo MUSS potenziell vertrauenswürdig sein (HTTPS oder localhost). Wenn ein ungültiger oder unsicherer Ursprung übergeben wird, wird registerTool() mit einem SecurityError abgelehnt.
• Geltungsbereich: exposedTo steuert die In-Page, dokumentübergreifende Erkennung über Frames im Dokumentbaum hinweg.

Parameter definieren

Parameter (params) werden mit der Property inputSchema definiert. Dies muss ein JSON-Schema-Objekt sein, das die strukturierten Daten beschreibt, die das Tool erwartet.

await document.modelContext.registerTool({
  name: "calculate_area",
  description: "Calculates the area of a rectangle.",
  inputSchema: {
    type: "object",
    properties: {
      width: { type: "number", description: "The width of the rectangle." },
      height: { type: "number", description: "The height of the rectangle." }
    },
    required: ["width", "height"]
  },
  execute(input) {
    // input is { width: 10, height: 20 }
    return input.width * input.height;
  },
  annotations: { readOnlyHint: true }
});

Tool- und Parameterbeschreibungen schreiben

Der KI-Agent erhält bereits die vollständige inputSchema. In der description muss also nur angegeben werden, was das Tool tut und wann es verwendet werden soll. Wiederholen Sie darin KEINE Parameternamen, Typen, enum-Werte, Standardwerte oder Limits. Deklarieren Sie diese stattdessen im Schema (enum, default, minimum/maximum). Für Parameterbeschreibungen gilt dieselbe Regel: Geben Sie an, was der Wert bedeutet, nicht seinen Typ oder die zulässigen Werte.

Der Browser validiert Argumente nicht anhand von inputSchema und wendet keine default-Werte an. Beides muss also in execute erfolgen.

const SORT_ORDERS = ["newest", "price_low_to_high"];

await document.modelContext.registerTool({
  name: "search_products",
  // Don't list the sort orders here, even via SORT_ORDERS: `enum` already does.
  description: "Searches the product catalog by keyword. Use when the user wants to find or compare products.",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "Words to search for." },
      sort: { type: "string", enum: SORT_ORDERS, default: "newest", description: "Order of the results." },
    },
    required: ["query"],
  },
  async execute({ query, sort = "newest" }, { signal }) {
    if (typeof query !== "string" || !SORT_ORDERS.includes(sort)) {
      return { error: "Pass a search query and a supported sort order.", sortOrders: SORT_ORDERS };
    }
    return await productService.search({ query, sort }, { signal });
  },
  annotations: { readOnlyHint: true },
});

Ausführungsmuster

Der Callback execute empfängt immer zwei Argumente: das Eingabeobjekt und ein Optionsobjekt mit einem AbortSignal – execute(inputObject, { signal }).

Verwendung von async execute

Verwenden Sie async, wenn das Tool Vorgänge umfasst, die ein Promise zurückgeben oder deren Ausführung Zeit in Anspruch nimmt:

• Netzwerkaufrufe: Daten von einer API abrufen.
• Asynchroner Speicher: Zugriff auf IndexedDB.
• Externe Ereignisse: Warten auf eine bestimmte Statusänderung oder das Ende einer Animation.

async execute(input, { signal }) {
  const response = await fetch(`/api/data/${input.id}`, { signal });
  return await response.json();
}

Wann execute (synchron) verwendet werden sollte

Verwenden Sie eine synchrone Standardfunktion für sofortige Vorgänge. Ein synchrones Tool wird bis zum Ende ausgeführt, bevor der Abbruch erkannt werden kann. Daher kann es das Signal ignorieren:

• Reine Logik: Mathematik, Filtern oder Sortieren von Daten, die sich bereits im Arbeitsspeicher befinden.
• Synchroner Status: Lesen aus localStorage oder einem synchronen Statusmanager.

execute(input) {
  return input.items.filter(item => item.active);
}

Fehler in execute verarbeiten

Wenn execute einen Fehler ausgibt (oder ein abgelehntes Promise zurückgibt), erhält der Agent nur einen allgemeinen Ausführungsfehler. Die Fehlermeldung wird nicht an den Kundenservicemitarbeiter weitergeleitet. Wenn Ihr Tool einen behebbaren Fehler feststellt (z. B. ungültige Eingabe, fehlende Elemente oder fehlgeschlagener HTTP-Status), NICHT throw new Error(...). Geben Sie stattdessen eine strukturierte Fehlernutzlast über den normalen Rückgabewert des Tools zurück, damit der KI-Agent die Diagnosedetails erhält und sich selbst korrigieren oder den Vorgang wiederholen kann:

execute({ itemName }) {
  const item = menuItems.find((entry) => entry.name.toLowerCase() === itemName.toLowerCase());
  if (!item) {
    // Return the error as a value instead of throwing, so the agent receives the message:
    return {
      error: `Menu item "${itemName}" not found.`,
      availableItems: menuItems.map((entry) => entry.name),
    };
  }
  return item;
}

Nur dann erneut auslösen, wenn die Ausführung abgebrochen wurde (signal.aborted ist true).

Laufende Ausführungen abbrechen

Die Stornierung wird vom Nutzer oder vom Kundenservicemitarbeiter initiiert. OBLIGATORISCH: Jedes Tool, das Netzwerkanfragen oder andere asynchrone Aufgaben mit langer Ausführungszeit ausführt, MUSS signal berücksichtigen. Andernfalls verbrauchen abgebrochene Ausführungen weiterhin Ressourcen und können veraltete Daten in die Benutzeroberfläche schreiben, nachdem der Agent fortgefahren ist.

• APIs, die ein Signal akzeptieren (fetch()-, addEventListener()-, ReadableStream-Reader): signal wird direkt weitergegeben.
• APIs, die das nicht tun (setTimeout, setInterval, Abfrageschleifen, Pipelines mit vielen await): Rufen Sie signal.throwIfAborted() zwischen den Schritten auf und/oder lehnen Sie bei signal.addEventListener('abort', ...) ab. Timer akzeptieren kein Signal. Sie müssen sie daher selbst im Abort-Listener löschen.

await document.modelContext.registerTool({
  name: "fetch_tool",
  description: "Fetch the text content of a URL and show it on the page.",
  inputSchema: {
    type: "object",
    properties: {
      url: { type: "string", description: "The URL to fetch" },
      priority: {
        type: "string",
        enum: ["high", "low", "auto"],
        description: "Relative network priority for the request",
      },
    },
    required: ["url"],
  },
  execute: async ({ url, priority }, { signal }) => {
    const output = document.querySelector("pre");
    output.textContent = "Loading…";
    try {
      // Passing `signal` aborts the network request the moment execution is cancelled.
      const response = await fetch(url, { priority, signal });
      if (!response.ok) {
        output.textContent = "";
        return { error: `Request failed with status ${response.status}` };
      }
      const text = await response.text();
      output.textContent = text;
      return text;
    } catch (err) {
      // Roll back the UI state this execution set, so a cancelled run leaves no trace.
      output.textContent = "";
      if (signal.aborted) {
        // The execution was cancelled: re-throw instead of returning an error value.
        throw err;
      }
      // Return other errors as a value instead of throwing, so the agent receives the message.
      return { error: err instanceof Error ? err.message : String(err) };
    }
  },
  annotations: { readOnlyHint: true }
});

Tools zum Melden von Inhalten mit schwerwiegenden Folgen

Seit Chrome 154 unterstützt annotations consequentialHint. Legen Sie den Wert für Tools, die risikoreiche, unumkehrbare oder reale Aktionen ausführen, auf true fest, z. B. für das Buchen von Reisen, das Überweisen von Geld, das Senden von Nachrichten oder das Löschen von Daten. Sie signalisiert KI-Agenten, dass sie vor der Ausführung eine explizite Bestätigung des Nutzers einholen müssen.

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'],
  },
  execute: async ({ flightId, passengers }, { signal }) => {
    // Forward `signal` to the transaction API to honor cancellation:
    return await bookFlightReservation({ flightId, passengers }, { signal });
  },
  annotations: {
    readOnlyHint: false,      // This tool mutates state (it makes a booking).
    consequentialHint: true,  // Spends money and is not trivially reversible.
    untrustedContentHint: false, // Output is first-party data, not third-party content.
  }
});

OBLIGATORISCH: Behandle consequentialHint als Hinweis, nicht als Durchsetzungsmechanismus. Die Ausführung wird nicht blockiert und Browser, die den Hinweis nicht unterstützen, zeigen überhaupt keine Aufforderung an. Behalten Sie die In-App-Bestätigung bei, die für die Aktion bereits erforderlich ist.

Debugging-Tools für die Kennzeichnung

Seit Chrome 156 unterstützt annotations debugging. Setzen Sie annotations.debugging auf true für Tools, die für die Fehlerbehebung und Entwicklertools und nicht für Endnutzeraufgaben entwickelt wurden. Beispiele: Dump des internen App-Status, Umschalten von Funktions-Flags oder Seeding von Testdaten. So können Agenten Tools, die nur für Entwickler gedacht sind, von Tools unterscheiden, die für den Nutzer gedacht sind. Der Standardwert ist false. In-Page-Agenten und Test-Harnische können sie über getTools() aus RegisteredTool.annotations.debugging lesen.

await document.modelContext.registerTool({
  name: "dump_app_state",
  description: "Returns a snapshot of the internal application store for debugging.",
  execute() {
    return appStore.getState();
  },
  annotations: {
    readOnlyHint: true, // Only reads state.
    debugging: true,    // Developer tooling, not an end-user action.
  }
});

In-Page-Agenten und Tests (getTools und executeTool)

Webseiten benötigen weder getTools() noch executeTool(), um KI-Agenten Tools zur Verfügung zu stellen. Der einfache Aufruf von document.modelContext.registerTool() reicht aus, damit Browser-Agenten, Browsererweiterungen, Entwicklertools und Assistenten auf Systemebene Ihre Tools Out-of-Band erkennen und ausführen können.

Die Methoden getTools() und executeTool() sind speziell für Consumer gedacht, die in der JavaScript-Umgebung ausgeführt werden:

1. In-Page-JavaScript-Agenten: Ein KI-Assistent, ein Copilot-Widget oder eine Chat-Oberfläche, die direkt in die Seite eingebettet ist (oder in einem <iframe> ausgeführt wird) und ermitteln muss, welche Tools die umgebende Seite oder die zugänglichen Frames im Dokumentbaum bieten, und diese im Namen des Nutzers aufrufen muss.
2. Automatisierte Tests und Debugging: Test-Suites (wie Playwright, Vitest oder Unit-Tests im Browser), die registrierte Tool-Metadaten prüfen und Agent-Tool-Aufrufe simulieren, ohne dass eine externe LLM-Live-Umgebung erforderlich ist.

Verfügbare Tools mit getTools() erkennen

In-Page-Agenten rufen document.modelContext.getTools() auf, um ein Array von RegisteredTool-Objekten aus dem aktuellen Dokument und allen zugänglichen Frames im Dokumentbaum abzurufen.

Seit Chrome 155 wird RegisteredTool.inputSchema direkt als JavaScript-Objekt zurückgegeben (eine tiefe Kopie des bei der Registrierung angegebenen Schemas). Wenn Sie dieses Objekt ändern, wird das tatsächliche Schema des registrierten Tools nicht geändert.

// Example: An in-page AI assistant discovering tools available on the page:
const tools = await document.modelContext.getTools();

// In-page agents can listen for tools being registered or unregistered dynamically:
document.modelContext.addEventListener("toolchange", async () => {
  const updatedTools = await document.modelContext.getTools();
  console.log(`Active tools updated: ${updatedTools.map((t) => t.name).join(", ")}`);
});

Wenn Sie Tools finden möchten, die in untergeordneten iFrames mit unterschiedlichem Ursprung registriert sind (die bei der Registrierung explizit Zugriff über exposedTo gewähren müssen), übergeben Sie fromOrigins im Options-Dictionary:

// Query tools registered in the embedded cart frame that exposed them to this checkout origin:
const cartTools = await document.modelContext.getTools({
  fromOrigins: ["https://cart.example.com"],
});

Tools mit executeTool() aufrufen

In-Page-Agenten und Testskripts rufen document.modelContext.executeTool(tool, inputObject, options) auf, um ein registriertes Tool auszuführen. Das Tool wird für das Dokument ausgeführt, in dem es registriert wurde. Das Promise wird in das stringifizierte Ergebnis aufgelöst, das vom execute-Callback des Tools zurückgegeben wird.

Seit Chrome 155 akzeptiert executeTool() ein einfaches JavaScript-Objekt direkt für inputObject, was dem Eingabeformat entspricht, das der execute-Callback Ihres Tools empfängt.

// 1. Discover the tool (typically done during agent initialization or test setup):
const tools = await document.modelContext.getTools();
const areaTool = tools.find((t) => t.name === "calculate_area");

if (areaTool) {
  const controller = new AbortController();
  // Example input payload matching the tool's inputSchema:
  const inputObject = { width: 10, height: 20 };
  const options = { signal: controller.signal };

  // 2. Pass input arguments as a JavaScript object, with a JSON string fallback for Chrome <155:
  let resultString;
  try {
    resultString = await document.modelContext.executeTool(areaTool, inputObject, options);
  } catch (err) {
    if (err?.message?.startsWith("Failed to parse input")) {
      resultString = await document.modelContext.executeTool(
        areaTool,
        JSON.stringify(inputObject),
        options
      );
    } else {
      // Re-throw real tool execution or cancellation errors:
      throw err;
    }
  }

  console.log("Execution output string:", resultString);
}

Das zurückgegebene Promise wird in folgenden Fällen abgelehnt:

• inputObject ist kein Objekt oder kann nicht in einen JSON-String serialisiert werden (z.B. zirkuläre Referenzen oder BigInt-Werte). Beachten Sie, dass Werte, die bei der JSON-Serialisierung weggelassen werden (z. B. Funktionen und undefined), aus dem vom Tool empfangenen Objekt weggelassen werden, anstatt eine Ablehnung zu verursachen.
• Die Ausführung wird über options.signal abgebrochen.
• Das Tool wurde vor der Ausführung abgemeldet oder es ist ein nicht behandelter Laufzeitfehler aufgetreten.

Tool Factory-Muster

Verwenden Sie Factory-Funktionen, um Kontext (z. B. Speicher oder Anwendungsinstanzen) an Ihre Tools zu übergeben.

export function createInventoryTool(inventoryManager) {
  return {
    name: "get_inventory",
    description: "Lists items in the inventory.",
    inputSchema: { type: "object", properties: {} },
    execute() {
      return inventoryManager.getItems();
    },
    annotations: { readOnlyHint: true }
  };
}

TypeScript-Typen

In TypeScript-Projekten sollten Sie Deklarationen für document.modelContext NICHT manuell schreiben. Installieren Sie das offizielle webmcp-types-Paket (npm install --save-dev webmcp-types) und fügen Sie es zu tsconfig.json hinzu, da es nicht automatisch erkannt wird:

{
  "compilerOptions": {
    "types": ["webmcp-types"]
  }
}

• document.modelContext ist als optional deklariert. Schützen Sie es daher vor der Verwendung mit if (document.modelContext).
• Bei einem Inline-inputSchema wird der Eingabetyp execute aus dem Schema abgeleitet.
• Benannte Typen wie WebMCP.ModelContextTool sind global (kein Import erforderlich) und nützlich für die Typisierung von Tool-Factories.

Framework-Support

OBLIGATORISCH: Wenn die App React, Angular oder Vue verwendet, registrieren Sie die Tools über die offizielle WebMCP-Integration des jeweiligen Frameworks (siehe unten). Rufen Sie document.modelContext.registerTool() NICHT über Komponenten auf und schreiben Sie keinen eigenen Lebenszyklus-Wrapper. Jede Integration übernimmt bereits die Featureerkennung, die AbortSignal-Bereinigung und die Eingrenzung von Tools auf den Lebenszyklus der Komponente oder des Injectors. Diese APIs sind experimentell. Suchen Sie daher vor dem Schreiben von Code die aktuelle Signatur in den Typen oder der Dokumentation des Pakets.

Alle Regeln in diesem Leitfaden gelten auch, wenn Sie diese Integrationen verwenden:

• Behalten Sie die Form der Tooldefinition bei: name, description, inputSchema, execute(input, { signal }) und annotations.
• Beachten Sie die Regeln für Beschreibungen und Anmerkungen.
• Eingabe validieren und Standardwerte in execute anwenden.
• Übergeben Sie signal an lang andauernde Aufgaben.
• Wenn Sie ein Tool nur manchmal anbieten möchten, übergeben Sie enabled (React, Vue). Verpacken Sie den Hook oder den Aufruf der zusammensetzbaren Funktion NICHT in eine Bedingung.
• Integrationen können Ergebnisse und Fehler verpacken (z. B. als { content, isError }). Lesen Sie die Dokumentation der Integration, bevor Sie sich darauf verlassen, wie Fehler den Agenten erreichen.

API-Hinweise

• annotations: (Optional) Ein Wörterbuch für Tool-Metadaten.
  • readOnlyHint: (Optional) Setzen Sie diesen Wert auf true, wenn das Tool keinen Status ändert und nur Daten liest. So können KI-Agenten entscheiden, wann es sicher ist, das Tool aufzurufen.
  • consequentialHint: (Optional, Chrome 154+) Legen Sie true für wichtige, unumkehrbare oder reale Aktionen fest, damit Agenten zuerst die Bestätigung des Nutzers anfordern.
  • untrustedContentHint: (Optional) Legen Sie diesen Wert auf true fest, wenn das Tool Inhalte zurückgibt, die nicht von Ihrer Website kontrolliert werden, z. B. von Nutzern generierten Text oder API-Antworten von Drittanbietern.
  • debugging: (Optional, Chrome 156+) Legen Sie true fest, wenn das Tool für Debugging und Entwicklertools gedacht ist, nicht für Endnutzeraufgaben. Die Standardeinstellung ist false.
• Registrierungsoptionen:
  • signal: (Optional) Ein AbortSignal, mit dem die Registrierung des Tools aufgehoben wird, wenn es nicht mehr benötigt wird.
  • exposedTo: (Optional) Ein Array von Strings mit sicheren Ursprüngen, die steuern, welche Dokumente im Dokumentbaum das Tool über Frame-Grenzen hinweg erkennen und ausführen dürfen.
• Optionen für die Tool-Erkennung (ModelContextGetToolOptions):
  • fromOrigins: (Optional) Ein Array von Strings mit sicheren Ursprüngen, die in zugänglichen Frames abgefragt werden sollen. Wenn Sie getTools() ohne fromOrigins aufrufen, werden nur Dokumente mit demselben Ursprung abgefragt.
• Rückgabeformat: Die Funktion execute kann einen beliebigen JSON-serialisierbaren Wert (Objekt, Array, String, Zahl, boolescher Wert) zurückgeben. Die Nachricht einer Ausnahme, die von execute ausgelöst wird, wird nicht an den KI-Agenten weitergeleitet. Geben Sie daher umsetzbare Fehler als strukturierte Fehler-Nutzlasten (z. B. { error: "..." }) über den Rückgabewert des Tools zurück, damit der KI-Agent sie lesen und darauf reagieren kann.
• Sicherer Kontext: WebMCP erfordert HTTPS. Alle Ursprünge in exposedTo und fromOrigins müssen ebenfalls potenziell vertrauenswürdig sein.
• Eingestellt/Entfernt: navigator.modelContext (in Chromium 150 eingestellt), unregisterTool(), provideContext() und clearContext() werden nicht mehr unterstützt.

Fallback-Strategien

Die WebMCP Imperative API sollte mit der Funktionserkennung verwendet werden, um die Kompatibilität mit Browsern zu gewährleisten, die WebMCP noch nicht unterstützen.

if ('modelContext' in document) {
  // Register tools
}