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: 11 września 2026 r.

Film z wyjaśnieniem	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 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}`;
  },
});

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

Podczas rejestrowania narzędzia możesz dodać wskazówki dotyczące metadanych we właściwości annotations. Te wskazówki pomagają agentom i przeglądarkom zrozumieć cechy bezpieczeństwa narzędzia, oczekiwane efekty uboczne i wiarygodność danych wyjściowych:

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 ma wartość true, oznacza, ż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 potwierdzeń przed wykonaniem narzędzi o wysokim ryzyku, co zmniejsza ryzyko przypadkowego lub złośliwego przekłamania intencji użytkownika.

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,
  },
  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ą ikony AbortSignal, jeśli jest ono 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.

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

Odkryj narzędzia

Użyj document.modelContext.getTools(), aby pobrać dostępne narzędzia. Ta asynchroniczna metoda 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, 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 źródła.

Narzędzia z dokumentów z innych domen 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 interfejsie czatu w przeglądarce 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 asynchroniczna metoda 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, jeśli zostanie on przekazany 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>

Udostępnienie ź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

Biblioteka 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 komponentu (montowanie i odmontowywanie). Hook useWebMCP zapewnia też wnioskowanie o typach na podstawie schematu i udostępnia lokalny stan wykonania.

Obsługa Angulara

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 chcesz podzielić się opinią, chętnie ją poznamy.

Przeczytaj wyjaśnienie dotyczące WebMCP, zadawaj pytania i bierz udział w dyskusji.
Przeczytaj sprawdzone metody dotyczące WebMCP.
Sprawdź implementację w Chrome na stronie Stan Chrome.
Dołącz do programu wcześniejszego dostępu, aby jako pierwszy(-a) 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