Tutorial sul Protocollo di Commercio Universale: crea il tuo primo server UCP

In questa guida scoprirai cos'è l'Universal Commerce Protocol (UCP), per chi è stato creato, perché serve un nuovo standard per il commercio e come funziona la sua architettura. 

Seguirai anche un percorso pratico per configurare un tuo server UCP di esempio, esplorarne il discovery profile, creare una sessione di checkout ed eseguire localmente un flusso completo di esempio. 

Questo ti darà sia una comprensione chiara del protocollo sia un punto di partenza pratico per testare come funziona UCP in un'implementazione reale.

Introduzione all'Universal Commerce Protocol

L'Universal Commerce Protocol è uno standard aperto che aiuta agenti AI, app, aziende e provider di pagamenti a collaborare in un unico flusso di acquisto condiviso. Invece di creare un'integrazione personalizzata per ogni nuovo partner, UCP fornisce un modo comune di comunicare.

UCP è progettato per lo shopping guidato dagli agenti, in cui le persone scoprono e acquistano prodotti tramite assistenti AI e interfacce conversazionali. Supporta l'intero percorso, dalla scoperta di ciò che un'azienda offre all'avvio del checkout e alla gestione dell'acquisto in modo strutturato.

Fonte: Google Developers Blog

In parole semplici, UCP funziona come un linguaggio condiviso per il commercio. Un'azienda può pubblicare ciò che supporta e un agente può leggere queste informazioni e interagire senza dover creare un'integrazione API ad hoc. Shopify lo descrive come un'infrastruttura costruita per alimentare il commercio guidato da agenti su larga scala.

UCP è anche open source e neutrale rispetto ai vendor. È progettato per funzionare con i sistemi di commercio esistenti ed è compatibile con l'Agent Payments Protocol (AP2) per pagamenti sicuri guidati da agenti. Può anche funzionare su diversi trasporti, inclusi API REST, comunicazione agent-to-agent e MCP. 

Per chi è stato creato l'Universal Commerce Protocol?

L'UCP è stato creato per i principali gruppi coinvolti nel commercio digitale moderno. L'obiettivo è dare a tutti un modo condiviso di comunicare, così da collaborare senza dover creare integrazioni personalizzate per ogni collegamento.

È progettato principalmente per:

1. Agenti AI e piattaforme consumer

Sono le app, gli assistenti e le superfici di scoperta che aiutano gli utenti a trovare prodotti e fare acquisti. UCP li aiuta a capire cosa supporta un'azienda e a interagirci in modo strutturato. Google descrive questo come il collegamento tra le superfici consumer e i backend delle aziende per uno shopping senza attriti.

2. Aziende e merchant

UCP aiuta le aziende a esporre i propri prodotti, i flussi di checkout e le funzionalità supportate in un formato standard. In questo modo è più semplice collaborare con diverse piattaforme e agenti AI senza dover creare un'integrazione separata per ciascuno.

3. Provider di pagamenti

Anche i provider di pagamenti fanno parte dell'ecosistema UCP. Il protocollo è progettato per supportare diversi handler di pagamento e diverse credenziali in modo flessibile, così i pagamenti possono essere gestiti in sicurezza tra sistemi differenti.

4. Sviluppatori e costruttori di protocolli

UCP è open source, quindi è pensato anche per gli sviluppatori che vogliono implementare, estendere o contribuire allo standard. Il progetto UCP invita esplicitamente aziende, sviluppatori e provider di pagamenti a contribuire a definire il futuro del protocollo.

In parole semplici, UCP è pensato per chiunque sia coinvolto nel commercio abilitato dall'AI: la piattaforma che aiuta l'utente a fare acquisti, l'azienda che vende il prodotto, il sistema di pagamento che elabora la transazione e gli sviluppatori che costruiscono le connessioni tra loro.

Perché è necessario un nuovo standard per il commercio

Serve un nuovo standard perché la maggior parte dei sistemi attuali è stata creata per siti web tradizionali e app mobile, non per assistenti AI e shopping conversazionale. 

Quel modello precedente spesso dipende da API personalizzate e integrazioni ad hoc, il che lo rende lento e difficile da scalare su molte piattaforme. UCP è stato creato per risolvere questo problema offrendo a aziende, agenti e piattaforme un modo condiviso di comunicare.

Man mano che sempre più persone iniziano a fare acquisti tramite strumenti AI, il commercio deve supportare azioni in tempo reale come scoperta dei prodotti, checkout, sconti e aggiornamenti degli ordini all'interno della stessa conversazione. 

UCP è progettato per questo nuovo stile di shopping, in cui l'esperienza è più interattiva e avviene su diverse superfici digitali.

È anche necessario perché l'ecosistema del commercio attuale è frammentato. Diverse aziende, provider di pagamenti e piattaforme utilizzano spesso sistemi differenti. UCP li avvicina grazie a uno standard comune, così possono collaborare senza ricostruire ogni volta le stesse integrazioni.

In breve, UCP serve perché gli strumenti di commercio di ieri non sono stati creati per lo shopping guidato dall'AI. Fornisce all'industria una base più moderna e flessibile per come le persone scopriranno e acquisteranno prodotti in futuro.

Comprendere l'architettura dell'Universal Commerce Protocol

L'Universal Commerce Protocol (UCP) è un sistema modulare per il commercio guidato da agenti. Offre ad aziende, agenti AI e provider di pagamenti un modo condiviso di gestire il percorso di acquisto, dalla scoperta al checkout e oltre. 

Invece di creare integrazioni personalizzate separate per ogni piattaforma, UCP consente a un'azienda di pubblicare ciò che supporta, così che un agente possa leggere queste informazioni e seguire un flusso standard. 

UCP è progettato per essere modulare ed estensibile, supporta trasporti come REST, MCP e A2A, e funziona con i payment handler così che le aziende possano utilizzare più facilmente le configurazioni di pagamento esistenti.

1. L'azienda pubblica un discovery profile

Un'azienda abilitata a UCP espone un profilo su /.well-known/ucp. Questo profilo indica a piattaforme e agenti ciò che l'azienda supporta prima che inizi qualsiasi transazione, incluse le funzionalità disponibili e gli endpoint.

2. L'agente legge le funzionalità supportate

Dopo la discovery, l'agente verifica quali servizi e funzionalità offre l'azienda. Il lancio iniziale di UCP si concentra su funzionalità core come Checkout, Identity Linking e Order Management, che costituiscono i principali mattoni del protocollo.

3. Le estensioni aggiungono funzionalità extra

UCP mantiene semplice il flusso core, ma le aziende possono aggiungere estensioni opzionali quando serve. Queste estensioni si basano sulle funzionalità di base e permettono di supportare caratteristiche più ricche senza cambiare l'intero protocollo.

4. Il flusso utilizza un trasporto supportato

Una volta che l'agente sa cosa è supportato, può interagire con l'azienda usando un trasporto supportato come REST, MCP o A2A. Questo rende più semplice utilizzare la stessa logica di commercio tra API, strumenti AI e sistemi agent-to-agent.

5. Il pagamento è gestito tramite payment handler

UCP separa il flusso di commercio dallo strato dei pagamenti. Le aziende possono dichiarare i payment handler supportati e il protocollo è progettato in modo che i merchant possano continuare a usare le loro integrazioni di pagamento esistenti invece di ricostruire tutto da zero.

6. Pagamenti sicuri guidati da agenti possono usare AP2

UCP è compatibile con l'Agent Payments Protocol (AP2), che aggiunge uno strato sicuro per i pagamenti guidati da agenti. Questo aiuta a supportare un'autorizzazione più sicura quando un agente AI agisce per conto di un utente.

Walkthrough end-to-end dell'Universal Commerce Protocol

Questa guida mostra un flusso completo di Universal Commerce Protocol usando l'implementazione di riferimento in Python. Imposterai il server merchant di esempio, caricherai un catalogo demo di un negozio di fiori, scoprirai le funzionalità dell'azienda, creerai una sessione di checkout, applicherai uno sconto e poi fermerai il server.

Passaggio 1: Configura il server dell'azienda

In questo passaggio installerai uv per la gestione delle dipendenze Python, quindi clonerai sia lo UCP Python SDK sia il repository del server di esempio. Il README del server di esempio segue lo stesso schema di setup e segnala che, per gli esempi, il percorso relativo all’SDK è importante.

Dato che il nostro sistema operativo è Linux, useremo il seguente comando per installare uv. uv è un gestore di pacchetti ed ambienti Python veloce e affidabile. Ha uno scopo simile a strumenti come Anaconda, ma è molto più leggero e rapido.

curl -LsSf https://astral.sh/uv/install.sh | sh

Una volta completata l'installazione, ricarica la sessione del terminale così che il comando uv sia disponibile nella shell corrente.

source ~/.bashrc

Ora crea una nuova cartella chiamata sdk. Questa cartella conterrà lo Universal Commerce Protocol Python SDK quando lo cloneremo dal repository GitHub. 

mkdir sdk
git clone https://github.com/Universal-Commerce-Protocol/python-sdk.git 
sdk/python

Ora passa alla directory sdk/python, dove è stato clonato il repository dell'SDK.

pushd sdk/python

Una volta dentro la directory dell'SDK, installa tutte le dipendenze Python richieste dall'SDK usando uv sync.

uv sync

Dopo aver installato le dipendenze, torna alla precedente directory di lavoro.

popd

Ora clona il repository degli esempi, che contiene il server merchant di riferimento in Python utilizzato in questo walkthrough.

git clone https://github.com/Universal-Commerce-Protocol/samples.git

Quindi, entra nell'esempio di server Python all'interno del repository degli esempi.

cd samples/rest/python/server

Infine, installa tutte le dipendenze Python necessarie per eseguire il server di esempio.

uv sync

A questo punto, il server aziendale di esempio è pronto nel tuo workspace. Questo server implementa già le funzionalità principali di shopping definite da UCP.

Passaggio 2: Crea un database prodotti di esempio

In questo passaggio creerai un negozio demo locale basato su SQLite per l'azienda di esempio. L'azienda di esempio in questo tutorial è un negozio di fiori, e questo comando carica il catalogo prodotti di esempio e il database delle transazioni che il server utilizzerà.

Per prima cosa, crea una cartella temporanea in cui verranno archiviati i file del database.

mkdir /tmp/ucp_test

Poi esegui lo script di import per creare e popolare i database di prodotti e transazioni.

uv run import_csv.py \
  --products_db_path=/tmp/ucp_test/products.db \
  --transactions_db_path=/tmp/ucp_test/transactions.db \
  --data_dir=../test_data/flower_shop

Questo comando fa quanto segue:

• --products_db_path crea il database del catalogo prodotti.
• --transactions_db_path crea il database delle transazioni utilizzato per lo stato del checkout.
• --data_dir=../test_data/flower_shop punta ai dati di esempio del negozio di fiori inclusi nel repository.

Una volta completato questo passaggio, i dati del tuo negozio di esempio locale sono pronti e il server potrà usarli.

Passaggio 3: Avvia il server dell'azienda

In questo passaggio avvierai il server UCP di esempio dell'azienda. Questo server utilizzerà i database di prodotti e transazioni creati nel passaggio precedente ed esporrà le API di shopping UCP sulla porta 8182.

Esegui il seguente comando per avviare il server in background.

uv run server.py \
  --products_db_path=/tmp/ucp_test/products.db \
  --transactions_db_path=/tmp/ucp_test/transactions.db \
  --port=8182 &
SERVER_PID=$!

Questo comando fa quanto segue:

• uv run server.py avvia il server Python di esempio.
• --products_db_path collega il server al database dei prodotti.
• --transactions_db_path collega il server al database delle transazioni.
• --port=8182 indica al server di funzionare sulla porta 8182.
• & esegue il processo in background così puoi continuare a usare il terminale.
• SERVER_PID=$! salva l'ID del processo, così potrai fermare il server in seguito.

A questo punto, il server dell'azienda è in esecuzione ed è pronto a ricevere richieste da un agente.

Passaggio 4: Scopri le funzionalità dell'azienda

In questo passaggio interrogherai l'endpoint di discovery di UCP. Ogni azienda abilitata a UCP pubblica un documento di discovery su /.well-known/ucp, che permette agli agenti di capire cosa supporta l'azienda prima di effettuare richieste.

Per prima cosa, salva l'URL del server in una variabile, così i prossimi comandi saranno più leggibili.

export SERVER_URL=http://localhost:8182

Ora recupera il documento di discovery UCP dal server dell'azienda.

curl -s $SERVER_URL/.well-known/ucp

Questa risposta comunica all'agente:

• quale versione di UCP supporta il server,
• quali servizi sono disponibili,
• quali funzionalità sono implementate, come checkout e sconti,
• e quali payment handler o schemi sono supportati.

Questo passaggio di discovery è importante perché elimina la necessità di integrazioni personalizzate hard-coded. L'agente può prima ispezionare il server e poi decidere come interagirci.

Passaggio 5: Crea una sessione di checkout

In questo passaggio creerai una nuova sessione di checkout usando la funzionalità di checkout di UCP. Qui l'agente invia al server dell'azienda il prodotto selezionato, le informazioni dell'acquirente e la struttura del pagamento.

Prima di inviare la richiesta, genera le intestazioni richieste. Queste intestazioni aiutano con il tracciamento delle richieste, l'idempotenza e la validazione della firma.

export REQUEST_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export IDEMPOTENCY_KEY=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export REQUEST_SIGNATURE="dev"

Questo fa quanto segue:

• REQUEST_ID crea un identificatore univoco per la richiesta.
• IDEMPOTENCY_KEY garantisce che la stessa richiesta non venga elaborata due volte in caso di retry.
• REQUEST_SIGNATURE fornisce l'intestazione di firma richiesta. In una demo locale, si può usare "dev" se non è applicata una validazione rigorosa della firma.

Ora invia la richiesta di checkout al server.

curl -X POST "$SERVER_URL/checkout-sessions" \
  -H "Content-Type: application/json" \
  -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
  -H "request-id: $REQUEST_ID" \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -H "request-signature: $REQUEST_SIGNATURE" \
  -d '{
    "line_items": [
      { "item": { "id": "bouquet_roses", "title": "Red Rose" }, "quantity": 1 }
    ],
    "buyer": { "full_name": "John Doe", "email": "john.doe@example.com" },
    "currency": "USD",
    "payment": { "handlers": [], "instruments": [] }
  }'

Questa richiesta include:

• line_items per definire cosa l'acquirente vuole acquistare,
• item.id per identificare il prodotto,
• item.title per fornire un nome leggibile,
• quantity per specificare quante unità vengono acquistate,
• buyer per includere i dettagli del cliente,
• currency per definire la valuta del checkout,
• e payment per fornire la struttura di pagamento richiesta.

La risposta restituirà un oggetto sessione di checkout. Questo include il nuovo ID di checkout, gli ID delle righe, i totali, le informazioni dell'acquirente e lo stato corrente del checkout.

Passaggio 6: Applica sconti tramite UCP

In questo passaggio aggiornerai la sessione di checkout esistente e applicherai un codice sconto. Gli sconti in UCP sono implementati come estensione della funzionalità di checkout, quindi lo sconto viene aggiunto come parte della richiesta di aggiornamento del checkout.

Per prima cosa, salva il vero ID del checkout e l'ID della riga restituiti dalla risposta di checkout precedente.

export CHECKOUT_ID=5dd08e18-c9c1-4fa1-a0d1-885ca81cda29
export LINE_ITEM_ID=ed72ebe6-2484-4e7b-afc8-a8ff5c8f430e

Poi genera un nuovo request ID e una nuova idempotency key per questa richiesta di aggiornamento.

export REQUEST_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export IDEMPOTENCY_KEY=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)
export REQUEST_SIGNATURE="dev"

Ora invia la richiesta di aggiornamento del checkout includendo il codice sconto.

curl -X PUT "$SERVER_URL/checkout-sessions/$CHECKOUT_ID" \
  -H "Content-Type: application/json" \
  -H "UCP-Agent: profile=\"https://agent.example/profile\"" \
  -H "request-id: $REQUEST_ID" \
  -H "idempotency-key: $IDEMPOTENCY_KEY" \
  -H "request-signature: $REQUEST_SIGNATURE" \
  -d "{
    \"id\": \"$CHECKOUT_ID\",
    \"line_items\": [
      {
        \"id\": \"$LINE_ITEM_ID\",
        \"item\": { \"id\": \"bouquet_roses\", \"title\": \"Red Rose\" },
        \"quantity\": 1
      }
    ],
    \"buyer\": {
      \"full_name\": \"John Doe\",
      \"email\": \"john.doe@example.com\"
    },
    \"currency\": \"USD\",
    \"discounts\": {
      \"codes\": [\"10OFF\"]
    },
    \"payment\": {
      \"handlers\": [],
      \"instruments\": []
    }
  }"

Questa richiesta fa quanto segue:

• aggiorna il checkout esistente usando PUT,
• include l'ID del checkout originale,
• include di nuovo la riga dell'ordine,
• aggiunge la sezione discounts,
• e applica il codice 10OFF.

La risposta dovrebbe restituire l'oggetto di checkout aggiornato con:

• totali ricalcolati,
• l'importo dello sconto,
• il totale finale aggiornato,
• ed eventuali dettagli dello sconto applicato.

Il codice sconto è valido; dovresti vedere la variazione di prezzo nella risposta.

Passaggio 7: Spegni il server

In questo passaggio finale fermerai il server dell'azienda di esempio avviato in precedenza. Poiché hai salvato l'ID del processo all'avvio del server, puoi spegnerlo facilmente con un solo comando.

Esegui il seguente comando per fermare il server.

kill $SERVER_PID

Dall'inizio alla fine, hai creato e testato con successo un flusso UCP end-to-end sulla tua macchina locale.

Hai:

• installato gli strumenti Python necessari usando uv,
• clonato i repository dello UCP Python SDK e del server di esempio,
• creato un database prodotti di esempio per un negozio di fiori,
• avviato il server dell'azienda,
• scoperto le funzionalità UCP del server tramite l'endpoint di discovery,
• creato una sessione di checkout come agente,
• aggiornato quel checkout applicando un codice sconto,
• e infine spento il server.

In parole semplici, hai configurato un'azienda abilitata a UCP funzionante, ti sei connesso come un agente, hai creato un checkout e hai testato come UCP gestisce aggiornamenti come gli sconti. Questo ti offre un esempio di base completo di come un'azienda e un agente possono interagire usando l'Universal Commerce Protocol.

Conclusione

L'Universal Commerce Protocol offre all'industria una base condivisa per il commercio guidato dall'AI. Crea un modo standard per aziende, agenti AI e sistemi di pagamento di comunicare, rendendo più facile supportare discovery, checkout, aggiornamenti e pagamenti senza dover ricostruire integrazioni personalizzate per ogni nuova piattaforma.

In questa guida hai imparato cos'è UCP, perché è importante, come funziona la sua architettura e come eseguire un esempio locale completo dall'inizio alla fine. Configurando il server di esempio, scoprendone le funzionalità, creando una sessione di checkout e applicando uno sconto, hai visto come UCP trasformi il commercio in un flusso di lavoro strutturato e adatto agli agenti.

La più grande opportunità per UCP è chiara: può ridurre la frammentazione e rendere il commercio più interoperabile in un mondo in cui gli acquisti avvengono sempre più tramite assistenti AI e interfacce conversazionali. 

La vera sfida, però, sarà l'adozione. Le aziende potrebbero comunque scegliere API personalizzate, integrazioni basate su REST esistenti, strumenti basati su MCP o altri workflow per agenti che già usano oggi. Per avere successo, UCP avrà bisogno di un forte supporto dell'ecosistema da parte di merchant, piattaforme, sviluppatori e provider di pagamenti.