API imperativa

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

Publicado: 18 de mayo de 2026, última actualización: 11 de septiembre de 2026

Explicativa Web Extensiones Estado de Chrome Intención
GitHub Prueba de origen Prueba de origen Ver Intención de experimentar

Puedes usar la API de WebMCP Imperative para definir muchos tipos de herramientas con JavaScript estándar. Tus herramientas pueden ejecutar diferentes funciones, como la entrada de formularios, la navegación por el sitio y la administración del estado.

Antes de usar esta API, lee sobre los ejemplos de casos de uso.

Proporciona contexto del modelo

Usa la interfaz de modelContext para registrar herramientas. El registro de herramientas requiere un nombre, una descripción y un esquema de entrada con propiedades relevantes.

Usa registerTool para agregar una sola herramienta al contexto del 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}`;
  },
});

Obtén el estado del 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.
  },
});

Anotaciones de herramientas (opcional)

Cuando registras una herramienta, puedes agregar sugerencias de metadatos en la propiedad annotations. Estas sugerencias ayudan a los agentes y navegadores a comprender las características de seguridad, los efectos secundarios esperados y la confiabilidad de la salida de una herramienta:

  • readOnlyHint (booleano, el valor predeterminado es false): Cuando es true, indica que la herramienta solo lee información y no modifica el estado de la aplicación o el sistema (por ejemplo, buscar un catálogo de productos o recuperar el estado de pedido). Esto ayuda a los agentes a determinar si la herramienta se puede llamar de forma segura sin efectos secundarios.
  • untrustedContentHint (booleano, valor predeterminado false): Cuando es true, indica que el resultado de la herramienta contiene datos no confiables desde la perspectiva del autor de la herramienta (por ejemplo, contenido generado por usuarios, opiniones o datos externos de la Web). Esto indica al agente y al cliente que la carga útil devuelta requiere un manejo de seguridad mejorado, como la desinfección o la delimitación, para mitigar la inyección indirecta de instrucciones.
  • consequentialHint (booleano, valor predeterminado false): Cuando es true, indica que la ejecución de la herramienta genera acciones significativas, reales o irreversibles (por ejemplo, reservar un vuelo, transferir dinero o borrar datos). Esto permite que los agentes y los navegadores apliquen mensajes obligatorios de confirmación del usuario antes de ejecutar herramientas de alto riesgo, lo que mitiga el riesgo de tergiversación accidental o maliciosa de la intención del usuario.
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 el registro de herramientas

Puedes quitar una herramienta con AbortSignal cuando se pasa como un 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 de Chrome 153, puedes anular el registro de una herramienta sin cancelar ni interrumpir las ejecuciones en curso. Esto evita efectos secundarios inesperados cuando se administran los ciclos de vida de las herramientas en los frameworks de componentes.

Cómo controlar la cancelación de herramientas

La función execute recibe un parámetro AbortSignal llamado signal como segundo argumento para controlar correctamente las cancelaciones de ejecución iniciadas por el usuario o el agente. Pasar este indicador a tareas asíncronas o operaciones de red de larga duración (como fetch()) ayuda a evitar trabajo innecesario, mejora la administración general de recursos y evita posibles fugas.

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

Descubre herramientas

Usa document.modelContext.getTools() para recuperar las herramientas disponibles. Este método asíncrono devuelve una lista ordenada alfabéticamente de las herramientas a las que el documento de llamada está autorizado a acceder.

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

De forma predeterminada, getTools() solo devuelve herramientas del mismo origen registradas por el documento de llamada o por otros documentos del mismo origen en el árbol de marcos. Para recuperar herramientas de origen cruzado, debes enumerar de forma explícita sus orígenes en la opción fromOrigins. Este array solo admite orígenes seguros.

Las herramientas de documentos de origen cruzado solo se incluyen si se cumplen las siguientes condiciones:

  1. El origen del hosting aparece en la opción fromOrigins.
  2. La herramienta se expuso explícitamente a tu origen.
// 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']
});

Consulta la demostración del agente de página de WebMCP para ver un ejemplo de cómo recuperar herramientas de un iframe y ejecutarlas dentro de una interfaz de chat basada en la Web.

Ejecutar herramienta

Para ejecutar manualmente una herramienta descubierta en getTools(), llama a document.modelContext.executeTool() con un objeto JavaScript opcional para los argumentos de entrada que se pueden serializar en una cadena JSON. Este método asíncrono devuelve el resultado de la ejecución de la herramienta o un valor nulo cuando se activa una navegación.

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

// 'Added to-do: Buy milk'

Puedes cancelar la ejecución de una herramienta pendiente con AbortSignal, cuando se pasa como un parámetro opcional.

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

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

Eventos

Los marcos pueden escuchar el evento toolchange en document.modelContext para recibir una notificación cuando cambie la lista de herramientas disponibles.

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

Iframes de origen cruzado

WebMCP admite iframes de origen cruzado que usan políticas de permisos y restricciones explícitas de origen.

Política de permisos

El registro de herramientas está inhabilitado de forma predeterminada en los iframe de origen cruzado. Una página debe delegar el acceso con la tools Política de permisos:

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

Exposición del origen

Las herramientas no están disponibles para los documentos de origen cruzado de forma predeterminada. Puedes usar el array exposedTo dentro de registerTool para enumerar los orígenes específicos que pueden ver y ejecutar una herramienta. Este array solo admite orígenes seguros.

// https://partner.org

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

Compatibilidad con React

React tiene compatibilidad experimental con WebMCP a través del paquete usewebmcp. Si tu aplicación ya está escrita con React, puedes registrar herramientas con hooks independientes vinculados al ciclo de vida de montaje y desmontaje de tu componente. El gancho useWebMCP también proporciona inferencia de tipos basada en el esquema y expone el estado de ejecución local.

Compatibilidad con Angular

Angular tiene compatibilidad experimental con WebMCP. Si tu aplicación ya está escrita con Angular, puedes registrar herramientas vinculadas al ciclo de vida de la inyección de dependencias de la aplicación y convertir tus formularios de Signal en herramientas de WebMCP.

Interactúa y comparte comentarios

WebMCP está en debate activo y está sujeto a cambios en el futuro. Si pruebas esta API y tienes comentarios, nos encantaría conocerlos.

Anterior
Comenzar
Siguiente
API declarativa