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

Opublikowano: 18 maja 2026 r., ostatnia aktualizacja: 15 października 2026 r.

Wyjaśnienie	Sieć	Rozszerzenia	Stan Chrome	Intencja
GitHub	Testowanie origin		Wyświetl	Intencja eksperymentu

Za pomocą interfejsu WebMCP Imperative API możesz definiować wiele typów narzędzi za pomocą standardowego JavaScriptu. Twoje 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, przeczytaj o przykładowych przypadkach użycia.

Podawanie kontekstu modelu

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

Aby dodać pojedyncze narzędzie do kontekstu modelu, użyj funkcji registerTool.

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

Pobieranie 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 narzędzi (opcjonalne)

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 w katalogu 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ą niezaufane dane z perspektywy autora narzędzia (np. treści użytkowników, opinie lub dane z zewnętrznych stron internetowych). Sygnalizuje to agentowi i klientowi, że zwrócony ładunek wymaga zwiększonej ochrony, np. oczyszczenia lub ograniczenia, aby złagodzić skutki pośredniego wstrzykiwania promptów.
consequentialHint (wartość logiczna, domyślnie false): gdy ma wartość true, wskazuje, że wykonanie narzędzia powoduje znaczące, rzeczywiste lub nieodwracalne działania (np. rezerwację lotu, przelew pieniędzy lub usunięcie danych). Umożliwia to agentom i przeglądarkom wymuszanie wyświetlania obowiązkowych promptów z prośbą o potwierdzenie przez użytkownika przed wykonaniem narzędzi o wysokim ryzyku, co zmniejsza ryzyko przypadkowego lub złośliwego przekłamania 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. platform testowych lub asystenta AI w Narzędziach deweloperskich w Chrome), a nie do interakcji z użytkownikami. Umożliwia to agentom do zwykłych obciążeń i agentom użytkowników filtrowanie narzędzi przeznaczonych 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 wpływu adnotacji na zachowanie agenta znajdziesz w przykładowym rozszerzeniu WebMCP.

Wyrejestrowywanie narzędzi

Narzędzie możesz usunąć za pomocą AbortSignal, gdy zostanie przekazane 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 Chrome 153 możesz wyrejestrować narzędzie bez anulowania i przerywania wykonywanych operacji. Zapobiega to nieoczekiwanym efektom ubocznym podczas zarządzania cyklem życia narzędzia w platformach komponentów.

Obsługa anulowania narzędzia

Funkcja execute otrzymuje jako drugi argument parametr AbortSignal o nazwie signal, aby płynnie 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 zapobiega potencjalnym wyciekom.

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

Aby pobrać dostępne narzędzia, użyj funkcji document.modelContext.getTools(). Ta metoda asynchroniczna zwraca posortowaną 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 funkcja getTools() zwraca tylko narzędzia z tej samej domeny zarejestrowane przez wywołujący dokument 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 domeny.

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

domena hostingu jest wymieniona 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 wersji demonstracyjnej WebMCP Page Agent. W przykładowym rozszerzeniu WebMCP dowiesz się, jak agent w rozszerzeniu przeglądarki znajduje i uruchamia narzędzia w elementach iframe z tej samej domeny i z różnych domen.

Wykonywanie narzędzia

Aby ręcznie wykonać narzędzie wykryte w getTools(), wywołaj funkcję 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 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ą AbortSignal, gdy zostanie przekazane 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 domen, które korzystają zarówno z zasad dotyczących uprawnień, jak i z wyraźnego ograniczania dostępu do domeny.

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 zasady dotyczącej uprawnień:

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

Udostępnianie domeny

Narzędzia są domyślnie niedostępne dla dokumentów współdzielenie. Aby wyświetlić listę konkretnych domen, które mogą wyświetlać i wykonywać narzędzie, użyj tablicy exposedTo w registerTool. Ta tablica obsługuje tylko bezpieczne domeny.

// https://partner.org

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

Obsługa Reacta

React eksperymentalnie obsługuje WebMCP za pomocą pakietu usewebmcp. Jeśli Twoja aplikacja jest już napisana w React, możesz rejestrować narzędzia za pomocą samodzielnych hooków powiązanych z cyklem życia montowania i odmontowywania komponentu. Hook useWebMCP zapewnia też wnioskowanie typu oparte na schemacie i udostępnia lokalny stan wykonania.

Obsługa Angulara

Angular eksperymentalnie obsługuje WebMCP. Jeśli Twoja aplikacja jest już napisana w Angularze, możesz rejestrować narzędzia powiązane z cyklem życia wstrzykiwania zależności aplikacji i przekształcać formularze sygnałów w narzędzia WebMCP.

Obsługa Vue

Vue eksperymentalnie obsługuje WebMCP za pomocą pakietu @vueuse/core. Jeśli Twoja aplikacja jest już napisana w Vue, możesz rejestrować narzędzia za pomocą funkcji kompozycyjnej useWebMCP powiązanej z bieżącym cyklem życia zakresu Vue. Obsługuje też rejestrację narzędzi reaktywnych i warunkowych oraz automatycznie normalizuje wyniki wykonania.

Zaangażuj się i prześlij opinię

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

Przeczytaj wyjaśnienie WebMCP, zadawaj pytania i bierz udział w dyskusji.
Dowiedz się, jak tworzyć skuteczne narzędzia WebMCP i poznaj sprawdzone metody WebMCP.
Sprawdź implementację Chrome w Stanie Chrome.
Dołącz do programu wczesnej wersji przedpremierowej aby wcześniej poznać nowe interfejsy API i uzyskać dostęp do naszej listy adresowej.
Jeśli masz uwagi dotyczące implementacji Chrome, zgłoś błąd w Chromium.

Wstecz

Rozpocznij

Dalej

Deklaratywny interfejs API