Universal-Commerce-Protocol-Tutorial: Erstelle deinen ersten UCP-Server

In diesem Guide erfährst du, was das Universal Commerce Protocol (UCP) ist, für wen es entwickelt wurde, warum ein neuer Commerce-Standard nötig ist und wie seine Architektur funktioniert. 

Außerdem setzt du Schritt für Schritt einen eigenen UCP-Beispielserver auf, prüfst sein Discovery-Profil, erstellst eine Checkout-Session und führst einen kompletten Beispielablauf lokal aus. 

So bekommst du sowohl ein klares Verständnis des Protokolls als auch einen praktischen Einstiegspunkt, um UCP in einer realen Implementierung auszuprobieren.

Einführung in das Universal Commerce Protocol

Das Universal Commerce Protocol ist ein offener Standard, der KI-Agenten, Apps, Unternehmen und Zahlungsanbieter in einem gemeinsamen Shopping-Flow zusammenbringt. Statt für jeden neuen Partner eine individuelle Integration zu bauen, stellt UCP eine gemeinsame Sprache für die Kommunikation bereit.

UCP ist für modernes Agent-led Shopping konzipiert, bei dem Menschen Produkte über KI-Assistenten und dialogbasierte Interfaces entdecken und kaufen. Es unterstützt die gesamte Journey – vom Entdecken des Angebots über den Checkout bis zur strukturierten Abwicklung des Kaufs.

Quelle: Google Developers Blog

Einfach gesagt fungiert UCP als gemeinsame Handelssprache. Ein Unternehmen kann veröffentlichen, was es unterstützt, und ein Agent kann diese Informationen auslesen und damit interagieren – ohne eine einmalige API-Integration zu benötigen. Shopify beschreibt es als Infrastruktur, die agentischen Commerce in großem Maßstab ermöglicht.

UCP ist zudem Open Source und herstellerneutral. Es ist so ausgelegt, dass es mit bestehenden Commerce-Systemen zusammenarbeitet, und es ist kompatibel mit dem Agent Payments Protocol (AP2) für sichere, agentengeführte Zahlungen. Es kann außerdem über verschiedene Transports funktionieren, darunter REST-APIs, Agent-zu-Agent-Kommunikation und MCP. 

Für wen ist das Universal Commerce Protocol gemacht?

Das UCP richtet sich an die Hauptakteure des modernen digitalen Handels. Ziel ist, allen eine gemeinsame Kommunikationsebene zu geben, damit sie zusammenarbeiten können, ohne für jede Verbindung eine individuelle Integration zu bauen.

Im Kern ist es gedacht für:

1. KI-Agenten und Consumer-Plattformen

Das sind Apps, Assistenten und Entdeckungsflächen, die Nutzerinnen und Nutzern helfen, Produkte zu finden und Käufe zu tätigen. UCP hilft ihnen zu verstehen, was ein Unternehmen unterstützt, und damit strukturiert zu interagieren. Google beschreibt dies als Verbindung von Consumer-Surfaces mit Business-Backends für nahtloses Einkaufen.

2. Unternehmen und Händler

UCP ermöglicht es Unternehmen, ihre Produkte, Checkout-Flows und unterstützten Features in einem Standardformat bereitzustellen. So können sie einfacher mit verschiedenen KI-Plattformen und Agenten zusammenarbeiten, ohne für jede einzelne eine neue Integration zu bauen.

3. Zahlungsanbieter

Auch Zahlungsanbieter sind Teil des UCP-Ökosystems. Das Protokoll unterstützt unterschiedliche Payment-Handler und Zahlungsnachweise flexibel, damit Zahlungen systemübergreifend sicher abgewickelt werden können.

4. Entwicklerinnen, Entwickler und Protokoll-Builder

UCP ist Open Source – es richtet sich daher auch an Entwickler, die den Standard implementieren, erweitern oder dazu beitragen möchten. Das UCP-Projekt lädt Unternehmen, Entwickler und Zahlungsanbieter ausdrücklich ein, die Zukunft des Protokolls mitzugestalten.

Kurz: UCP ist für alle, die am KI-gestützten Commerce beteiligt sind – die Plattform, die beim Einkauf unterstützt, das Unternehmen, das verkauft, das Zahlungssystem, das Transaktionen verarbeitet, und die Entwickler, die die Verbindungen zwischen ihnen bauen.

Warum ein neuer Commerce-Standard nötig ist

Ein neuer Standard ist nötig, weil die meisten heutigen Commerce-Systeme für klassische Websites und Mobile-Apps entwickelt wurden – nicht für KI-Assistenten und dialogbasiertes Shopping. 

Dieses ältere Modell basiert häufig auf individuellen APIs und einmaligen Integrationen – langsam und schwer skalierbar über viele Plattformen hinweg. UCP löst das, indem es Unternehmen, Agenten und Plattformen eine gemeinsame Kommunikationsbasis gibt.

Da immer mehr Menschen mit KI-Tools einkaufen, muss Commerce Live-Aktionen wie Produktsuche, Checkout, Rabatte und Bestellupdates innerhalb derselben Konversation unterstützen. 

UCP ist für diesen neueren Einkaufsstil gemacht, bei dem das Erlebnis interaktiver ist und über unterschiedliche digitale Oberflächen hinweg stattfindet.

Außerdem ist es nötig, weil das heutige Commerce-Ökosystem fragmentiert ist. Unterschiedliche Unternehmen, Zahlungsanbieter und Plattformen nutzen oft verschiedene Systeme. UCP führt sie über einen gemeinsamen Standard zusammen, sodass sie ohne ständiges Neubauen identischer Integrationen zusammenarbeiten können.

Kurz: UCP wird gebraucht, weil alte Commerce-Tools nicht für KI-geführtes Shopping gebaut wurden. Es bietet der Branche ein modernes, flexibles Fundament für die Art und Weise, wie Menschen künftig Produkte entdecken und kaufen.

Die Architektur des Universal Commerce Protocol verstehen

Das Universal Commerce Protocol (UCP) ist ein modulares System für agentischen Commerce. Es bietet Unternehmen, KI-Agenten und Zahlungsanbietern eine gemeinsame Grundlage, um die Shopping-Journey von der Entdeckung bis zum Checkout und darüber hinaus zu steuern. 

Anstatt für jede Plattform separate Spezialintegrationen zu bauen, kann ein Unternehmen mit UCP veröffentlichen, was es unterstützt – ein Agent liest diese Informationen und folgt einem standardisierten Ablauf. 

UCP ist modular und erweiterbar, unterstützt Transports wie REST, MCP und A2A und arbeitet mit Payment-Handlern, sodass Unternehmen bestehende Zahlungs-Setups einfacher weiterverwenden können.

1. Das Unternehmen veröffentlicht ein Discovery-Profil

Ein UCP-fähiges Unternehmen stellt ein Profil unter /.well-known/ucp bereit. Dieses Profil informiert Plattformen und Agenten vor Beginn einer Transaktion darüber, was unterstützt wird – inklusive verfügbarer Fähigkeiten und Endpunkte.

2. Der Agent liest die unterstützten Capabilities

Nach dem Discovery prüft der Agent, welche Services und Capabilities das Unternehmen anbietet. Der erste UCP-Release fokussiert sich auf Kernfunktionen wie Checkout, Identity Linking und Order Management – die zentralen Bausteine des Protokolls.

3. Erweiterungen fügen zusätzliche Features hinzu

UCP hält den Kernablauf schlank, aber Unternehmen können bei Bedarf optionale Extensions ergänzen. Diese bauen auf den Kernfähigkeiten auf und ermöglichen reichere Funktionen, ohne das gesamte Protokoll zu verändern.

4. Der Flow läuft über einen unterstützten Transport

Sobald der Agent weiß, was unterstützt wird, kann er über einen unterstützten Transport wie REST, MCP oder A2A mit dem Unternehmen interagieren. So lässt sich dieselbe Commerce-Logik leichter über APIs, KI-Tools und Agent-zu-Agent-Systeme nutzen.

5. Zahlungen werden über Payment-Handler abgewickelt

UCP trennt den Commerce-Flow von der Zahlungsebene. Unternehmen können unterstützte Payment-Handler deklarieren, und das Protokoll ist so gestaltet, dass Händler ihre bestehenden Zahlungsintegrationen weiterverwenden können, statt alles neu aufzubauen.

6. Sichere, agentengeführte Zahlungen können AP2 nutzen

UCP ist kompatibel mit dem Agent Payments Protocol (AP2), das eine zusätzliche Sicherheitsschicht für agentengeführte Zahlungen bietet. So lässt sich die Autorisierung sicherer gestalten, wenn ein KI-Agent im Namen eines Nutzers handelt.

End-to-End-Walkthrough zum Universal Commerce Protocol

Dieser Guide zeigt einen vollständigen Universal-Commerce-Protocol-Flow anhand der Python-Referenzimplementierung. Du setzt den Beispiel-Server für Händler auf, lädst einen Demo-Katalog eines Blumenladens, entdeckst die Unternehmensfähigkeiten, erstellst eine Checkout-Session, wendest einen Rabatt an und stoppst anschließend den Server.

Schritt 1: Business-Server einrichten

In diesem Schritt installierst du uv für das Python-Abhängigkeitsmanagement und klonst anschließend sowohl das UCP Python SDK als auch das Repository des Beispielservers. Das README des Beispielservers folgt demselben Setup-Muster und weist darauf hin, dass der relative Pfad zum SDK für die Beispiele wichtig ist.

Da unser Betriebssystem Linux ist, verwenden wir den folgenden Befehl zur Installation von uv. uv ist ein schneller, zuverlässiger Paket- und Umgebungsmanager für Python. Er erfüllt einen ähnlichen Zweck wie Tools wie Anaconda, ist aber deutlich schlanker und schneller.

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

Sobald die Installation abgeschlossen ist, lade deine Terminal-Session neu, damit der uv-Befehl in der aktuellen Shell verfügbar ist.

source ~/.bashrc

Erstelle als Nächstes einen neuen Ordner namens sdk. Dieser Ordner wird das Universal Commerce Protocol Python SDK enthalten, wenn wir es aus dem GitHub-Repository klonen. 

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

Wechsle nun ins Verzeichnis sdk/python, in das das SDK-Repository geklont wurde.

pushd sdk/python

Sobald du im SDK-Verzeichnis bist, installiere alle benötigten Python-Abhängigkeiten für das SDK mit uv sync.

uv sync

Nachdem die Abhängigkeiten installiert sind, kehrst du in dein vorheriges Arbeitsverzeichnis zurück.

popd

Klon nun das Samples-Repository, das den Python-Referenzserver für Händler enthält, den wir in diesem Walkthrough verwenden.

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

Wechsle als Nächstes in das Python-Server-Beispiel innerhalb des Samples-Repositories.

cd samples/rest/python/server

Installiere abschließend alle Python-Abhängigkeiten, die für den Beispielserver erforderlich sind.

uv sync

Jetzt ist der Beispiel-Business-Server in deiner Workspace bereit. Er implementiert bereits die von UCP definierten Kernfunktionen für Shopping.

Schritt 2: Beispiel-Produktdatenbank erstellen

In diesem Schritt erstellst du einen lokalen, auf SQLite basierenden Demo-Store für das Beispielunternehmen. In diesem Tutorial ist das Beispiel ein Blumenladen. Der folgende Befehl lädt den Beispiel-Produktkatalog und die Transaktionsdatenbank, die der Server nutzt.

Lege zuerst einen temporären Ordner an, in dem die Datenbanken gespeichert werden.

mkdir /tmp/ucp_test

Führe dann das Importskript aus, um die Produkt- und Transaktionsdatenbanken zu erstellen und zu befüllen.

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

Dieser Befehl bewirkt Folgendes:

• --products_db_path erstellt die Produktkatalog-Datenbank.
• --transactions_db_path erstellt die Transaktionsdatenbank für den Checkout-Status.
• --data_dir=../test_data/flower_shop verweist auf die im Repository enthaltenen Beispieldaten des Blumenladens.

Nach Abschluss dieses Schritts sind deine lokalen Beispieldaten bereit und der Server kann sie verwenden.

Schritt 3: Business-Server starten

In diesem Schritt startest du den UCP-Beispielserver des Unternehmens. Er nutzt die im vorherigen Schritt erstellten Produkt- und Transaktionsdatenbanken und stellt die UCP-Shopping-APIs auf Port 8182 bereit.

Führe den folgenden Befehl aus, um den Server im Hintergrund zu starten.

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

Dieser Befehl bewirkt Folgendes:

• uv run server.py startet den Python-Beispielserver.
• --products_db_path verbindet den Server mit der Produktdatenbank.
• --transactions_db_path verbindet den Server mit der Transaktionsdatenbank.
• --port=8182 legt Port 8182 fest.
• & führt den Prozess im Hintergrund aus, damit du das Terminal weiter nutzen kannst.
• SERVER_PID=$! speichert die Prozess-ID, um den Server später zu beenden.

Jetzt läuft der Business-Server und ist bereit, Anfragen von einem Agenten zu verarbeiten.

Schritt 4: Business-Capabilities entdecken

In diesem Schritt fragst du den UCP-Discovery-Endpunkt ab. Jedes UCP-fähige Unternehmen veröffentlicht ein Discovery-Dokument unter /.well-known/ucp, damit Agenten vorab verstehen, was unterstützt wird.

Speichere zunächst die Server-URL in einer Variablen, damit die nächsten Befehle übersichtlicher sind.

export SERVER_URL=http://localhost:8182

Rufe nun das UCP-Discovery-Dokument vom Business-Server ab.

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

Diese Antwort informiert den Agenten darüber,

• welche UCP-Version der Server unterstützt,
• welche Services verfügbar sind,
• welche Capabilities implementiert sind – etwa Checkout und Rabatte,
• und welche Payment-Handler oder -Schemata unterstützt werden.

Dieser Discovery-Schritt ist wichtig, weil er harte, individuelle Integrationen überflüssig macht. Der Agent kann den Server zuerst inspizieren und dann entscheiden, wie er mit ihm interagiert.

Schritt 5: Checkout-Session erstellen

In diesem Schritt erstellst du eine neue Checkout-Session mithilfe der UCP-Checkout-Fähigkeit. Hier übermittelt der Agent das ausgewählte Produkt, Käuferinformationen und die Zahlungsstruktur an den Business-Server.

Erzeuge vor dem Absenden die nötigen Request-Header. Diese unterstützen Request-Tracing, Idempotenz und Signaturprüfung.

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"

Das bewirkt Folgendes:

• REQUEST_ID erzeugt eine eindeutige Kennung für die Anfrage.
• IDEMPOTENCY_KEY stellt sicher, dass dieselbe Anfrage bei einem Retry nicht doppelt verarbeitet wird.
• REQUEST_SIGNATURE liefert den erforderlichen Signatur-Header. In einer lokalen Demo kann "dev" verwendet werden, wenn keine strikte Signaturprüfung erzwungen wird.

Sende nun die Checkout-Anfrage an den 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": [] }
  }'

Diese Anfrage umfasst:

• line_items zur Definition der gewünschten Produkte,
• item.id zur Identifikation des Produkts,
• item.title als lesbarer Name,
• quantity für die Anzahl der Einheiten,
• buyer für die Kundendaten,
• currency zur Definition der Checkout-Währung,
• und payment für die erforderliche Zahlungsstruktur.

Die Antwort liefert ein Checkout-Session-Objekt – mit neuer Checkout-ID, Line-Item-IDs, Summen, Käuferinformationen und dem aktuellen Checkout-Status.

Schritt 6: Rabatte mit UCP anwenden

In diesem Schritt aktualisierst du die bestehende Checkout-Session und wendest einen Rabattcode an. Rabatte sind in UCP als Erweiterung der Checkout-Fähigkeit implementiert, daher wird der Rabatt im Update-Request des Checkouts ergänzt.

Speichere zunächst die echte Checkout-ID und Line-Item-ID aus der vorherigen Antwort.

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

Erzeuge als Nächstes eine neue Request-ID und einen Idempotency-Key für dieses Update.

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"

Sende nun den aktualisierten Checkout-Request inklusive Rabattcode.

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\": []
    }
  }"

Dieser Request bewirkt Folgendes:

• aktualisiert den bestehenden Checkout per PUT,
• enthält die ursprüngliche Checkout-ID,
• führt das Line-Item erneut auf,
• fügt den Abschnitt discounts hinzu,
• und wendet den Code 10OFF an.

Die Antwort sollte das aktualisierte Checkout-Objekt zurückgeben – mit:

• neu berechneten Summen,
• dem Rabattbetrag,
• der finalen Gesamtsumme,
• und Details zum angewendeten Rabatt.

Der Rabattcode ist gültig; du solltest die Preisänderung in der Antwort sehen.

Schritt 7: Server herunterfahren

Im letzten Schritt beendest du den Beispielserver, den du zuvor gestartet hast. Weil du die Prozess-ID beim Start gespeichert hast, kannst du ihn bequem mit einem Befehl stoppen.

Führe folgenden Befehl aus, um den Server zu stoppen.

kill $SERVER_PID

Von Anfang bis Ende hast du erfolgreich einen vollständigen End-to-End-UCP-Flow auf deiner lokalen Maschine aufgebaut und getestet.

Du hast:

• die benötigten Python-Tools mit uv installiert,
• das UCP Python SDK und die Sample-Server-Repositories geklont,
• eine Beispiel-Produktdatenbank für den Blumenladen erstellt,
• den Business-Server gestartet,
• die UCP-Capabilities des Servers über den Discovery-Endpunkt ermittelt,
• als Agent eine Checkout-Session erstellt,
• diesen Checkout per Rabattcode aktualisiert,
• und den Server wieder beendet.

Kurz gesagt: Du hast ein UCP-fähiges Unternehmen aufgesetzt, dich wie ein Agent verbunden, einen Checkout erstellt und getestet, wie UCP Updates wie Rabatte verarbeitet. Damit hast du ein vollständiges Basisbeispiel, wie ein Unternehmen und ein Agent über das Universal Commerce Protocol interagieren können.

Fazit

Das Universal Commerce Protocol gibt der Branche ein gemeinsames Fundament für KI-geführten Commerce. Es schafft eine standardisierte Sprache für Unternehmen, KI-Agenten und Zahlungssysteme – so werden Discovery, Checkout, Updates und Zahlungen einfacher unterstützt, ohne für jede neue Plattform individuelle Integrationen zu bauen.

In diesem Guide hast du gelernt, was UCP ist, warum es relevant ist, wie die Architektur funktioniert und wie du ein komplettes lokales Beispiel von Anfang bis Ende ausführst. Durch das Aufsetzen des Beispielservers, das Entdecken seiner Capabilities, das Erstellen einer Checkout-Session und das Anwenden eines Rabatts hast du gesehen, wie UCP Commerce in einen strukturierten, agentenfreundlichen Workflow verwandelt.

Die größte Chance von UCP ist klar: Es kann Fragmentierung reduzieren und Commerce interoperabler machen – in einer Welt, in der Shopping zunehmend über KI-Assistenten und Konversationsoberflächen stattfindet. 

Die eigentliche Herausforderung wird jedoch die Verbreitung sein. Unternehmen könnten weiterhin auf individuelle APIs, bestehende REST-Integrationen, MCP-basierte Tools oder andere Agent-Workflows setzen, die sie heute schon nutzen. Für den Erfolg von UCP braucht es starke Unterstützung im Ökosystem – von Händlern, Plattformen, Entwicklern und Zahlungsanbietern.