Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Imperative API

Alexandra Klepper

François Beaufort

Data publikacji: 18 maja 2026 r., ostatnia aktualizacja: 21 września 2026 r.

Film z wyjaśnieniem	Sieć	Rozszerzenia	Stan Chrome	Intencja
GitHub	Testowanie origin		Wyświetl	Zamiar przeprowadzenia eksperymentu

Za pomocą interfejsu WebMCP Imperative API możesz definiować wiele typów narzędzi za pomocą standardowego kodu JavaScript. Narzędzia mogą wykonywać różne funkcje, takie jak wprowadzanie danych do formularza, nawigacja po witrynie i zarządzanie stanem.

Zanim zaczniesz korzystać z tego interfejsu API, zapoznaj się z przykładami zastosowań.

Podawanie kontekstu modelu

Użyj interfejsu modelContext, aby zarejestrować narzędzia. Rejestracja narzędzia wymaga podania nazwy, opisu i schematu wejściowego z odpowiednimi właściwościami.

Użyj registerTool, aby dodać pojedyncze narzędzie do kontekstu modelu.

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

Sprawdzanie stanu zamówienia

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

Adnotacje do narzędzi (opcjonalnie)

Podczas rejestrowania narzędzia możesz dodać metadane we właściwości annotations. Te adnotacje pomagają agentom i przeglądarkom zrozumieć charakterystykę bezpieczeństwa narzędzia, oczekiwane skutki uboczne, wiarygodność danych wyjściowych i docelowych odbiorców:

readOnlyHint (wartość logiczna, domyślnie false): gdy wartość to true, oznacza to, że narzędzie tylko odczytuje informacje i nie modyfikuje stanu aplikacji ani systemu (np. wyszukuje katalog produktów lub pobiera stan zamówienia). Pomaga to agentom określić, czy narzędzie można bezpiecznie wywołać bez efektów ubocznych.
untrustedContentHint (wartość logiczna, domyślnie false): gdy true, oznacza, że dane wyjściowe narzędzia zawierają niezaufane dane z perspektywy autora narzędzia (np. treści użytkowników, opinie lub zewnętrzne dane internetowe). Sygnalizuje to agentowi i klientowi, że zwrócony ładunek wymaga zwiększonych środków bezpieczeństwa, takich jak oczyszczanie lub ograniczanie, aby ograniczyć pośrednie wstrzykiwanie promptów.
consequentialHint (wartość logiczna, domyślnie false): gdy wartość to true, oznacza to, że wykonanie narzędzia powoduje istotne, rzeczywiste lub nieodwracalne działania (np. rezerwację lotu, przelew pieniędzy lub usunięcie danych). Dzięki temu agenci i przeglądarki mogą wymuszać wyświetlanie użytkownikom obowiązkowych komunikatów z prośbą o potwierdzenie przed wykonaniem narzędzi o wysokim ryzyku, co zmniejsza ryzyko przypadkowego lub złośliwego błędnego przedstawienia intencji użytkownika.
debugging (wartość logiczna, domyślnie false, dostępna od Chrome 156): gdy wartość to true, oznacza to, że narzędzie jest przeznaczone specjalnie do sprawdzania i narzędzi deweloperskich (np. platform testowych lub pomocy AI w Narzędziach deweloperskich w Chrome), a nie do interakcji z użytkownikami. Dzięki temu agenty do zwykłych obciążeń i skierowane do użytkowników końcowych mogą odfiltrowywać narzędzia przeznaczone dla programistów.

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

Wyrejestrowywanie narzędzi

Narzędzie możesz usunąć za pomocą symbolu AbortSignal, jeśli jest przekazywane jako parametr opcjonalny.

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

Od wersji 153 Chrome możesz wyrejestrować narzędzie bez anulowania i przerywania trwających wykonań. Zapobiega to nieoczekiwanym efektom ubocznym podczas zarządzania cyklami życia narzędzi w frameworkach komponentów.

Obsługa anulowania narzędzia

Funkcja execute otrzymuje parametr AbortSignal o nazwie signal jako drugi argument, aby prawidłowo obsługiwać anulowanie wykonania zainicjowane przez użytkownika lub agenta. Przekazywanie tego sygnału do długotrwałych zadań asynchronicznych lub operacji sieciowych (np. fetch()) pomaga zapobiegać niepotrzebnej pracy, poprawia ogólne zarządzanie zasobami i pozwala uniknąć potencjalnych wycieków.

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

Odkrywanie narzędzi

Użyj document.modelContext.getTools(), aby pobrać dostępne narzędzia. Ta asynchroniczna metoda zwraca posortowaną alfabetycznie listę narzędzi, do których dokument wywołujący ma uprawnienia dostępu.

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

Domyślnie metoda getTools() zwraca tylko narzędzia z tej samej domeny zarejestrowane przez dokument wywołujący lub inne dokumenty z tej samej domeny w drzewie ramek. Aby pobrać narzędzia współdzielenia, musisz wyraźnie wymienić ich pochodzenie w opcji fromOrigins. Ta tablica obsługuje tylko bezpieczne źródła.

Narzędzia z dokumentów z innych źródeł są uwzględniane tylko wtedy, gdy:

Pochodzenie hostingu jest wymienione w opcji fromOrigins.
Narzędzie zostało wyraźnie udostępnione Twojej domenie.

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

Przykład pobierania narzędzi z elementu iframe i wykonywania ich w internetowym interfejsie czatu znajdziesz w demonstracji agenta strony WebMCP.

Uruchom narzędzie

Aby ręcznie wykonać narzędzie wykryte w getTools(), wywołaj document.modelContext.executeTool() z opcjonalnym obiektem JavaScript dla argumentów wejściowych, który można serializować do ciągu JSON. Ta metoda asynchroniczna zwraca wynik wykonania narzędzia lub wartość null, gdy zostanie wywołana nawigacja.

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

// 'Added to-do: Buy milk'

Możesz anulować oczekujące wykonanie narzędzia za pomocą parametru AbortSignal, gdy jest on przekazywany jako parametr opcjonalny.

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

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

Wydarzenia

Ramki mogą nasłuchiwać zdarzenia toolchange w document.modelContext, aby otrzymywać powiadomienia o zmianach na liście dostępnych narzędzi.

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

Elementy iframe z różnych domen

WebMCP obsługuje elementy iframe pochodzące z różnych źródeł, które korzystają zarówno z zasad dotyczących uprawnień, jak i z jawnego ograniczania dostępu do źródła.

Zasady dotyczące uprawnień

Rejestracja narzędzi jest domyślnie wyłączona w elementach iframe ze współdzieleniem. Strona musi delegować dostęp za pomocą tools zasad dotyczących uprawnień:

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

Narażenie źródła

Narzędzia są domyślnie niedostępne dla dokumentów z innych domen. W tablicy exposedTo w ramach registerTool możesz podać konkretne źródła, które mogą wyświetlać i uruchamiać narzędzie. Ta tablica obsługuje tylko bezpieczne źródła.

// https://partner.org

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

Obsługa React

React ma eksperymentalną obsługę WebMCP za pomocą pakietu usewebmcp. Jeśli aplikacja jest już napisana w React, możesz zarejestrować narzędzia za pomocą samodzielnych hooków powiązanych z cyklem życia montowania i odmontowywania komponentu. Hook useWebMCP zapewnia też wnioskowanie o typach na podstawie schematu i udostępnia lokalny stan wykonania.

Obsługa kątowa

Angular ma eksperymentalną obsługę WebMCP. Jeśli Twoja aplikacja jest już napisana w Angularze, możesz zarejestrować narzędzia powiązane z cyklem życia wstrzykiwania zależności aplikacji i przekształcić formularze sygnałowe w narzędzia WebMCP.

Zaangażuj się i prześlij opinię

WebMCP jest obecnie przedmiotem dyskusji i w przyszłości może ulec zmianie. Jeśli wypróbujesz ten interfejs API i będziesz mieć jakieś uwagi, chętnie je poznamy.

Przeczytaj wyjaśnienie dotyczące WebMCP, zadawaj pytania i bierz udział w dyskusji.
Przeczytaj sprawdzone metody dotyczące WebMCP.
Sprawdź implementację Chrome na stronie Chrome Status.
Dołącz do programu wcześniejszego dostępu, aby jako jeden z pierwszych poznać nowe interfejsy API i uzyskać dostęp do naszej listy mailingowej.
Jeśli masz uwagi na temat implementacji Chrome, zgłoś błąd w Chromium.

Wstecz

Rozpocznij

Dalej

Deklaratywny interfejs API