API imperativa

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

Fecha de publicación: 18 de mayo de 2026; última actualización: 16 de octubre de 2026

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

Puedes usar la API imperativa de WebMCP 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 de uso 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 propiedades pertinentes.

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

WebMCP

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 metadatos en la propiedad annotations. Estas anotaciones ayudan a los agentes y navegadores a comprender las características de seguridad de una herramienta, los efectos secundarios esperados, la confiabilidad de los resultados y el público objetivo:

  • 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 en un catálogo de productos o recuperar el estado de un 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, opiniones o datos web externos). Esto indica al agente y al cliente que la carga útil que se muestra requiere un manejo de seguridad más estricto, como la limpieza o la delimitación, para mitigar la inyección de instrucciones indirecta.
  • 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.
  • debugging (booleano, el valor predeterminado es false, disponible a partir de Chrome 156): Cuando es true, indica que la herramienta está diseñada específicamente para la inspección y las herramientas para desarrolladores (por ejemplo, frameworks de pruebas o la asistencia de IA de las Herramientas para desarrolladores de Chrome) en lugar de las interacciones de los usuarios finales. Esto permite que los usuario-agentes de uso general y de usuario final filtren las herramientas enfocadas en los desarrolladores.
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 ejemplos de cómo las anotaciones pueden influir en el comportamiento del agente, consulta la extensión de WebMCP de ejemplo.

Cómo cancelar el registro de herramientas

Puedes quitar una herramienta con AbortSignal, cuando se pasa como 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 la herramienta

La función execute recibe un parámetro AbortSignal llamado signal como su segundo argumento para controlar de forma correcta 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 ordenada alfabéticamente de las herramientas 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, 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, …},
// }

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 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 de hosting se indica en la opción fromOrigins.
  2. La herramienta se expuso de forma explícita 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 en una interfaz de chat basada en la Web. Consulta la extensión de WebMCP de ejemplo para ver cómo un agente en una extensión de navegador encuentra y ejecuta herramientas en iframes de origen cruzado y del mismo origen.

Ejecutar herramienta

Para ejecutar manualmente una herramienta descubierta en getTools(), llama a document.modelContext.executeTool() con un objeto de 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 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 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 control de acceso explícito de origen.

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

De forma predeterminada, las herramientas no están disponibles para los documentos de origen cruzado. 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 frameworks de JavaScript comunes

React, Angular y Vue tienen compatibilidad experimental con WebMCP.

  • React: Usa el paquete use-webmcp-tool. Registra herramientas con el hook useWebMCP vinculado al ciclo de vida de activación y desactivación de tu componente. Este hook admite el registro condicional de herramientas y normaliza automáticamente los resultados de la ejecución.
  • Angular: Registra herramientas vinculadas al ciclo de vida de la inserción de dependencias de la aplicación y convierte tus Signal Forms en herramientas de WebMCP.
  • Vue: Usa el elemento componible useWebMCP del paquete @vueuse/core. Registra herramientas vinculadas al ciclo de vida del permiso de Vue actual. La implementación de Vue admite el registro de herramientas reactivas y condicionales, y normaliza automáticamente los resultados de la ejecución.

Interactúa y envía comentarios

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

Anterior
Comenzar
Siguiente
API declarativa