Formularios de agentes

Funciones web: Atributos de WebMCP asociados a formularios

La API declarativa transforma los elementos HTML <form> estándar en herramientas de WebMCP a través de atributos. El navegador sintetiza un esquema JSON a partir de las entradas del formulario y controla las interacciones del agente.

Formularios de indicadores de Angular: NO agregues toolname/tooldescription a los formularios creados con form() de @angular/forms/signals. En su lugar, agrega provideExperimentalWebMcpForms() a los proveedores de la app y pasa la opción experimentalWebMcpTool: { name, description } a form(). Luego, Angular registra el formulario a través de la API imperativa, compila el esquema a partir del modelo de indicadores y lo conecta a la validación y el envío. Si usas ambos enfoques, se registrará el mismo formulario dos veces.

Atributos de formulario

  • toolname: Es el nombre único de la herramienta.
  • tooldescription: Es lo que hace la herramienta y cuándo debe usarla un agente. No incluyas los campos, las opciones ni los límites del formulario: el navegador ya los incluye en el esquema que compila a partir de los controles del formulario.
  • toolautosubmit: (Opcional) Si está presente, el agente puede enviar el formulario sin esperar la interacción del usuario.
  • toolparamdescription: (Opcional) Proporciona una forma de definir una descripción de propiedad dentro del esquema JSON. Úsala para explicar lo que significa el valor (por ejemplo, con valores de muestra), no para repetir las opciones o los límites del control.
    • Orden de resolución: El navegador usa toolparamdescription si está presente. En su ausencia, usa el textContent del <label> asociado (omitiendo los descendientes etiquetables). Si no existe ninguna etiqueta, se recurre a la aria-description.
    • Agrupación (conjuntos de campos): Para adjuntar una descripción a un grupo de elementos relacionados (como los botones <input type="radio">), coloca toolparamdescription en el elemento superior <fieldset> más cercano para que se aplique al grupo de parámetros en su totalidad.

Ejemplo

<form toolname="search-cars" 
      tooldescription="Perform a car make/model search" 
      toolautosubmit>
  <label for="make">Vehicle Make</label>
  <input type="text" id="make" name="make" required>
  
  <label for="model">Vehicle Model</label>
  <input type="text" id="model" name="model" toolparamdescription="e.g., 330i, F-150" required>
  
  <button type="submit">Search</button>
</form>

Cómo controlar los envíos en JavaScript

Cuando un agente envía el formulario, el SubmitEvent incluye agentInvoked (booleano) y respondWith(promise).

document.querySelector('form').addEventListener('submit', (event) => {
  event.preventDefault();

  // Validate the form
  const formValidationErrors = myFormIsValid();

  if (formValidationErrors.length > 0) {
    if (event.agentInvoked) {
      const errorString =
        'Validation failed: ' +
        formValidationErrors
          .map((err) => `${err.field} (${err.message})`)
          .join(', ');

      event.respondWith(Promise.resolve(errorString));
    }
    return;
  }

  const resultPromise = performAsyncSearch(new FormData(event.target));

  // Return the result directly to the agent without navigation
  if (event.agentInvoked) {
    event.respondWith(resultPromise);
  }
});

Eventos de ciclo de vida

document.modelContext emite eventos cuando los agentes comienzan o dejan de interactuar con una herramienta: toolactivated se activa cuando se inicia la ejecución de la herramienta y toolcancel se activa cuando se cancela.

// Starting in Chrome 156, these events are dispatched on `document.modelContext`.
// Older versions dispatch them on `window`. Feature-detect the event handler
// property to pick the right target for backward compatibility.
const targetFor = (type, listener, options) =>
  (`on${type}` in (document.modelContext ?? {}) ? document.modelContext : window)
    .addEventListener(type, listener, options);

targetFor('toolactivated', ({ toolName }) => {
  console.log(`Tool "${toolName}" started execution.`);
});

targetFor('toolcancel', ({ toolName }) => {
  console.log(`Tool "${toolName}" execution is cancelled.`);
});

Comentarios visuales (CSS)

Usa pseudoclases para destacar los formularios cuando un agente interactúa con ellos:

  • :tool-form-active: Se aplica al elemento <form> que usa el agente de forma activa.
  • :tool-submit-active: Se aplica al botón de envío cuando el navegador se detiene para que el usuario revise la información (si se omite toolautosubmit).
form:tool-form-active {
  outline: 2px dashed blue;
  background-color: rgba(0, 0, 255, 0.05);
}

button:tool-submit-active {
  outline: 2px dashed red;
  animation: pulse 2s infinite;
}

Idoneidad del formulario (cuándo evitarlo)

La API declarativa es ideal para formularios estándar independientes. No es una buena opción en las siguientes situaciones:

  • Campos altamente dependientes: Formularios en los que las entradas cambian las opciones o la visibilidad en función de otras entradas. El esquema sintetizado no puede expresar bien estas dependencias.
  • Componentes de IU personalizados: Formularios que dependen de entradas no estándar (p.ej., lienzo, editores de texto enriquecido) que no serializan automáticamente los valores.
  • Asistentes de varios pasos: Flujos de trabajo complejos que requieren varios envíos de formularios. La API imperativa o la interacción estándar con el DOM son más adecuadas en este caso.

Cuándo usar toolautosubmit

  • Operaciones y consultas de solo lectura: Búsquedas, filtros, recuperación de detalles o verificación de estado (p.ej., búsqueda de un modelo de automóvil, búsqueda en un directorio, verificación de disponibilidad de stock).
  • Acciones reversibles de bajo riesgo: Acciones de formulario que el usuario puede deshacer o definir mejor con facilidad de forma manual (p. ej., agregar artículos a un carrito, aplicar un código de cupón, guardar un borrador o establecer opciones de diseño temporales)

Cuándo omitir toolautosubmit

  • Acciones destructivas o irreversibles: Borrar registros, restablecer configuraciones del sistema o borrar bases de datos.
  • Acciones financieras y transaccionales: Enviar un formulario de confirmación de compra, transferir fondos, autorizar pagos de suscripciones o realizar pedidos finales
  • Comunicación de alto impacto con el usuario: Envío de una solicitud de empleo final, envío de correos electrónicos o mensajes a otros usuarios reales, o publicación de contenido de acceso público.
  • Configuración de la cuenta sensible: Cambiar contraseñas, modificar roles o permisos de usuario, o actualizar la información de facturación o del perfil.

Estrategias de resguardo

La API declarativa de WebMCP se puede usar de forma segura en todos los navegadores. Los navegadores que no admiten WebMCP ignorarán los atributos tool*, y el <form> seguirá funcionando como un formulario HTML normal. No se requiere detección de funciones.