API dichiarativa

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

Pubblicato: 18 maggio 2026

Spiegazione 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 intrapresa dallo strumento e il suo scopo.

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

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

Quando un agente chiama toolname, il browser mette a fuoco il modulo e compila il relativo campo. Il modulo rimane visibile all'utente.

Se rimuovi l'attributo HTML toolname o tooldescription, lo strumento viene deregistrato.

(Facoltativo) Parametri dello strumento

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

  • toolparamdescription: mappa gli elementi della mappa a una descrizione della proprietà all'interno dello schema JSON. Senza questo attributo, il browser utilizza i contenuti all'interno del tag <label> associato e ignora 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 modifica della navigazione.

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 specificamente per le interazioni basate su agenti.

Inoltre, SubmitEvent include il metodo respondWith(Promise<any>), in modo da poter passare una promessa al browser che risolvi 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'evento "toolactivated". Questo evento viene attivato nella finestra una volta precompilati i campi del modulo. Al contrario, se un utente annulla l'operazione dell'agente o viene richiamato il metodo reset(), viene attivato un evento "toolcancel". 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.
});

Modificare l'indicatore di selezione

Un indicatore di messa a fuoco 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 una volta inviato il modulo, annullata l'azione dall'agente o reimpostato il modulo dall'utente. Puoi personalizzare il CSS per questi stati o fare affidamento a uno stile del browser predefinito.

/* 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 messa a fuoco.

Interagire e condividere feedback

WebMCP è in fase di discussione e potrebbe subire modifiche in futuro. Se provi questa API e hai un feedback, saremo felici di riceverlo.