Moduli agentici

Funzionalità web: Attributi WebMCP associati ai moduli

L'API Declarative trasforma gli elementi HTML <form> standard in strumenti WebMCP tramite attributi. Il browser sintetizza uno schema JSON dagli input del modulo e gestisce le interazioni con l'agente.

Moduli Angular Signal: NON aggiungere toolname/tooldescription ai moduli creati con form() da @angular/forms/signals. Aggiungi invece provideExperimentalWebMcpForms() ai provider dell'app e passa l'opzione experimentalWebMcpTool: { name, description } a form(). Angular registra quindi il modulo tramite l'API Imperative, creando lo schema dal modello di indicatori e collegandolo alla convalida e all'invio. Se utilizzi entrambi gli approcci, lo stesso modulo viene registrato due volte.

Attributi del modulo

  • toolname: nome univoco dello strumento.
  • tooldescription: cosa fa lo strumento e quando un agente deve utilizzarlo. Non elencare i campi, le opzioni o i limiti del modulo: il browser li include già nello schema che crea dai controlli del modulo.
  • toolautosubmit: (facoltativo) se presente, l'agente può inviare il modulo senza attendere l'interazione dell'utente.
  • toolparamdescription: (facoltativo) consente di definire una descrizione della proprietà all'interno dello schema JSON. Utilizzala per spiegare il significato del valore (ad esempio, con valori di esempio), non per ripetere le opzioni o i limiti del controllo.
    • Ordine di risoluzione: il browser utilizza toolparamdescription, se presente. In sua assenza, utilizza l'elemento textContent dell'elemento <label> associato (saltando i discendenti etichettabili). Se non esiste un'etichetta, viene utilizzato il valore aria-description.
    • Raggruppamento (Fieldset): per allegare una descrizione a un gruppo di elementi correlati (come i pulsanti <input type="radio">), posiziona toolparamdescription sull'elemento principale <fieldset> più vicino in modo che venga applicato al gruppo di parametri nel suo complesso.

Esempio

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

Gestione degli invii in JavaScript

Quando un agente invia il modulo, SubmitEvent include agentInvoked (booleano) e 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);
  }
});

Eventi del ciclo di vita

document.modelContext genera eventi quando gli agenti iniziano o interrompono l'interazione con uno strumento: toolactivated viene attivato all'avvio dell'esecuzione dello strumento e toolcancel viene attivato quando viene annullato.

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

Feedback visivo (CSS)

Utilizza le pseudoclassi per evidenziare i moduli quando un agente interagisce con questi:

  • :tool-form-active: applicato all'elemento <form> utilizzato attivamente dall'agente.
  • :tool-submit-active: applicato al pulsante di invio quando il browser si mette in pausa per la revisione dell'utente (se toolautosubmit viene omesso).
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;
}

Idoneità del modulo (quando evitarlo)

L'API Declarative è ideale per i moduli standard autonomi. È una scelta sbagliata in questi scenari:

  • Campi altamente dipendenti: moduli in cui gli input modificano le opzioni o la visibilità in base ad altri input. Lo schema sintetizzato non può esprimere bene queste dipendenze.
  • Componenti UI personalizzati: moduli che si basano su input standard non (ad es. canvas, editor di testo RTF) che non serializzano automaticamente i valori.
  • Procedure guidate in più passaggi: workflow complessi che richiedono l'invio di più moduli. In questo caso, l'API imperativa o l'interazione DOM standard sono più adatte.

Quando utilizzare toolautosubmit

  • Operazioni e query di sola lettura: ricerche, filtri, recupero di dettagli o controllo dello stato (ad es. ricerca di un modello di auto, ricerca in una directory, controllo della disponibilità di un articolo).
  • Azioni reversibili a basso rischio: azioni del modulo che possono essere facilmente annullate o perfezionate manualmente dall'utente (ad es. l'aggiunta di articoli a un carrello, l'applicazione di un codice coupon, il salvataggio di una bozza o l'impostazione di opzioni di layout temporanee).

Quando omettere toolautosubmit

  • Azioni distruttive o irreversibili: eliminazione di record, ripristino delle configurazioni di sistema o cancellazione di database.
  • Azioni finanziarie e transazionali: invio di un modulo di pagamento, trasferimento di fondi, autorizzazione di pagamenti di abbonamenti o invio di ordini finali.
  • Comunicazione con gli utenti ad alto impatto: invio di una domanda di lavoro finale, invio di email/messaggi ad altri utenti reali o pubblicazione di contenuti visibili pubblicamente.
  • Impostazioni sensibili dell'account: modifica delle password, dei ruoli/delle autorizzazioni degli utenti o aggiornamento dei dati di fatturazione/del profilo.

Strategie di riserva

L'API dichiarativa WebMCP è sicura da utilizzare in tutti i browser. I browser che non supportano WebMCP ignoreranno gli attributi tool* e <form> continuerà a funzionare come un normale modulo HTML. Non è richiesto il rilevamento delle funzionalità.