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: 16 października 2026 r.

Wyjaśnienie	Sieć	Rozszerzenia	Stan Chrome	Intencja
GitHub	Wersja próbna origin		Wyświetl	Zamiar przeprowadzenia eksperymentu

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

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

Podaj kontekst modelu

Do rejestrowania narzędzi używaj interfejsu modelContext. Rejestracja narzędzia wymaga nazwy, opisu i schematu wejściowego z odpowiednimi właściwościami.

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

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 dotyczące 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 efekty uboczne, wiarygodność danych wyjściowych i docelowych odbiorców:

readOnlyHint (wartość logiczna, domyślnie false): gdy ma wartość true, wskazuje, ż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 ma wartość true, wskazuje, że dane wyjściowe narzędzia zawierają dane niezaufane z perspektywy autora narzędzia (np. treści generowane przez użytkowników, opinie lub zewnętrzne dane internetowe). Sygnalizuje to agentowi i klientowi, że zwrócone dane wymagają zwiększonego bezpieczeństwa, np. oczyszczenia lub rozdzielenia, aby ograniczyć pośrednie wstrzykiwanie promptów.
consequentialHint (wartość logiczna, domyślnie false): gdy ma wartość true, wskazuje, że wykonanie narzędzia powoduje istotne, rzeczywiste lub nieodwracalne działania (np. rezerwację lotu, przelew pieniędzy lub usunięcie danych). Dzięki temu agenty i przeglądarki mogą wymuszać wyświetlanie obowiązkowych próśb o potwierdzenie przez użytkownika przed wykonaniem działań za pomocą 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 ma wartość true, wskazuje, że narzędzie jest przeznaczone specjalnie do inspekcji i narzędzi dla programistów (np. platformy testowe lub pomoc AI w Narzędziach deweloperskich w Chrome), a nie do interakcji z użytkownikiem. Dzięki temu klienci użytkownika do zwykłych obciążeń i klienci użytkownika mogą odfiltrować narzędzia dla deweloperó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}.`;
  },
});

Przykłady wpływu adnotacji na zachowanie agenta znajdziesz w sekcji Przykładowe rozszerzenie WebMCP.

Wyrejestrowywanie narzędzi

Możesz usunąć narzędzie za pomocą parametru AbortSignal, gdy jest on przekazywany 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 Chrome 153 możesz wyrejestrować narzędzie bez anulowania i przerywania wykonywania w trakcie. Zapobiega to nieoczekiwanym efektom ubocznym podczas zarządzania cyklami życia narzędzi w platformach komponentów.

Postępowanie w razie anulowania narzędzia

Funkcja execute otrzymuje parametr AbortSignal o nazwie signal jako drugi argument, aby prawidłowo obsługiwać anulowanie wykonywania zainicjowane przez użytkownika lub agenta. Przekazywanie tego sygnału do długotrwałych zadań asynchronicznych lub operacji sieciowych (takich jak 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 metoda asynchroniczna zwraca uporządkowaną alfabetycznie listę narzędzi, do których wywołujący dokument 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 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 podać ich źródła w opcji fromOrigins. Ta tablica obsługuje tylko bezpieczne źródła.

Narzędzia z dokumentów z innych domen są uwzględniane tylko wtedy, gdy:

Punkt początkowy hostingu jest wymieniony w opcji fromOrigins.
Narzędzie zostało wyraźnie udostępnione Twojemu źródłu.

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

Zobacz wersję demonstracyjną agenta strony WebMCP, aby dowiedzieć się, jak pobierać narzędzia z elementu iframe i wykonywać je w interfejsie czatu internetowego. Zapoznaj się z przykładowym rozszerzeniem WebMCP, aby zobaczyć, jak agent w rozszerzeniu do przeglądarki znajduje i uruchamia narzędzia w ramkach iframe z tego samego źródła i współdzielenia.

Uruchom narzędzie

Aby ręcznie wykonać narzędzie wykryte w getTools(), wywołaj document.modelContext.executeTool() z opcjonalnym obiektem w JavaScripcie 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 wywoływana jest 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ą AbortSignal, gdy jest 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 zmianie listy dostępnych narzędzi.

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

Elementy iframe z różnych domen

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

zasady dotyczące uprawnień,

Rejestracja narzędzi jest domyślnie wyłączona w elementach iframe ze współdzieleniem zasobów z różnych domen. Strona musi przekazywać dostęp za pomocą toolszasad dotyczących uprawnień:

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

Udostępnienie źródła

Narzędzia są domyślnie niedostępne w przypadku dokumentów z innych domen. Możesz użyć tablicy exposedTo w obiekcie registerTool, aby wyświetlić listę konkretnych źródeł, które mogą wyświetlać i wykonywać 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 w popularnych platformach JavaScript

React, Angular i Vue mają eksperymentalną obsługę WebMCP.

React: użyj pakietu use-webmcp-tool. Zarejestruj narzędzia za pomocą elementu hook useWebMCP powiązanego z cyklem życia podłączania i odłączania komponentu. Ten punkt zaczepienia obsługuje warunkową rejestrację narzędzi i automatycznie normalizuje wyniki wykonywania.
Angular: zarejestruj narzędzia powiązane z cyklem życia wstrzykiwania zależności aplikacji i przekształć formularze Signal w narzędzia WebMCP.
Vue: użyj funkcji kompozycyjnej useWebMCP z pakietu @vueuse/core. Zarejestruj narzędzia powiązane z bieżącym cyklem życia zakresu Vue. Implementacja Vue obsługuje reaktywną i warunkową rejestrację narzędzi oraz automatycznie normalizuje wyniki wykonywania.

Zaangażuj się i prześlij opinię

WebMCP jest przedmiotem aktywnej dyskusji i może ulec zmianie w przyszłości. 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.
Dowiedz się, jak tworzyć skuteczne narzędzia WebMCP, i poznaj sprawdzone metody dotyczące WebMCP.
Sprawdź implementację w Chrome na stronie Stan Chrome.
Dołącz do programu wczesnej wersji przedpremierowej, aby uzyskać wcześniejszy dostęp do nowych interfejsów API i naszej listy adresowej.
Jeśli masz uwagi dotyczące implementacji Chrome, zgłoś błąd Chromium.

Wstecz

Rozpocznij

Dalej

Deklaratywny interfejs API