API imperativa

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

Publicado em 18 de maio de 2026, atualizado pela última vez em 2 de junho de 2026

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

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

Antes de usar essa API, leia sobre os casos de uso de exemplo.

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.

Criador do WebMCPza

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

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

É 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();
document.modelContext.registerTool(addTodoTool, { signal: controller.signal });

// Unregister the tool later...
controller.abort();

Descobrem as ferramentas

Para conferir as ferramentas disponíveis, use document.modelContext.getTools(). Esse método assíncrono retorna uma lista de ferramentas que o documento de chamada está autorizado a acessar.

const [tool] = await document.modelContext.getTools();
console.log(tool);

// {
//   annotations: { readOnlyHint: false, untrustedContentHint: true },
//   description: "Add a new item to the to-do list",
//   inputSchema: '{"type":"object","properties":{"text":{"type":"string"}}}',
//   name: "addTodo",
//   origin: "https://example.com",
//   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 delas na opção fromOrigins. Essa matriz só aceita origens seguras.

As ferramentas de documentos de origem cruzada só serão incluídas se:

  1. A origem de hospedagem estiver listada na opção fromOrigins.
  2. A ferramenta foi exposta explicitamente à 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 conferir 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 argumentos de entrada como uma string JSON válida. 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 transmitida 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 de origem cruzada

O WebMCP oferece suporte a iframes de origem cruzada que usam políticas de permissão e bloqueio de origem explícito.

Política de permissões

O registro de ferramentas está desativado por padrão em iframes de origem cruzada. 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

As ferramentas não estão disponíveis para documentos de origem cruzada por padrão. É possível usar a matriz exposedTo em registerTool para listar origens específicas permitidas para visualizar e executar uma ferramenta. Essa matriz só aceita origens seguras.

// https://partner.org

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

Suporte do 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 da injeção de dependência do aplicativo e transformar seus formulários de sinal em ferramentas do WebMCP.

Engajamento e como compartilhar feedback

O WebMCP está em discussão ativa e está sujeito a mudanças no futuro. Se você testar essa API e tiver feedback, gostaríamos de saber.