API declarativa

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

Publicado el 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 <form> elemento, 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: Nombra la herramienta con claridad, 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 formulario permanece visible para el usuario.

Si quitas el atributo HTML toolname o tooldescription, la herramienta se anula.

(Opcional) Parámetros de la herramienta

Para mejorar la exactitud, agrega los siguientes atributos HTML a los elementos de formulario individuales:

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

El siguiente formulario usa los parámetros opcionales para el <select> elemento.

<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 presenta el atributo booleano agentInvoked. Este atributo se establece en verdadero cada vez que un agente de IA activa un formulario para adaptar el comportamiento de tu app web específicamente para 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. Luego, el valor resultante se serializa y se muestra al modelo como el resultado de la herramienta. Para usar este método, primero debes llamar a preventDefault() para detener el envío de formularios estándar 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 "toolactivated" evento. Esto se activa en la ventana una vez que se completan previamente 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.
});

Modifica 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 correctamente una herramienta, enfoca el formulario asociado y completa automáticamente sus campos, el navegador activa pseudoclases CSS específicas para obtener comentarios visuales:

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

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 de navegador predeterminado.

/* 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 de enfoque.

Participa 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.