Che cos'è un manifesto UCP e quando pubblicarne uno è la scelta sbagliata

Un manifesto UCP è un file JSON in /.well-known/ucp che indica agli agenti di acquisto IA che cosa sa fare il tuo negozio e dove chiamarlo. Non è un file di marketing né un gesto simbolico: dichiara endpoint API reali e le chiavi pubbliche usate per verificare i tuoi messaggi firmati. Questa guida spiega che cosa contiene il file, che cosa no, come servirlo da Shopify e quando è sbagliato pubblicarne uno.

Che cos'è UCP

Universal Commerce Protocol è uno standard aperto, pubblicato da Google con licenza Apache 2.0, per la scoperta dei commercianti da parte delle macchine. Dove llms.txt e agents.md descrivono un'azienda in prosa che un assistente può citare, UCP descrive un'interfaccia: i servizi che un agente può chiamare per esplorare il catalogo, ordinare e seguire un ordine, senza persone nel mezzo.

Il punto di ingresso è un unico URL well-known. Un agente richiede https://tuo-negozio.example/.well-known/ucp, legge il JSON e scopre quale versione del protocollo parli, quali endpoint contattare e come verificare che i messaggi attribuiti a te vengano davvero da te.

Che cosa deve contenere il file

Due chiavi obbligatorie di primo livello: ucp e signing_keys.

• ucp.version — la versione del protocollo, come data: "2026-04-08". Le versioni UCP sono date, non SemVer.
• ucp.services — una mappa da un identificatore di servizio come dev.ucp.shopping ai suoi binding di trasporto: versione, URL della specifica, trasporto (rest, mcp, a2a o embedded), URL dello schema e l'endpoint che l'agente deve chiamare.
• ucp.capabilities — una mappa delle funzionalità all'interno di quei servizi, ad esempio dev.ucp.shopping.checkout, ciascuna con versione e schema propri. Le estensioni dichiarano la capability da cui derivano.
• signing_keys — chiavi pubbliche in formato JWK, usate per verificare webhook e messaggi autenticati che firmi (RFC 9421, HTTP Message Signatures). La specifica lo elenca al primo livello, ma i manifesti generati da Shopify lo omettono del tutto: la sua assenza è quindi normale e non un difetto da correggere.

ucp.payment_handlers è facoltativo. Se supporti più versioni del protocollo, una mappa supported_versions punta a URL di profilo specifici per versione.

Un manifesto minimo valido

{
  "ucp": {
    "version": "2026-04-08",
    "services": {
      "dev.ucp.shopping": [{
        "version": "2026-04-08",
        "spec": "https://ucp.dev/2026-04-08/specification/overview",
        "transport": "rest",
        "endpoint": "https://business.example.com/ucp/v1",
        "schema": "https://ucp.dev/2026-04-08/services/shopping/rest.openapi.json"
      }]
    },
    "capabilities": {
      "dev.ucp.shopping.checkout": [{
        "version": "2026-04-08",
        "spec": "https://ucp.dev/2026-04-08/specification/checkout",
        "schema": "https://ucp.dev/2026-04-08/schemas/shopping/checkout.json"
      }]
    }
  },
  "signing_keys": [{
    "kid": "business_2026",
    "kty": "EC", "crv": "P-256", "use": "sig", "alg": "ES256",
    "x": "…", "y": "…"
  }]
}

Osserva che cosa implica quell'endpoint: è un URL reale che un agente chiamerà. Un manifesto è una promessa su un'infrastruttura che deve esistere.

Su Shopify ne hai già uno

È il punto che la maggior parte delle guide sbaglia. Shopify ha sviluppato UCP insieme a Google e lo attiva sui negozi per impostazione predefinita: la tua vetrina serve quindi già un manifesto su /.well-known/ucp senza che tu configuri nulla. Controlla il tuo:

curl -sSL https://tuo-negozio.example/.well-known/ucp | jq .

Un manifesto Shopify reale dichiara un trasporto mcp che punta a https://tuo-negozio.myshopify.com/api/ucp/mcp, una mappa supported_versions, capability tra cui checkout, cart, fulfillment, discount, order oltre a ricerca e consultazione del catalogo, e payment handler come Google Pay e Shop Pay. Nulla di tutto ciò lo scrivi tu, e non dovresti provare a sostituirlo.

Su Shopify il lavoro è quindi verificare, non scrivere: conferma che il file risolva sul dominio di produzione, che sopravviva a qualunque cosa stia davanti al negozio e che nulla di ciò che hai aggiunto lo blocchi. I casi in cui lo scrivi tu sono headless e front-end personalizzati, dove controlli il server web e la piattaforma non serve il percorso al posto tuo. Lì un redirect URL o un app proxy è la strada abituale — e tutto quanto detto sopra sul dichiarare solo endpoint che rispondono resta valido.

Quando non pubblicarne uno

Un manifesto vuoto o inventato è peggio di nessun manifesto. Se services elenca un endpoint che non risponde, un agente ti scopre, lo chiama e fallisce — un esito peggiore di un 404 pulito, che gli dice subito di ripiegare sulla lettura delle tue pagine.

Vale anche per i siti che non sono negozi. Il nostro sito vetrina restituisce deliberatamente 404 su /.well-known/ucp: non vende nulla, quindi non c'è alcun endpoint da dichiarare, e la specifica non prevede alcun modo per dire «non sono un commerciante». Uno stub che esiste solo per far diventare verde un controllo è una casella spuntata, non prontezza.

Come verificare il tuo

Tre cose, in quest'ordine: il file restituisce 200 a un client non autenticato, il contenuto si interpreta come JSON e ogni URL in services risolve. I controlli del Pilastro A di Sichta coprono i primi due come controllo A1 e riportano l'esito separatamente dagli altri rilievi, così un manifesto mancante diventa una voce precisa invece di un punteggio da interpretare.

La specifica è ancora in movimento — le versioni sono date e lo schema evolve — quindi tratta il manifesto come qualcosa che rigeneri, non che scrivi una volta e dimentichi.

In breve

Pubblica un manifesto UCP quando hai un endpoint commerce che un agente può davvero chiamare. Servilo su /.well-known/ucp come JSON non autenticato, dichiara un endpoint e signing_keys reali, e verificalo con un semplice client HTTP invece che con un browser. Se quell'infrastruttura non c'è ancora, un 404 è la risposta onesta — e llms.txt più agents.md sono ciò che paga oggi.