API declarativa

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Fecha de publicación: 18 de mayo de 2026

Explicativa Web Extensiones Estado de Chrome Intención
GitHub Versión de prueba para desarrolladores Prueba para desarrolladores Versión de prueba para desarrolladores Prueba para desarrolladores Ver Intención de experimentar

Usa la API declarativa para transformar formularios HTML estándar en herramientas de WebMCP agregando anotaciones. Las anotaciones definen el nombre y el propósito de la herramienta en el elemento <form>, mientras que los campos actúan como parámetros de la herramienta. El navegador traduce estos elementos en una representación estructurada que los agentes pueden usar de manera similar a las herramientas imperativas.

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

Registro de herramientas

Agrega los siguientes atributos HTML a tu formulario:

  • toolname: Asigna un nombre claro a la herramienta según su propósito.
  • tooldescription: Describe qué acción realiza la herramienta y su propósito.

Por ejemplo, el siguiente formulario se encuentra en example.com/get-customer-support:

<form toolname="supportRequestTool" tooldescription="Submit a request for support.">
</form>

Cuando un agente llama a toolname, el navegador enfoca el formulario y completa su campo. El usuario sigue viendo el formulario.

Si quitas el atributo HTML toolname o tooldescription, se anulará el registro de la herramienta.

(Opcional) Parámetros de la herramienta

Para mejorar la precisión, agrega los siguientes atributos HTML a los elementos del formulario individuales:

  • toolparamdescription: Asigna elementos a una descripción de propiedad dentro del esquema JSON. Sin este atributo, el navegador usa el contenido dentro del <label> asociado y omite los elementos descendientes que se pueden etiquetar. Si no hay una etiqueta, el navegador hace referencia a aria-description.

En el siguiente formulario, se usan los parámetros opcionales del elemento <select>.

<form toolname="supportRequestTool"
  tooldescription="Submit a request for support."
  action="/submit">

  <label for="firstName">First Name</label>
  <input type=text name=firstName>

  <label for="lastName">Last Name</label>
  <input type=text name=lastName>

  <select name="select" required toolparamtitle="Support type" 
    toolparamdescription="Determines what team this request is routed to.">
    <option value="Customer happiness team">Return my purchase.</option>
    <option value="Distribution team">Check where my package is.</option>
    <option value="Website support team">Get help on the website.</option>
  </select>

  <button type=submit>Submit</button>
</form>

El navegador interpreta este formulario como una herramienta, representada por el siguiente JSON:

[
  {
    "name": "supportRequestTool",
    "description": "Submit a request for support.",
    "inputSchema": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "title": "firstName",
          "description": "First name"
        },
        "text": {
          "type": "string",
          "title": "lastName",
          "description": "Last name"
        },
        "select": {
          "type": "string",
          "anyOf": [
            {
              "const": "Customer happiness team",
              "title": "Return my purchase."
            },
            {
              "const": "Distribution team",
              "title": "Check where my package is."
            },
            {
              "const": "Website support team",
              "title": "Get help on the website."
            }
          ],
          "enum": [
            "Customer happiness team",
            "Distribution team",
            "Website support team"
          ],
          "title": "Support type",
          "description": "Determines what team this request is routed to."
        }
      },
      "required": [
        "select"
      ]
    }
  }
]

Envía el formulario

Tienes dos opciones para enviar el formulario:

  • El usuario debe hacer clic en Enviar de forma manual para completar la tarea.
  • Agrega toolautosubmit para activar el envío y un cambio de navegación.

La interfaz SubmitEvent introduce el atributo booleano agentInvoked. Este atributo se establece como verdadero cada vez que un agente de IA activa un formulario, para adaptar el comportamiento de tu app web específicamente a las interacciones basadas en agentes.

Además, SubmitEvent incluye el método respondWith(Promise<any>), por lo que puedes pasar una promesa al navegador que resuelves con los resultados del formulario. Luego, el valor resultante se serializa y se devuelve al modelo como la salida de la herramienta. Para usar este método, primero debes llamar a preventDefault() para detener el envío estándar del formulario del navegador.

<form toolautosubmit toolname="search_tool"
  tooldescription="Search the web" action="/search">
  <input type=text name=query>
</form>
<script>
  document.querySelector("form").addEventListener("submit", (e) => {
    e.preventDefault();
    if (!myFormIsValid()) {
      if (e.agentInvoked) { e.respondWith(myFormValidationErrorPromise) };
      return;
    }
    if (e.agentInvoked) { e.respondWith(Promise.resolve("Search is done!")); }
  });
</script>

El navegador indica que un agente de IA ejecutó una herramienta con el evento "toolactivated". Este evento se activa en la ventana una vez que se precompletan los campos del formulario. Por el contrario, si un usuario cancela la operación del agente o se invoca el método reset(), se activa un evento "toolcancel". Ambos eventos no se pueden cancelar y proporcionan un atributo toolName para la identificación.

window.addEventListener('toolactivated', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was activated.`);
  // TODO: Update UI or validate form if needed.
});

window.addEventListener('toolcancel', ({ toolName }) => {
  console.log(`the tool "${toolName}" execution was cancelled.`);
  // TODO: Let the user know. Update UI.
});

Cómo modificar el indicador de enfoque

Un indicador de enfoque visible es fundamental para informar a los usuarios y agentes dónde se encuentran en una página. Cuando un agente invoca una herramienta correctamente, enfoca el formulario asociado y completa automáticamente sus campos, el navegador activa seudoclases CSS específicas para proporcionar comentarios visuales:

  • :tool-form-active se aplica al elemento form de HTML de la herramienta.
  • Se aplica :tool-submit-active al botón de envío del formulario, si hay uno.

Estas clases se desactivan una vez que se envía el formulario, el agente cancela la acción o el usuario restablece el formulario. Puedes personalizar el CSS para estos estados o usar un estilo predeterminado del navegador.

/* Chrome default declarative form styles. */
form:tool-form-active {
  outline: light-dark(blue, cyan) dashed 1px;
  outline-offset: -1px;
}

input:tool-submit-active {
  outline: light-dark(red, pink) dashed 1px;
  outline-offset: -1px;
}

Obtén más información sobre las prácticas recomendadas y el estilo para el enfoque.

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.