API imperativa

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky
François Beaufort
François Beaufort
GitHub

Publicado em: 18 de maio de 2026. Última atualização: 11 de setembro de 2026

Explicação Web Extensões Status do Chrome Intenção
GitHub Teste de origem Teste de origem Ver Intenção de experimentar

É possível usar a API imperativa WebMCP para definir vários tipos de ferramentas com JavaScript padrão. Suas ferramentas podem executar diferentes funções, como entrada de formulário, navegação no site e gerenciamento de estado.

Antes de usar essa API, leia sobre exemplos de casos de uso.

Fornecer contexto do modelo

Use a interface modelContext para registrar ferramentas. O registro de ferramentas exige um nome, uma descrição e um esquema de entrada com propriedades relevantes.

Use registerTool para adicionar uma única ferramenta ao contexto do modelo.

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

Verificar o status do pedido

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

Anotações de ferramentas (opcional)

Ao registrar uma ferramenta, é possível adicionar dicas de metadados na propriedade annotations. Essas dicas ajudam agentes e navegadores a entender as características de segurança de uma ferramenta, os efeitos colaterais esperados e a confiabilidade da saída:

  • readOnlyHint (booleano, padrão false): quando true, indica que a ferramenta apenas lê informações e não modifica o estado do aplicativo ou sistema (por exemplo, pesquisar um catálogo de produtos ou recuperar o status do pedido). Isso ajuda os agentes a determinar se a ferramenta pode ser chamada com segurança sem efeitos colaterais.
  • untrustedContentHint (booleano, padrão false): quando true, indica que a saída da ferramenta contém dados não confiáveis do ponto de vista do autor da ferramenta (por exemplo, conteúdo gerado pelo usuário, avaliações ou dados externos da Web). Isso indica ao agente e ao cliente que o payload retornado requer um tratamento de segurança mais rigoroso, como higienização ou delimitação, para mitigar a injeção indireta de comandos.
  • consequentialHint (booleano, padrão é false): quando true, indica que a execução da ferramenta resulta em ações significativas, reais ou irreversíveis (por exemplo, reservar um voo, transferir dinheiro ou excluir dados). Isso permite que agentes e navegadores apliquem solicitações de confirmação obrigatória do usuário antes de executar ferramentas de alto risco, reduzindo o risco de representação indevida acidental ou maliciosa da intenção do usuário.
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}.`;
  },
});

Cancelar registro de ferramentas

É possível remover uma ferramenta com AbortSignal, quando transmitida como um parâmetro opcional.

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

A partir do Chrome 153, é possível cancelar o registro de uma ferramenta sem cancelar e interromper as execuções em andamento. Isso evita efeitos colaterais inesperados ao gerenciar ciclos de vida de ferramentas em frameworks de componentes.

Processar o cancelamento da ferramenta

A função execute recebe um parâmetro AbortSignal chamado signal como segundo argumento para processar cancelamentos de execução iniciados pelo usuário ou agente. Transmitir esse sinal para tarefas assíncronas de longa duração ou operações de rede (como fetch()) ajuda a evitar trabalho desnecessário, melhora o gerenciamento geral de recursos e evita possíveis vazamentos.

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

descobrem as ferramentas

Use document.modelContext.getTools() para extrair as ferramentas disponíveis. Esse método assíncrono retorna uma lista em ordem alfabética de ferramentas que o documento de chamada está autorizado a acessar.

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

Por padrão, getTools() retorna apenas ferramentas de mesma origem registradas pelo documento de chamada ou outros documentos de mesma origem na árvore de frames. Para recuperar ferramentas de origem cruzada, liste explicitamente as origens na opção fromOrigins. Essa matriz só aceita origens seguras.

As ferramentas de documentos entre origens só serão incluídas se:

  1. A origem da hospedagem está listada na opção fromOrigins.
  2. A ferramenta foi exposta à sua origem.
// 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']
});

Consulte a demonstração do agente de página do WebMCP para ver um exemplo de como recuperar ferramentas de um iframe e executá-las em uma interface de chat baseada na Web.

Executar ferramenta

Para executar manualmente uma ferramenta descoberta em getTools(), chame document.modelContext.executeTool() com um objeto JavaScript opcional para argumentos de entrada que podem ser serializados em uma string JSON. Esse método assíncrono retorna o resultado da execução da ferramenta ou nulo quando uma navegação é acionada.

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

// 'Added to-do: Buy milk'

É possível cancelar uma execução de ferramenta pendente com AbortSignal, quando transmitido como um parâmetro opcional.

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

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

Eventos

Os frames podem detectar o evento toolchange em document.modelContext para receber uma notificação quando a lista de ferramentas disponíveis mudar.

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

iframes entre origens

O WebMCP é compatível com iframes entre origens que usam políticas de permissão e controle de origem explícito.

Política de permissões

O registro de ferramentas fica desativado por padrão em iframes entre origens. Uma página precisa delegar acesso usando a tools política de permissões:

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

Exposição de origem

Por padrão, as ferramentas não estão disponíveis para documentos de origens diferentes. É possível usar a matriz exposedTo em registerTool para listar origens específicas que podem visualizar e executar uma ferramenta. Essa matriz só aceita origens seguras.

// https://partner.org

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

Suporte do React

O React tem suporte experimental para WebMCP usando o pacote usewebmcp. Se o aplicativo já estiver escrito com React, você poderá registrar ferramentas usando hooks independentes vinculados ao ciclo de vida de montagem e desmontagem do componente. O hook useWebMCP também oferece inferência de tipo orientada a esquema e expõe o estado de execução local.

Suporte ao Angular

O Angular tem suporte experimental para WebMCP. Se o aplicativo já estiver escrito em Angular, você poderá registrar ferramentas vinculadas ao ciclo de vida de injeção de dependência do aplicativo e transformar seus formulários de sinalização em ferramentas do WebMCP.

Engajamento e como compartilhar feedback

O WebMCP está em discussão e sujeito a mudanças no futuro. Se você testar essa API e tiver feedback, envie sua opinião.

Anterior
Começar
Avançar
API declarativa