API dichiarativa

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

Data di pubblicazione: 18 maggio 2026

Divulgatore Web Estensioni Stato di Chrome Intenzione
GitHub Prova per sviluppatori Prova per sviluppatori Prova per sviluppatori Prova per sviluppatori Visualizza Intenzione di sperimentare

Utilizza l'API dichiarativa per trasformare i moduli HTML standard in strumenti WebMCP aggiungendo annotazioni. Le annotazioni definiscono il nome e lo scopo dello strumento nell'elemento <form>, mentre i campi fungono da parametri dello strumento. Il browser traduce questi elementi in una rappresentazione strutturata che gli agenti possono utilizzare in modo simile agli strumenti imperativi.

Prima di utilizzare questa API, leggi gli esempi di casi d'uso.

Registrazione dello strumento

Aggiungi i seguenti attributi HTML al modulo:

  • toolname: assegna un nome chiaro allo strumento, in base al suo scopo.
  • tooldescription: descrivi l'azione eseguita dallo strumento e il suo scopo.

Ad esempio, il seguente modulo si trova all'indirizzo example.com/get-customer-support:

<form toolname="createSupportRequest" tooldescription="Submits a request for customer support.">
</form>

Quando un agente chiama toolname, il browser porta il modulo in primo piano e ne compila il campo. Il modulo rimane visibile all'utente.

Se rimuovi l'attributo HTML toolname o tooldescription, la registrazione dello strumento viene annullata.

(Facoltativo) Parametri dello strumento

Per migliorare l'accuratezza, aggiungi i seguenti attributi HTML ai singoli elementi del modulo:

  • toolparamdescription: mappa gli elementi a una descrizione della proprietà all'interno dello schema JSON. Senza questo attributo, il browser utilizza il contenuto all'interno dell'elemento <label> associato e salta i discendenti etichettabili. Se non è presente un'etichetta, il browser fa riferimento a aria-description.

Il seguente modulo utilizza i parametri facoltativi per l'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>

Il browser interpreta questo modulo come uno strumento, rappresentato dal seguente 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"
      ]
    }
  }
]

Invia il modulo

Hai due opzioni per l'invio del modulo:

  • L'utente deve fare clic manualmente su Invia per completare l'attività.
  • Aggiungi toolautosubmit per attivare l'invio e una navigazione quando il modello richiama questo strumento.

L'interfaccia SubmitEvent introduce l'attributo booleano agentInvoked. Questo attributo è impostato su true ogni volta che un modulo viene attivato da un agente AI, per adattare il comportamento della tua app web in modo specifico per le interazioni basate su agenti.

Inoltre, SubmitEvent include il metodo respondWith(Promise<any>), in modo da poter passare al browser una promessa che viene risolta con i risultati del modulo. Il valore risultante viene quindi serializzato e restituito al modello come output dello strumento. Per utilizzare questo metodo, devi prima chiamare preventDefault() per interrompere l'invio standard del modulo del browser.

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

Il browser segnala che un agente AI ha eseguito uno strumento con l'"toolactivated" evento. Questo evento viene attivato nella finestra una volta che i campi del modulo sono stati precompilati. Al contrario, se un utente annulla l'operazione dell'agente o viene richiamato il metodo reset(), viene attivato un "toolcancel" evento. Entrambi questi eventi non sono annullabili e forniscono un attributo toolName per l'identificazione.

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 l'indicatore di selezione

Un indicatore di selezione visibile è fondamentale per informare utenti e agenti della loro posizione in una pagina. Quando un agente richiama correttamente uno strumento, mette a fuoco il modulo associato e compila automaticamente i relativi campi, il browser attiva pseudo-classi CSS specifiche per il feedback visivo:

  • :tool-form-active viene applicato all'elemento HTML form dello strumento.
  • :tool-submit-active viene applicato al pulsante di invio del modulo, se presente.

Queste classi vengono disattivate quando il modulo viene inviato, l'agente annulla l'azione o l'utente reimposta il modulo. Puoi personalizzare il CSS per questi stati o affidarti a uno stile predefinito del browser.

/* 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;
}

Scopri di più sulle best practice e sullo stile per la selezione.

Partecipa e condividi feedback

WebMCP è in fase di discussione attiva ed è soggetto a modifiche in futuro. Se provi questa API e hai feedback, non esitare a comunicarcelo.