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	Testowanie origin		Wyświetl	Zamiar eksperymentowania

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ń.

Podawanie kontekstu 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 pojedyncze 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 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ń 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 kontroli i narzędzi dla programistów (np. platform testowych lub pomocy AI w Narzędziach deweloperskich w Chrome), a nie do interakcji z użytkownikiem. Dzięki temu agenty ogólnego przeznaczenia i agenty dla użytkowników mogą odfiltrować narzędzia 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}.`;
  },
});

Przykłady tego, jak adnotacje mogą wpływać 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 tego samego źródła zarejestrowane przez dokument wywołujący lub inne dokumenty z tego samego źródła 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 demonstrację 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 elementach iframe z tej samej domeny i współdzielenie.

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 z różnych źródeł, które korzystają zarówno z zasad uprawnień, jak i 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ą tools zasad 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 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 React

React ma eksperymentalną obsługę WebMCP przy użyciu pakietu use-webmcp-tool. Jeśli aplikacja jest już napisana w React, możesz zarejestrować narzędzia za pomocą elementu hook useWebMCP powiązanego z cyklem życia montowania i odmontowywania komponentu. Obsługuje też warunkową rejestrację narzędzi i automatycznie normalizuje wyniki wykonywania.

Obsługa Angulara

Angular ma eksperymentalną obsługę WebMCP. Jeśli 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 Signal w narzędzia WebMCP.

Obsługa Vue

Vue ma eksperymentalną obsługę WebMCP przy użyciu pakietu @vueuse/core. Jeśli aplikacja jest już napisana w Vue, możesz zarejestrować narzędzia za pomocą funkcji kompozycyjnej useWebMCP powiązanej z bieżącym cyklem życia zakresu Vue. Obsługuje też reaktywną i warunkową rejestrację narzędzi oraz automatycznie normalizuje wyniki wykonywania.

Zaangażuj się i prześlij opinię

Protokół WebMCP jest obecnie przedmiotem 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 Chrome Status.
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