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: 16 de outubro de 2026

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

É possível usar a API Imperative do WebMCP para definir vários tipos de ferramentas com JavaScript padrão. As 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 requer 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}`;
  },
});

Ver 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 metadados na propriedade annotations. Essas anotações ajudam os agentes e navegadores a entender as características de segurança de uma ferramenta, os efeitos colaterais esperados, a confiabilidade da saída e o público-alvo:

  • 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, o padrão é false): quando true, indica que a saída da ferramenta contém dados não confiáveis da perspectiva do autor da ferramenta (por exemplo, conteúdo gerado pelo usuário, avaliações ou dados da Web externos). Isso sinaliza ao agente e ao cliente que o payload retornado requer um tratamento de segurança mais rigoroso, como limpeza ou delimitação, para mitigar a injeção indireta de comandos.
  • consequentialHint (booleano, o 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órias antes de executar ferramentas de alto risco, mitigando o risco de deturpação acidental ou maliciosa da intenção do usuário.
  • debugging (booleano, o padrão é false, disponível no Chrome 156): quando true, indica que a ferramenta foi projetada especificamente para inspeção e ferramentas para desenvolvedores (por exemplo, frameworks de teste ou Assistência de IA do Chrome DevTools), em vez de interações do usuário final. Isso permite que os agentes de uso geral e de usuários finais filtrem as ferramentas voltadas para desenvolvedores.
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}.`;
  },
});

Para ver exemplos de como as anotações podem influenciar o comportamento do agente, consulte o exemplo de extensão WebMCP.

Cancelar o 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 lidar de forma adequada com 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 recuperar as ferramentas disponíveis. Esse método assíncrono retorna uma lista ordenada em ordem alfabética de ferramentas que o documento de chamada tem autorização para acessar.

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

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, é necessário listar explicitamente as origens delas 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 explicitamente 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']
});

Confira 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. Consulte o exemplo de extensão do WebMCP para ver como um agente em uma extensão do navegador encontra e executa ferramentas em iframes de mesma origem e entre origens.

Executar ferramenta

Para executar manualmente uma ferramenta descoberta em getTools(), chame document.modelContext.executeTool() com um objeto JavaScript opcional para argumentos de entrada que seja serializável 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 serem notificados 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 entre origens. É 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 ao React

O React tem suporte experimental para o WebMCP usando o pacote use-webmcp-tool. Se o aplicativo já estiver escrito com o React, você poderá registrar ferramentas usando o hook useWebMCP vinculado ao ciclo de vida de montagem e desmontagem do componente. Ele também é compatível com o registro condicional de ferramentas e normaliza automaticamente os resultados da execução.

Suporte ao Angular

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

Suporte ao Vue

O Vue tem suporte experimental ao WebMCP usando o pacote @vueuse/core. Se o aplicativo já estiver escrito com o Vue, você poderá registrar ferramentas usando o elemento combinável useWebMCP vinculado ao ciclo de vida do escopo atual do Vue. Ele também oferece suporte ao registro de ferramentas reativas e condicionais e normaliza automaticamente os resultados da execução.

Engajamento e como compartilhar feedback

O WebMCP está em discussão ativa e sujeito a mudanças no futuro. Se você testar essa API e tiver feedback, entre em contato com nossa equipe.

Anterior
Começar
Avançar
API declarativa