API imperativa

Alexandra Klepper

François Beaufort

Fecha de publicación: 18 de mayo de 2026. Última actualización: 1 de septiembre de 2026

Video explicativo	Web	Extensiones	Estado de Chrome	Intención
GitHub	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 de estados.

Antes de usar esta API, lee sobre los casos prácticos de ejemplo.

Proporciona contexto del modelo

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

Usa registerTool para agregar una sola herramienta al contexto del modelo.

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

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 de una herramienta, los efectos secundarios esperados y la confiabilidad de los resultados:

• 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 del pedido). Esto ayuda a los agentes a determinar si se puede llamar a la herramienta de forma segura sin efectos secundarios.
• untrustedContentHint (booleano, el valor predeterminado es 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, reseñas o datos web externos). Esto indica al agente y al cliente que la carga útil que se muestra requiere un manejo de seguridad mejorado, como la desinfección o la delimitación, para mitigar la inyección indirecta de instrucciones.
• consequentialHint (booleano, el valor predeterminado es false): Cuando es true, indica que la ejecución de la herramienta genera acciones significativas, reales o no reversibles (por ejemplo, reservar un vuelo, transferir dinero o borrar datos). Esto permite que los agentes y los navegadores apliquen mensajes de confirmación obligatorios para el 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 cancelar 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.

Controla la cancelación de herramientas

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

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 de herramientas ordenadas alfabéticamente a las que el documento que realiza la llamada tiene autorización para 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 las herramientas del mismo origen registradas por el documento que realiza la llamada o por otros documentos del mismo origen en el árbol de marcos. Para recuperar herramientas de origen cruzado, debes enumerar explícitamente 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 de 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 obtener un ejemplo de cómo recuperar herramientas de un iframe y ejecutarlas dentro de una interfaz de chat basada en la Web.

Ejecuta la herramienta

Para ejecutar manualmente una herramienta descubierta en getTools(), llama a document.modelContext.executeTool() con argumentos de entrada como una cadena JSON válida. 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 una ejecución de 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 cambia 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 puertas de enlace de origen explícitas.

Política de permisos

El registro de herramientas está inhabilitado de forma predeterminada en los iframes 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 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 mediante el 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 hook 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 señal en herramientas de WebMCP.

Interactúa y envía 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.

• Lee la explicación de WebMCP, haz preguntas y participa en el debate.
• Lee las prácticas recomendadas de WebMCP.
• Revisa la implementación de Chrome en el estado de Chrome.
• Únete al programa de vista previa anticipada para obtener una vista previa de las nuevas APIs y acceder a nuestra lista de distribución.
• Si tienes comentarios sobre la implementación de Chrome, informa un error de Chromium.