1. Übersicht
In diesem Codelab führen Sie einen ADK-Agenten aus, der Kinokarten bei mehreren Kinobetreibern über zwei Open-Source-Commerce-Protokolle bucht:
- UCP (Universal Commerce Protocol): Ein Standard für Agenten, um Händler zu finden, Kataloge zu durchsuchen und Kaufabwicklungen zu verwalten.
- AP2 (Agent Payments Protocol): Ein Protokoll für die sichere, überprüfbare Zahlungsautorisierung mit kryptografisch signierten Mandaten.
Die Demo-App CineAgent stellt eine Verbindung zu zwei fiktiven Kinohändlern mit unterschiedlichen Funktionen (Sitzplatzauswahl, spezielle Formate und Zahlungsmethoden) her und orchestriert den gesamten Buchungsablauf von der Suche bis zur Zahlung.
Lerninhalte
- So funktioniert die Händlersuche über
/.well-known/ucp-Profile - Wie ein ADK-Agent UCP verwendet, um Kataloge zu durchsuchen und Check-outs zu erstellen
- So sichern AP2-Mandate (CheckoutMandate, PaymentMandate) Transaktionen
- So schützen die Ende-zu-Ende-Protokolle UCP und AP2 den agentischen E-Commerce
Voraussetzungen
- Ein Google Cloud-Projekt mit aktivierter Abrechnungsfunktion
- Ein Webbrowser wie Chrome
- Python 3.11 oder höher und uv, wenn Sie den Code auf Ihrem eigenen Computer anstelle von Cloud Shell ausführen
Dieses Codelab richtet sich an Entwickler mit mittleren Kenntnissen, die mit Python und Google Cloud vertraut sind. Dieses Codelab dauert etwa 30 Minuten.
Die in diesem Codelab erstellten Ressourcen sollten weniger als 5 $ kosten.
2. UCP- und AP2-Protokolle
Bevor wir mit der Entwicklung des Agents beginnen, sehen wir uns die beiden Protokolle an, die diesen sicheren Agentenhandel ermöglichen.
In diesem Codelab wird die UCP-Version 2026-08-25 mit dem UCP Python SDK und AP2 v0.2 mit dem AP2 Python SDK verwendet.
Universal Commerce Protocol (UCP)
UCP standardisiert die Interaktion von KI-Agenten mit Händlern. Es löst das Problem, dass Agenten für jeden einzelnen Shop benutzerdefinierte APIs lernen müssen, indem ein standardisiertes Ressourcenmodell eingeführt wird.
Funktionsweise:
- Erkennung: Jeder UCP-konforme Händler stellt ein Profil an einem Standardspeicherort bereit:
/.well-known/ucp. Beispiel: UCP-Endpunkt von Everlane.Wenn ein Agent dieses Profil liest, sucht er nach:- Funktionen: Die eigenständigen Kernfunktionen, die ein Unternehmen unterstützt, z. B. die Katalogsuche oder die Kaufabwicklung.
- Dienste: Die Kommunikationsschichten auf niedrigerer Ebene, die zum Austausch von Daten verwendet werden. Beispiele: REST API, MCP (Model Context Protocol), A2A (Agent2Agent Protocol).
- Erweiterungen: Wenn ein Händler ein spezielles Verhalten benötigt, kann er in diesem Profil benutzerdefinierte Erweiterungen definieren.
- Schlüssel: Die öffentlichen Signaturschlüssel des Händlers, die von Kundenservicemitarbeitern verwendet werden, um die Signaturen des Händlers zu prüfen.
- Vorgänge: Nachdem der Agent den Dienstendpunkt ermittelt hat, verwendet er ihn, um Vorgänge auszuführen. In diesem Codelab verwenden wir das Model Context Protocol (MCP) als Diensttransport. Der Agent führt JSON-RPC 2.0-Aufrufe an diesen Endpunkt aus, um die erkannten Funktionen aufzurufen: Produkte suchen, Check-outs erstellen und Käufe abschließen.

Agent Payments Protocol (AP2)
AP2 standardisiert die Autorisierung von Zahlungen durch Kundenservicemitarbeiter im Namen von Nutzern. So wird das Sicherheitsproblem gelöst, dass Kundenservicemitarbeiter vertrauliche Zahlungsdaten verarbeiten.
Funktionsweise:
- Händlersignatur: Wenn ein Agent einen Direktkauf über das UCP-Protokoll erstellt, signiert der Händler den Direktkauf (Positionen und Summen) und gibt die Signatur in
ap2.merchant_authorizationzurück. Sie fungiert als Garantie für den Preis. Wenn der Händler den Preis nach der Unterzeichnung ändert, stimmt die Unterschrift nicht mehr. - Checkout-Mandat und Zahlungsauftrag: Nachdem der Nutzer (oder der Kundenservicemitarbeiter in seinem Namen) den Inhalt des Checkouts bestätigt hat, unterzeichnet er zwei Mandate. Das
CheckoutMandateenthält den vom Händler signierten Direktkauf und informiert den Händler darüber, dass der Nutzer ihn genehmigt hat. DiePaymentMandateautorisiert den Zahlungsbetrag für diesen Checkout. Beide verweisen auf einen Hash des signierten Check-outs und enthalten die kryptografische Signatur des Nutzers. - Bestätigung der Unterschrift: Der Händler erhält beide Mandate. Es wird die Signatur des Nutzers für
CheckoutMandateüberprüft und geprüft, ob die darin enthaltene Kaufabwicklung die Signatur des Händlers enthält. DiePaymentMandatewird an die Zahlungsseite (einen Anmeldedatenanbieter oder Zahlungsabwickler) gesendet, die sie überprüft, bevor sie Geld überweist. Wenn alles gültig ist, wird die Transaktion fortgesetzt.
Dieses „Doppelschloss“-System sorgt dafür, dass Händler nicht zu viel berechnen und Kundenservicemitarbeiter nicht ohne Autorisierung Geld ausgeben können. Mandate sind SD-JWT-Anmeldedaten (Selective Disclosure JWT), die die Privatsphäre der Nutzer schützen, indem nur die Felder offengelegt werden, die die jeweilige Partei benötigt. In AP2 v0.2 ersetzt CheckoutMandate das CartMandate aus AP2 v0.1.

3. Umgebung einrichten
Google Cloud-Projekt einrichten
Google Cloud-Projekt erstellen
- Wählen Sie in der Google Cloud Console auf der Seite zur Projektauswahl ein Google Cloud-Projekt aus oder erstellen Sie eines.
- Die Abrechnung für das Cloud-Projekt muss aktiviert sein. So prüfen Sie, ob die Abrechnung für ein Projekt aktiviert ist.
Cloud Shell starten
Cloud Shell ist eine Befehlszeilenumgebung, die in Google Cloud ausgeführt wird und mit den erforderlichen Tools vorinstalliert ist.
- Klicken Sie oben in der Google Cloud Console auf Cloud Shell aktivieren.
- Sobald die Verbindung mit der Cloud Shell hergestellt ist, prüfen Sie Ihre Authentifizierung:
gcloud auth list - Prüfen Sie, ob Ihr Projekt konfiguriert ist:
gcloud config get project - Wenn Ihr Projekt nicht wie erwartet festgelegt ist, legen Sie es fest:
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
APIs aktivieren
Führen Sie den folgenden Befehl aus, um die erforderlichen APIs zu aktivieren:
gcloud services enable aiplatform.googleapis.com
Verzeichnisstruktur einrichten
Kopieren Sie die folgenden Befehle und fügen Sie sie ein, um einen Ordner für dieses Codelab zu erstellen. Darin befindet sich ein Ordner agent_payments für den Agent-Code:
mkdir -p ~/adk-agent-commerce/agent_payments
cd ~/adk-agent-commerce
Auf Gemini-Modelle zugreifen
Kopieren Sie den folgenden Befehl und fügen Sie ihn ein, um agent_payments/.env mit Ihrem Projekt und Standort zu erstellen und ADK über Ihr Google Cloud-Projekt Gemini aufrufen zu lassen. Der Cine-Agent verwendet Gemini, um zu entscheiden, welche Tools aufgerufen werden sollen. Das ADK lädt diese Datei automatisch, sodass die Einstellungen auch in neuen Terminals funktionieren.
cat > ~/adk-agent-commerce/agent_payments/.env <<EOF
GOOGLE_CLOUD_PROJECT=$(gcloud config get project)
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_ENTERPRISE=True
EOF
Abhängigkeiten installieren
uv ist in Google Cloud Shell vorinstalliert, um die Umgebung und Abhängigkeiten zu verwalten.
- Erstellen Sie im Stammverzeichnis Ihres
adk-agent-commerce-Ordners eine Datei mit dem Namenpyproject.tomlund fügen Sie ihr den folgenden Inhalt hinzu. In dieser Datei werden die Projektmetadaten und ‑abhängigkeiten definiert.
[project]
name = "agent-payments-demo"
version = "0.1.0"
description = "CineAgent booking agent using UCP and AP2"
requires-python = ">=3.11"
dependencies = [
"google-adk",
"fastapi",
"uvicorn",
"httpx",
"ucp-sdk",
"ap2 @ git+https://github.com/google-agentic-commerce/AP2.git@main",
]
Das AP2 SDK wird aus dem GitHub-Repository installiert, da es noch nicht auf PyPI veröffentlicht wurde. Das ap2-Paket auf PyPI ist ein unabhängiges Projekt.
- Führen Sie den folgenden Befehl aus, um die virtuelle Umgebung zu erstellen und alle Abhängigkeiten zu installieren:
uv sync
uv erstellt eine isolierte Python-Umgebung für dieses Codelab, sodass Sie nichts aktivieren müssen. Stellen Sie Python-Befehlen das Präfix uv run voran.
4. Agent definieren
Bevor wir Tool-Logik schreiben, definieren wir den Agenten selbst in einer Datei namens agent.py. Dieser KI-Agent fungiert als Orchestrator für den Ablauf der Filmbuchung.
agent_payments/agent.py erstellen:
"""CineAgent — movie ticket booking agent using UCP and AP2."""
from google.adk.agents import Agent
from google.adk.models import Gemini
from google.genai import types
from google.adk.tools import FunctionTool
from agent_payments.tools import (
discover_theaters,
search_movies,
get_movie_detail,
create_checkout,
complete_purchase,
)
root_agent = Agent(
model=Gemini(
model="gemini-3.8-flash",
retry_options=types.HttpRetryOptions(attempts=5),
),
name="cineagent",
description="Movie ticket booking agent using UCP and AP2.",
instruction="""You are CineAgent, a movie ticket booking assistant.
You help users find and book movie tickets across multiple theaters
using UCP (Universal Commerce Protocol) and AP2 (Agent Payments).
**Your tools:**
- discover_theaters: Find theaters and what they support
- search_movies: Search movies across all theaters
- get_movie_detail: Get showtimes at a specific theater
- create_checkout: Start a checkout session
- complete_purchase: Finalize with AP2 mandate signing
**Rules:**
- Always call discover_theaters first if you haven't yet
- Keep responses concise — summarize and suggest next steps
- Prices from tools are in cents (1500 = $15.00)
- Never invent data — only state what tools return
""",
tools=[
discover_theaters,
search_movies,
get_movie_detail,
create_checkout,
FunctionTool(complete_purchase, require_confirmation=True),
],
)
Erläuterung zum Code:
Sehen wir uns an, was in dieser Agentendefinition passiert:
model=Gemini(...): Wir verwenden Gemini 3.8 Flash für Schlussfolgerungen und die Verwendung von Tools.instruction: Diese Eingabeaufforderung steuert das Verhalten des Agenten. Darin wird dem Agenten ausdrücklich mitgeteilt, dass er UCP und AP2 verwenden soll. Außerdem werden die verfügbaren Tools aufgeführt und wichtige Regeln wie „Never invent data“ (Erfinde niemals Daten) und „Prices are in cents“ (Preise sind in Cent angegeben) festgelegt.tools: Dies ist eine Liste von Python-Funktionen (die wir als Nächstes erstellen), die der Agent basierend auf den Anfragen des Nutzers aufrufen kann.require_confirmation: Sie können jedes Tool mitFunctionTool(my_function,require_confirmation=True)umschließen. Wenn der Trigger ausgelöst wird, pausiert der Agent und wartet auf eine einfache Bestätigung mit „Ja“ oder „Nein“, bevor er das Tool ausführt. Bevor dascomplete_purchase-Tool ausgeführt wird, pausiert der KI-Agent, um eine Bestätigung durch einen Menschen einzuholen.
Die Tool-Liste
In der Agent-Definition wird deklariert, was wir erstellen müssen. Jedes Tool entspricht einem bestimmten Vorgang im UCP- oder AP2-Protokoll:
Tool | Funktion | Protokollaktion |
| Händler und ihre Funktionen finden | Abfragen |
| Kataloge verschiedener Händler durchsuchen | JSON-RPC-zu-MCP-Endpunkt |
| Vorstellungszeiten bei einem bestimmten Händler abrufen | JSON-RPC-zu-MCP-Endpunkt |
| Checkout-Sitzung starten | JSON-RPC-zu-MCP-Endpunkt |
| Zahlung autorisieren und Bestellung abschließen | Signs AP2 Mandates & sends to MCP |
Das Gemini-Modell entscheidet anhand der Unterhaltung, wann die einzelnen Tools aufgerufen werden. Als Nächstes müssen wir implementieren, was die einzelnen Tools in tools.py tun.
5. Agententools erstellen: Discovery und Browsing
Implementieren wir nun die Tools, mit denen der Agent Filme suchen und finden kann. Jedes Tool umschließt einen UCP-Vorgang.
Erstellen Sie eine neue Datei mit dem Namen agent_payments/tools.py und kopieren Sie den folgenden Code hinein:
"""Agent tools — each one wraps a UCP or AP2 operation."""
import json
from .ucp_client import UCPClient
from .ap2_handler import AP2Handler
# Initialize clients directly
_merchant_urls = ["http://localhost:8081", "http://localhost:8082"]
_ap2 = AP2Handler()
_ucp = UCPClient(platform_keys=[_ap2.public_key])
Einrichtung
Damit sich dieses Codelab auf die Erstellung des Agenten konzentriert, verwenden wir zwei Hilfsklassen, UCPClient und AP2Handler, die wir uns in einem späteren Schritt ansehen.
- Was sind sie?: Das sind kleine Hilfsklassen, die wir für dieses Codelab geschrieben haben, um mit den Mock-Händlern zu kommunizieren. Die offiziellen SDKs enthalten die Protokollteile: Das UCP SDK hat Datenmodelle für jedes UCP-Schema und das AP2 SDK erstellt und prüft signierte Mandate. Keines der SDKs enthält einen Client für Anrufe bei Händlern. Diese Helfer übernehmen diesen Teil.
- Behandeln Sie sie vorerst als Hilfsobjekte:
_ucp.discover(url): Ruft das Profil eines Händlers ab und validiert es._ucp.mcp_call(url, method, params): Sendet eine JSON-RPC 2.0-Anfrage an den MCP-Endpunkt des Händlers.
Theater entdecken
Dieses Tool ist der erste Schritt im UCP-Ablauf. Es wird ermittelt, welche Händler es gibt und was sie unterstützen.
Zu tools.py hinzufügen:
async def discover_theaters() -> str:
"""Discover available theater merchants and their capabilities via UCP."""
theaters = []
for url in _merchant_urls:
info = await _ucp.discover(url)
theaters.append(
{
"url": url,
"name": info["name"],
"capabilities": info["capabilities"],
"payment_handlers": info["payment_handlers"],
}
)
return json.dumps(theaters, indent=2)
Was passiert?
- Es wird eine vom Server bereitgestellte Liste von Händler-URLs durchlaufen. In diesem Codelab richten wir im späteren Abschnitt zwei Test-Händler ein.
- Für jede URL wird
_ucp.discover(url)aufgerufen, wodurch der Endpunkt/.well-known/ucperreicht wird. - Darin werden Name, Funktionen und Zahlungshandler in einer Zusammenfassungsliste erfasst.
- Die Liste wird als JSON-String zurückgegeben, damit der Agent sie lesen kann.
Filme suchen
Mit diesem Tool wird bei allen erkannten Händlern gesucht und die Ergebnisse werden zusammengeführt. Das ist wichtig, da derselbe Film möglicherweise in mehreren Kinos mit unterschiedlichen Formaten (IMAX, Dolby) und unterschiedlichen Preisen läuft.
Zu tools.py hinzufügen:
async def search_movies(query: str = "") -> str:
"""Search for movies across all theaters. Use '' to browse all."""
all_movies = {}
for url, merchant in _ucp.merchants.items():
result = await _ucp.mcp_call(
url, "search_catalog", {"catalog": {"query": query}}
)
for product in result.get("products", []):
mid = product["id"]
if mid not in all_movies:
all_movies[mid] = {
"id": mid,
"title": product["title"],
"categories": [
c["value"] for c in product.get("categories", [])
],
"theaters": {},
}
showtimes = []
for v in product.get("variants", []):
opts = {o["name"]: o["label"] for o in v.get("options", [])}
showtimes.append(
{
"id": v["id"],
"format": opts.get("format", "Standard"),
"time": opts.get("time", ""),
"price": v.get("price", {}),
"seats": v.get("metadata", {}).get(
"seats_available", 0
),
}
)
all_movies[mid]["theaters"][url] = {
"name": merchant["name"],
"showtimes": showtimes,
}
return json.dumps(list(all_movies.values()), indent=2)
Was passiert?
- Es wird eine Schleife durch alle gefundenen Kinos durchlaufen.
- Es wird eine JSON-RPC-Anfrage für den Suchkatalog (
_ucp.mcp_call(url, "search_catalog", {"catalog": {"query": query}})) an den MCP-Endpunkt des Händlers gesendet. - Anschließend werden die Ergebnisse analysiert, um Filme und ihre „Varianten“ (die bestimmte Vorstellungszeiten und Formate darstellen) zu finden. Gruppiert die Filme nach ID, damit der Nutzer keine doppelten Filmeinträge sieht.
Filmdetails abrufen
Mit diesem Tool werden die vollständigen Katalogdetails für einen bestimmten Film in einem bestimmten Kino abgerufen.
Zu tools.py hinzufügen:
async def get_movie_detail(movie_id: str, merchant_url: str) -> str:
"""Get detailed showtimes for a movie at a specific theater."""
result = await _ucp.mcp_call(
merchant_url, "lookup_catalog", {"catalog": {"ids": [movie_id]}}
)
return json.dumps(result, indent=2)
Was passiert?
- Dabei wird die Methode
lookup_catalogam MCP-Endpunkt des Händlers aufgerufen und die spezifischemovie_idincatalog.idsübergeben. So erhalten Sie detaillierte Informationen wie Spielzeiten und verfügbare Plätze für das jeweilige Kino.
6. Agententools erstellen: Checkout und Zahlung
Diese Tools übernehmen den Checkout- und Kaufvorgang. Hier kommt das AP2-Protokoll ins Spiel, um sichere Transaktionen zu gewährleisten.
Direktkauf erstellen
Mit diesem Tool wird eine Abrechnungssitzung in einem bestimmten Kino für eine bestimmte Vorstellung gestartet.
Zu tools.py hinzufügen:
async def create_checkout(
merchant_url: str, showtime_id: str, quantity: int = 1
) -> str:
"""Create a checkout session for tickets at a theater."""
result = await _ucp.mcp_call(merchant_url, "create_checkout", {
"checkout": {
"line_items": [
{"item": {"id": showtime_id}, "quantity": quantity}
],
"context": {"address_country": "US", "currency": "USD"},
}
})
return json.dumps(result, indent=2)
Was passiert?
- Dabei wird die Methode
create_checkoutam MCP-Endpunkt des Händlers aufgerufen. - Sie übergibt die vom Nutzer angeforderten
showtime_idundquantity. - Der Händler gibt einen mit seinem Schlüssel signierten Checkout zurück.
Hinweis: Wenn Sie die Antwortdaten untersuchen, enthält das Feld ap2.merchant_authorization die kryptografische Signatur des Händlers für den Bezahlvorgang, mit der der angegebene Preis gesperrt wird. Sie können sie später nicht mehr ändern.
Einkauf abschließen
In diesem Tool passieren drei Dinge:
- Wir erhalten die Kasse und überprüfen die Signatur des Händlers.
- Erstellen und signieren Sie das CheckoutMandate und das PaymentMandate mit dem AP2 SDK.
- Senden Sie beide Mandate an den Händler, um den Kauf abzuschließen.
Zu tools.py hinzufügen:
async def complete_purchase(checkout_id: str, merchant_url: str) -> str:
"""Complete purchase with AP2 payment authorization."""
merchant = _ucp.merchants[merchant_url]
# 1. Get the checkout and verify the merchant's signature on it
checkout = await _ucp.mcp_call(
merchant_url, "get_checkout", {"id": checkout_id}
)
checkout_jwt = _ap2.verify_merchant_authorization(checkout, merchant["keys"])
if not checkout_jwt:
return json.dumps({"error": "Merchant signature is missing or invalid"})
# 2. Create and sign the CheckoutMandate and PaymentMandate
# In production, this step asks the user to approve on a trusted device
# (biometric or device auth). In this demo, the agent signs with a local key.
checkout_mandate, payment_mandate = _ap2.create_mandates(
checkout, checkout_jwt, merchant["name"]
)
# 3. Send both mandates to the merchant to complete the purchase
result = await _ucp.mcp_call(merchant_url, "complete_checkout", {
"id": checkout_id,
"checkout": {
"payment": {
"instruments": [{
"id": "instr_1",
"handler_id": merchant["payment_handlers"][0],
"type": "card",
"selected": True,
"credential": {
"type": "ap2_payment_mandate",
"token": payment_mandate,
},
}],
},
"ap2": {"checkout_mandate": checkout_mandate},
},
})
return json.dumps(result, indent=2)
Warum zwei Mandate? Das CheckoutMandate beweist dem Händler, dass der Nutzer genau diesen Bezahlvorgang zum vom Händler unterzeichneten Preis genehmigt hat. Das PaymentMandate dient der Zahlungsseite als Nachweis dafür, dass der Nutzer diese Belastung autorisiert hat. Der Ablauf ist wie folgt:
Merchant signs checkout -> User signs mandates -> Merchant and payment side verify -> Order completes.
Checkpoint: Vollständige tools.py
Ihre vollständige tools.py sollte jetzt fünf Toolfunktionen und die Initialisierung auf Modulebene für UCP- und AP2-Clients haben. Prüfen Sie, ob es so aussieht:
"""Agent tools — each one wraps a UCP or AP2 operation."""
import json
from .ucp_client import UCPClient
from .ap2_handler import AP2Handler
# Initialize clients directly
_merchant_urls = ["http://localhost:8081", "http://localhost:8082"]
_ap2 = AP2Handler()
_ucp = UCPClient(platform_keys=[_ap2.public_key])
async def discover_theaters() -> str:
"""Discover available theater merchants and their capabilities via UCP."""
theaters = []
for url in _merchant_urls:
info = await _ucp.discover(url)
theaters.append(
{
"url": url,
"name": info["name"],
"capabilities": info["capabilities"],
"payment_handlers": info["payment_handlers"],
}
)
return json.dumps(theaters, indent=2)
async def search_movies(query: str = "") -> str:
"""Search for movies across all theaters. Use '' to browse all."""
all_movies = {}
for url, merchant in _ucp.merchants.items():
result = await _ucp.mcp_call(
url, "search_catalog", {"catalog": {"query": query}}
)
for product in result.get("products", []):
mid = product["id"]
if mid not in all_movies:
all_movies[mid] = {
"id": mid,
"title": product["title"],
"categories": [
c["value"] for c in product.get("categories", [])
],
"theaters": {},
}
showtimes = []
for v in product.get("variants", []):
opts = {o["name"]: o["label"] for o in v.get("options", [])}
showtimes.append(
{
"id": v["id"],
"format": opts.get("format", "Standard"),
"time": opts.get("time", ""),
"price": v.get("price", {}),
"seats": v.get("metadata", {}).get(
"seats_available", 0
),
}
)
all_movies[mid]["theaters"][url] = {
"name": merchant["name"],
"showtimes": showtimes,
}
return json.dumps(list(all_movies.values()), indent=2)
async def get_movie_detail(movie_id: str, merchant_url: str) -> str:
"""Get detailed showtimes for a movie at a specific theater."""
result = await _ucp.mcp_call(
merchant_url, "lookup_catalog", {"catalog": {"ids": [movie_id]}}
)
return json.dumps(result, indent=2)
async def create_checkout(
merchant_url: str, showtime_id: str, quantity: int = 1
) -> str:
"""Create a checkout session for tickets at a theater."""
result = await _ucp.mcp_call(merchant_url, "create_checkout", {
"checkout": {
"line_items": [
{"item": {"id": showtime_id}, "quantity": quantity}
],
"context": {"address_country": "US", "currency": "USD"},
}
})
return json.dumps(result, indent=2)
async def complete_purchase(checkout_id: str, merchant_url: str) -> str:
"""Complete purchase with AP2 payment authorization."""
merchant = _ucp.merchants[merchant_url]
# 1. Get the checkout and verify the merchant's signature on it
checkout = await _ucp.mcp_call(
merchant_url, "get_checkout", {"id": checkout_id}
)
checkout_jwt = _ap2.verify_merchant_authorization(checkout, merchant["keys"])
if not checkout_jwt:
return json.dumps({"error": "Merchant signature is missing or invalid"})
# 2. Create and sign the CheckoutMandate and PaymentMandate
# In production, this step asks the user to approve on a trusted device
# (biometric or device auth). In this demo, the agent signs with a local key.
checkout_mandate, payment_mandate = _ap2.create_mandates(
checkout, checkout_jwt, merchant["name"]
)
# 3. Send both mandates to the merchant to complete the purchase
result = await _ucp.mcp_call(merchant_url, "complete_checkout", {
"id": checkout_id,
"checkout": {
"payment": {
"instruments": [{
"id": "instr_1",
"handler_id": merchant["payment_handlers"][0],
"type": "card",
"selected": True,
"credential": {
"type": "ap2_payment_mandate",
"token": payment_mandate,
},
}],
},
"ap2": {"checkout_mandate": checkout_mandate},
},
})
return json.dumps(result, indent=2)
7. Runnable erstellen
Bei echten UCP-Händlern würden Sie den Agenten auf ihre URLs verweisen und das war es dann auch schon. Für dieses Codelab benötigen wir zwei Dinge, um lokal zu testen:
- Simulierte Händler: Lokale Server, die UCP-Endpunkte simulieren, damit Sie etwas zum Testen haben
- Protokoll-Helfer: schlanke Wrapper, die Händler über HTTP aufrufen und die UCP- und AP2-SDKs für die Protokolldaten und Signaturen verwenden
Hinweis: Sie müssen diesen Code nicht sorgfältig lesen. Diese Dateien simulieren echte Händler und die Wallet eines Nutzers. Kopieren Sie sie unverändert.
Protokoll-Helfer
Das UCP SDK bietet Datenmodelle und das AP2 SDK signiert und überprüft Mandate. Keines der beiden SDKs enthält jedoch einen Client für die Kommunikation mit Händlern. Diese beiden Dateien schließen diese Lücke. Sie heißen ucp_client.py und ap2_handler.py, damit sie das Paket ap2 nicht überschreiben.
agent_payments/ucp_client.py erstellen:
"""UCP client: discovers merchants and calls their MCP tools."""
import uuid
import httpx
from ucp_sdk.models.schemas.profile import BusinessSchema
# The platform (this agent) identifies itself with a UCP profile URL
PLATFORM_PROFILE = "https://cineagent.example/.well-known/ucp"
class UCPClient:
def __init__(self, platform_keys: list[dict]):
self.client = httpx.AsyncClient(timeout=30)
self.platform_keys = platform_keys
self.merchants = {} # url -> merchant info dict
async def discover(self, merchant_url: str) -> dict:
"""Fetch and validate a merchant's UCP profile from /.well-known/ucp."""
resp = await self.client.get(f"{merchant_url}/.well-known/ucp")
resp.raise_for_status()
profile = BusinessSchema.model_validate(resp.json())
ucp = profile.ucp
info = {
"name": merchant_url.split("//")[-1],
"mcp_endpoint": str(ucp.services["dev.ucp.shopping"][0].endpoint),
"capabilities": list(ucp.capabilities or {}),
"payment_handlers": [
h.id for handlers in ucp.payment_handlers.values() for h in handlers
],
"keys": [k.model_dump(exclude_none=True) for k in profile.keys or []],
}
self.merchants[merchant_url] = info
return info
async def mcp_call(
self, merchant_url: str, tool_name: str, arguments: dict
) -> dict:
"""Call a merchant's MCP tool via JSON-RPC 2.0."""
merchant = self.merchants[merchant_url]
meta = {
"ucp-agent": {
"profile": PLATFORM_PROFILE,
# Mock shortcut: a real merchant reads the platform's public
# keys from the profile URL above instead
"keys": self.platform_keys,
},
"idempotency-key": str(uuid.uuid4()),
}
resp = await self.client.post(
merchant["mcp_endpoint"],
json={
"jsonrpc": "2.0",
"id": uuid.uuid4().hex,
"method": "tools/call",
"params": {
"name": tool_name,
"arguments": {"meta": meta, **arguments},
},
},
)
resp.raise_for_status()
data = resp.json()
if "error" in data:
raise Exception(f"MCP error: {data['error']}")
return data["result"]["structuredContent"]
async def close(self):
await self.client.aclose()
agent_payments/ap2_handler.py erstellen:
"""AP2 mandate handler: verifies the merchant's signature and signs mandates."""
import json
import time
from jwcrypto.jwk import JWK
from jwcrypto.jws import JWS
from ap2.sdk.mandate import MandateClient
from ap2.sdk.utils import b64url_decode, b64url_encode, compute_sha256_b64url
from ap2.sdk.generated.checkout_mandate import CheckoutMandate
from ap2.sdk.generated.payment_mandate import PaymentMandate
from ap2.sdk.generated.types.amount import Amount
from ap2.sdk.generated.types.merchant import Merchant
from ap2.sdk.generated.types.payment_instrument import PaymentInstrument
class AP2Handler:
def __init__(self):
# The user's signing key. In production, this key stays in a wallet or
# on a trusted device, and the user approves each signature.
self.key = JWK.generate(kty="EC", crv="P-256", kid="cineagent-user-key")
self.public_key = json.loads(self.key.export_public())
self.mandates = MandateClient()
def verify_merchant_authorization(
self, checkout: dict, merchant_keys: list[dict]
) -> str | None:
"""Check the merchant's signature on a checkout.
The signature is the merchant's price guarantee: if anything in the
checkout changes, the signature no longer matches. Returns the signed
checkout as a JWT, or None if the signature is missing or invalid.
"""
signature = checkout.get("ap2", {}).get("merchant_authorization")
if not signature:
return None
header, _, sig = signature.split(".") # detached JWS: header..signature
payload = {k: v for k, v in checkout.items() if k != "ap2"}
canonical = json.dumps(
payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False
)
checkout_jwt = f"{header}.{b64url_encode(canonical.encode())}.{sig}"
kid = json.loads(b64url_decode(header))["kid"]
key = next((k for k in merchant_keys if k["kid"] == kid), None)
if not key:
return None
try:
jws = JWS()
jws.deserialize(checkout_jwt)
jws.verify(JWK(**key))
except Exception:
return None
return checkout_jwt
def create_mandates(
self, checkout: dict, checkout_jwt: str, merchant_name: str
) -> tuple[str, str]:
"""Create and sign a CheckoutMandate and a PaymentMandate.
Both mandates reference the hash of the merchant-signed checkout, so
the user's approval is bound to exactly this cart and price.
"""
checkout_hash = compute_sha256_b64url(checkout_jwt)
total = next(t["amount"] for t in checkout["totals"] if t["type"] == "total")
now = int(time.time())
checkout_mandate = CheckoutMandate(
checkout_jwt=checkout_jwt,
checkout_hash=checkout_hash,
iat=now,
exp=now + 600,
)
payment_mandate = PaymentMandate(
transaction_id=checkout_hash,
payee=Merchant(id=merchant_name, name=merchant_name),
payment_amount=Amount(amount=total, currency=checkout["currency"]),
payment_instrument=PaymentInstrument(
id="instr_1", type="card", description="Demo card"
),
iat=now,
exp=now + 600,
)
# Sign each mandate as an SD-JWT with the user's key
return (
self.mandates.create(payloads=[checkout_mandate], issuer_key=self.key),
self.mandates.create(payloads=[payment_mandate], issuer_key=self.key),
)
Mock-Händler
agent_payments/merchants.py erstellen:
"""Mock UCP merchant servers: two theaters with different capabilities."""
import json
import time
import uuid
import multiprocessing
from datetime import datetime, timezone, timedelta
import uvicorn
from fastapi import FastAPI
from jwcrypto.jwk import JWK
from jwcrypto.jws import JWS
from ap2.sdk.mandate import MandateClient
from ap2.sdk.utils import compute_sha256_b64url
from ap2.sdk.generated.checkout_mandate import CheckoutMandate
from ap2.sdk.generated.payment_mandate import PaymentMandate
from ucp_sdk.models.schemas.common.payment_ap2_mandate import Checkout
from ucp_sdk.models.schemas.profile import BusinessSchema
from ucp_sdk.models.schemas.shopping.catalog_lookup import LookupResponse
from ucp_sdk.models.schemas.shopping.catalog_search import SearchResponse
UCP_VERSION = "2026-08-25"
UCP_SPEC = f"https://ucp.dev/{UCP_VERSION}"
# ── Theater data ────────────────────────────────────────────
THEATERS = {
8081: {
"name": "Meridian Cinemas",
"movies": [
{
"id": "opp",
"title": "Oppenheimer",
"categories": ["Drama", "History"],
"showtimes": [
{"id": "st_opp_7pm_imax", "format": "IMAX", "time": "7:00 PM", "price": 2200, "seats": 45},
{"id": "st_opp_930pm", "format": "Standard", "time": "9:30 PM", "price": 1500, "seats": 80},
],
},
{
"id": "dune3",
"title": "Dune: Part Three",
"categories": ["Sci-Fi", "Action"],
"showtimes": [
{"id": "st_dune_8pm_imax", "format": "IMAX", "time": "8:00 PM", "price": 2200, "seats": 30},
],
},
],
},
8082: {
"name": "StarLight Theaters",
"movies": [
{
"id": "opp",
"title": "Oppenheimer",
"categories": ["Drama", "History"],
"showtimes": [
{"id": "st_opp_6pm_atmos", "format": "Dolby Atmos", "time": "6:00 PM", "price": 1800, "seats": 60},
],
},
{
"id": "spider",
"title": "Spider-Verse",
"categories": ["Animation", "Action"],
"showtimes": [
{"id": "st_spider_4pm", "format": "Standard", "time": "4:00 PM", "price": 1200, "seats": 100},
],
},
],
},
}
def create_app(port):
theater = THEATERS[port]
app = FastAPI()
sessions = {}
checkout_jwts = {} # checkout id -> merchant-signed checkout JWT
# The merchant's signing key. Its public half is published in the profile.
key = JWK.generate(kty="EC", crv="P-256", kid=f"merchant-{port}")
def _capability(name, path, schema, **extra):
return {name: [{
"version": UCP_VERSION,
"spec": f"{UCP_SPEC}/specification/{path}",
"schema": f"{UCP_SPEC}/schemas/{schema}",
**extra,
}]}
payment_handlers = {
"com.example.card": [
{"id": f"card_{port}", "version": UCP_VERSION,
"available_instruments": [{"type": "card"}], "config": {}}
]
}
# ── UCP Discovery endpoint ──────────────────────────────
@app.get("/.well-known/ucp")
def discovery():
profile = {
"ucp": {
"version": UCP_VERSION,
"services": {
"dev.ucp.shopping": [
{"version": UCP_VERSION,
"spec": f"{UCP_SPEC}/specification/overview",
"transport": "mcp",
"schema": f"{UCP_SPEC}/services/shopping/mcp.openrpc.json",
"endpoint": f"http://localhost:{port}/mcp"}
]
},
"capabilities": {
**_capability("dev.ucp.shopping.catalog.search",
"shopping/catalog/search", "shopping/catalog_search.json"),
**_capability("dev.ucp.shopping.catalog.lookup",
"shopping/catalog/lookup", "shopping/catalog_lookup.json"),
**_capability("dev.ucp.shopping.checkout",
"shopping/checkout", "shopping/checkout.json"),
**_capability("dev.ucp.common.payment.ap2_mandate",
"payment/extensions/ap2-mandates",
"common/payment_ap2_mandate.json",
extends="dev.ucp.shopping.checkout",
config={"vp_formats_supported": {"dc+sd-jwt": {}}}),
},
"payment_handlers": payment_handlers,
},
"keys": [json.loads(key.export_public())],
}
# Check the profile against the UCP SDK models before returning it
BusinessSchema.model_validate(profile)
return profile
# ── MCP JSON-RPC endpoint ───────────────────────────────
@app.post("/mcp")
def mcp(body: dict):
tool = body["params"]["name"]
args = body["params"].get("arguments", {})
rid = body.get("id", "1")
if tool == "search_catalog":
q = args.get("catalog", {}).get("query", "").lower()
hits = [m for m in theater["movies"]
if not q or q in m["title"].lower()
or any(q in c.lower() for c in m["categories"])]
result = {"ucp": _ucp_meta("dev.ucp.shopping.catalog.search"),
"products": [_product(m) for m in hits]}
return _ok(rid, SearchResponse, result)
if tool == "lookup_catalog":
ids = args.get("catalog", {}).get("ids", [])
movies = [m for m in theater["movies"] if m["id"] in ids]
if not movies:
return _err(rid, "Not found")
result = {"ucp": _ucp_meta("dev.ucp.shopping.catalog.lookup"),
"products": [_product(m, lookup=True) for m in movies]}
return _ok(rid, LookupResponse, result)
if tool == "create_checkout":
co = args.get("checkout", {})
sid = f"chk_{uuid.uuid4().hex[:12]}"
items, subtotal = [], 0
for li in co.get("line_items", []):
st = _find_showtime(li["item"]["id"])
if not st:
continue
mv = _find_movie(li["item"]["id"])
qty = li.get("quantity", 1)
amt = st["price"] * qty
subtotal += amt
items.append({
"id": f"li_{uuid.uuid4().hex[:8]}",
"item": {
"id": st["id"],
"title": f"{mv['title']} ({st['format']}, {st['time']})",
"price": st["price"],
},
"quantity": qty,
"totals": [{"type": "subtotal", "amount": amt},
{"type": "total", "amount": amt}],
})
if not items:
return _err(rid, "No valid showtimes in checkout")
tax = int(subtotal * 0.08)
total = subtotal + tax
session = {
"ucp": {
**_ucp_meta("dev.ucp.shopping.checkout",
"dev.ucp.common.payment.ap2_mandate"),
"payment_handlers": payment_handlers,
},
"id": sid,
"status": "ready_for_complete",
"currency": "USD",
"line_items": items,
"totals": [
{"type": "subtotal", "display_text": "Subtotal", "amount": subtotal},
{"type": "tax", "display_text": "Tax", "amount": tax},
{"type": "total", "display_text": "Total", "amount": total},
],
"links": [{"type": "terms_of_service",
"url": f"http://localhost:{port}/terms"}],
"expires_at": (
datetime.now(timezone.utc) + timedelta(minutes=10)
).isoformat(),
}
_sign(session)
sessions[sid] = session
return _ok(rid, Checkout, session)
if tool == "get_checkout":
session = sessions.get(args.get("id"))
if not session:
return _err(rid, "Not found")
return _ok(rid, Checkout, session)
if tool == "complete_checkout":
sid = args.get("id")
session = sessions.get(sid)
if not session:
return _err(rid, "Not found")
co = args.get("checkout", {})
checkout_mandate = co.get("ap2", {}).get("checkout_mandate")
instruments = co.get("payment", {}).get("instruments", [])
if not checkout_mandate or not instruments:
return _err(rid, "mandate_required")
payment_mandate = instruments[0]["credential"]["token"]
# Mock shortcut: a real merchant fetches the platform's keys
# from its profile URL (meta["ucp-agent"]["profile"])
platform_key = JWK(**args["meta"]["ucp-agent"]["keys"][0])
try:
cm = MandateClient().verify(
checkout_mandate, platform_key, payload_type=CheckoutMandate
).mandate_payload
pm = MandateClient().verify(
payment_mandate, platform_key, payload_type=PaymentMandate
).mandate_payload
except Exception as e:
return _err(rid, f"mandate_invalid_signature: {e}")
# The mandates must point at the exact checkout this merchant signed
expected_hash = compute_sha256_b64url(checkout_jwts[sid])
total = next(t["amount"] for t in session["totals"] if t["type"] == "total")
if (cm.checkout_jwt != checkout_jwts[sid]
or cm.checkout_hash != expected_hash
or pm.transaction_id != expected_hash
or pm.payment_amount.amount != total):
return _err(rid, "mandate_scope_mismatch")
order_id = f"ord_{uuid.uuid4().hex[:8]}"
session["status"] = "completed"
session["order"] = {
"id": order_id,
"label": theater["name"],
"permalink_url": f"http://localhost:{port}/orders/{order_id}",
"tickets": [
{
"movie": li["item"]["title"],
"quantity": li["quantity"],
"ticket_code": uuid.uuid4().hex[:8].upper(),
}
for li in session["line_items"]
],
}
_sign(session)
return _ok(rid, Checkout, session)
return _err(rid, f"Unknown tool: {tool}")
def _sign(session):
"""Add the merchant's signature (a detached JWS) to the checkout."""
payload = {k: v for k, v in session.items() if k != "ap2"}
canonical = json.dumps(
payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False
)
jws = JWS(canonical.encode())
jws.add_signature(key, alg="ES256",
protected=json.dumps({"alg": "ES256", "kid": key.kid}))
checkout_jwt = jws.serialize(compact=True)
header, _, sig = checkout_jwt.split(".")
session["ap2"] = {"merchant_authorization": f"{header}..{sig}"}
checkout_jwts[session["id"]] = checkout_jwt
def _ucp_meta(*capabilities):
return {"version": UCP_VERSION,
"capabilities": {c: [{"version": UCP_VERSION}] for c in capabilities}}
def _ok(rid, model, result):
# Check the response against the UCP SDK models before returning it
model.model_validate(result)
return {"jsonrpc": "2.0", "id": rid, "result": {
"structuredContent": result,
"content": [{"type": "text", "text": json.dumps(result)}],
}}
def _err(rid, msg):
return {"jsonrpc": "2.0", "id": rid, "error": {"code": -32000, "message": msg}}
def _product(movie, lookup=False):
prices = [st["price"] for st in movie["showtimes"]]
return {
"id": movie["id"],
"title": movie["title"],
"description": {"plain": f"{movie['title']} at {theater['name']}"},
"categories": [{"value": c, "taxonomy": "merchant"} for c in movie["categories"]],
"price_range": {
"min": {"amount": min(prices), "currency": "USD"},
"max": {"amount": max(prices), "currency": "USD"},
},
"variants": [
{
"id": st["id"],
"title": f"{st['format']} {st['time']}",
"description": {"plain": f"{st['format']} showing at {st['time']}"},
"options": [
{"name": "format", "label": st["format"]},
{"name": "time", "label": st["time"]},
],
"price": {"amount": st["price"], "currency": "USD"},
"availability": {"available": st["seats"] > 0},
"metadata": {"seats_available": st["seats"]},
**({"inputs": [{"id": movie["id"], "match": "featured"}]} if lookup else {}),
}
for st in movie["showtimes"]
],
}
def _find_showtime(sid):
return next(
(st for m in theater["movies"] for st in m["showtimes"] if st["id"] == sid),
None,
)
def _find_movie(sid):
return next(
(m for m in theater["movies"] for st in m["showtimes"] if st["id"] == sid),
None,
)
return app
def _run(port):
uvicorn.run(create_app(port), host="0.0.0.0", port=port, log_level="warning")
if __name__ == "__main__":
for port in THEATERS:
multiprocessing.Process(target=_run, args=(port,), daemon=True).start()
print("Merchants running: Meridian (:8081), StarLight (:8082)")
print("Press Ctrl+C to stop")
try:
while True:
time.sleep(1)
except KeyboardInterrupt:
pass
Dadurch werden zwei FastAPI-Server mit jeweils zwei Endpunkten erstellt:
GET /.well-known/ucp: UCP-Discovery. Gibt die Funktionen des Händlers, die MCP-Endpunkt-URL, die akzeptierten Zahlungsmethoden und den öffentlichen Signaturschlüssel zurück.POST /mcp: MCP-Vorgänge (Model Context Protocol). Verarbeitet JSON-RPC 2.0-Aufrufe für die Katalogsuche, den Check-out und die Zahlung.
Jeder Händler signiert seine Checkouts mit seinem eigenen Schlüssel, prüft die AP2-Mandate, bevor er eine Bestellung abschließt, und gleicht jede Antwort mit den UCP SDK-Modellen ab.
Starten Sie die Händler in einem neuen Terminal (sie müssen weiter ausgeführt werden):
cd ~/adk-agent-commerce
uv run python agent_payments/merchants.py
Hier sollten Sie dies sehen:
Merchants running: Meridian (:8081), StarLight (:8082)
Prüfen Sie in Ihrem ersten Terminal, ob UCP erkannt wird:
curl -s http://localhost:8081/.well-known/ucp | uv run python -m json.tool
Sie sollten die Funktionen des Händlers, die MCP-Endpunkt-URL, die Zahlungsabwickler und den öffentlichen Schlüssel sehen.
8. Agent mit ADK Web ausführen
Verwenden wir die integrierte Web-UI der ADK CLI. Dadurch wird eine Chat-Oberfläche im Browser bereitgestellt und Tool-Bestätigungsaufforderungen werden automatisch verarbeitet.
Ihr Projekt sollte nun so aussehen:
adk-agent-commerce/
├── pyproject.toml
└── agent_payments/
├── .env # Project settings
├── merchants.py # Mock UCP merchants
├── ucp_client.py # UCP client helper
├── ap2_handler.py # AP2 mandate handler
├── tools.py # Agent tools
└── agent.py # Agent definition
Ausprobieren
Wechseln Sie im ersten Terminal zum Ordner adk-agent-commerce (ein Ordner über agent_payments) und starten Sie die ADK-Web-UI:
cd ~/adk-agent-commerce
uv run adk web --port 8080 --allow_origins '*'
In der Ausgabe sollte angezeigt werden, dass der Server unter http://127.0.0.1:8080 ausgeführt wird.
Mit dem Kundenservicemitarbeiter sprechen
- Öffnen Sie die ADK-Web-UI, indem Sie bei gedrückter Ctrl- oder Cmd-Taste auf die URL klicken oder auf den Button Webvorschau klicken und Vorschau auf Port 8080 auswählen.
- Wählen Sie
agent_paymentsaus dem Drop-down-Menü aus, falls es nicht bereits ausgewählt ist. Eine Chat-Oberfläche wird angezeigt. - Frag zum Beispiel: Welche Filme werden gezeigt?
- Der Kundenservicemitarbeiter sucht im Hintergrund nach Kinos und Katalogen und fasst die Ergebnisse beider Händler über UCP zusammen.
- Tickets buchen: „Buche 2 Tickets für Oppenheimer um 19:00 Uhr.“
- Wenn der Agent versucht,
complete_purchaseaufzurufen, wird in der ADK Web-UI eine Bestätigungskarte mit den Kaufdetails angezeigt. - Wenn Sie die Transaktion autorisieren möchten, setzen Sie ein Häkchen in das Kästchen Bestätigt auf der Karte und klicken Sie auf Senden.
- Der Kundenservicemitarbeiter schließt den Kauf ab und sendet Ihnen die Bestellbestätigung mit den Ticketcodes zurück.
So ging es hinter den Kulissen zu:
create_checkout→ Der Händler hat einen mit seinem Schlüssel signierten Checkout zurückgegeben (ap2.merchant_authorization, die Preissperre).complete_purchase→ Die Signatur des Händlers wurde bestätigt, ein CheckoutMandate und ein PaymentMandate wurden erstellt, beide wurden als SD-JWTs signiert und an den Händler gesendet.- Der Händler hat beide Mandate bestätigt und geprüft, ob sie auf die unterzeichnete Kasse verweisen → Tickets ausgestellt (im Mock)
9. Bereinigen
So vermeiden Sie, dass lokale Server weiter ausgeführt werden:
- Drücken Sie im Terminal, in dem
adk webausgeführt wird, Strg + C, um den Agent-Server zu beenden. - Drücken Sie im Terminal, in dem
merchants.pyausgeführt wird, Strg + C, um die Test-Händler zu beenden. - Optional: Wenn Sie für dieses Codelab ein neues Google Cloud-Projekt erstellt haben und es löschen möchten, führen Sie den folgenden Befehl aus und ersetzen Sie
durch die Projekt-ID:
gcloud projects delete <YOUR_PROJECT_ID>
10. Glückwunsch! 🎉
Sie haben einen ADK-Agenten erstellt, der Händler findet, Kataloge durchsucht und Käufe über UCP und AP2 abschließt.
Das haben Sie gelernt
In diesem Codelab haben Sie einen ADK-Agenten erstellt, der sichere Commerce-Abläufe verarbeitet. Hier eine Zusammenfassung der erstellten Inhalte und der angewendeten Schlüsselkonzepte:
Was Sie erstellt haben:
- 5 Agent-Tools für UCP- und AP2-Vorgänge: Erkennung, Katalogsuchen, Kaufabwicklung und Zahlung.
- AP2-Mandatsunterzeichnung: Vom Händler unterzeichnete Kaufabwicklung (Preisbindung) + CheckoutMandate und PaymentMandate (Nutzerautorisierung).
- Suche bei mehreren Händlern: Ein Agent fragt mehrere Kinos ab und führt die Ergebnisse zusammen.
Wichtige Konzepte:
Protokoll | Funktion | Funktionsweise |
UCP Discovery | Der KI-Agent findet Händler und ihre Funktionen. |
|
UCP MCP | Der Agent durchsucht Kataloge und erstellt Check-outs. | JSON-RPC 2.0-Aufrufe des MCP-Endpunkts des Händlers |
Händlerautorisierung | Der Händler legt den angegebenen Preis fest. | Vom Händler unterzeichnet, umfasst Positionen und Summen |
AP2 CheckoutMandate | Nutzer genehmigt den genauen Bezahlvorgang | Vom Nutzer signiert, enthält die vom Händler signierte Kaufabwicklung |
AP2 PaymentMandate | Nutzer autorisiert die Belastung | Vom Nutzer signiert, verweist auf den Checkout-Hash |
Was ist in der Produktion anders?
In diesem Codelab werden Mocks verwendet. In Produktion:
- UCP-Discovery wird anhand einer Registry aufgelöst, nicht anhand von hartcodierten localhost-URLs.
- MCP-Endpunkte werden von echten Händlern gehostet: gleiches JSON-RPC 2.0-Protokoll, echtes Inventar
- AP2-Befehle werden auf dem vertrauenswürdigen Gerät des Nutzers oder von einer vertrauenswürdigen Plattform signiert, nicht mit einem Schlüssel, der vom Agent beim Start generiert wird.
- Signaturschlüssel stammen aus dem UCP-Profil der jeweiligen Partei (die Mock-Händler erhalten stattdessen den öffentlichen Schlüssel des KI-Agenten in jeder Anfrage).
- Die Zahlungsautorisierung erfolgt über einen Anmeldedatenanbieter, der das Zahlungsermächtigungsformular überprüft und die Einwilligung des Nutzers einholt.
- Im Frontend werden Tool-Ergebnisse als Rich-UI gerendert (Produktübersichten, Zusammenfassungen an der Kasse, Bestätigungskarten).
Nächste Schritte
- AP2-Protokollspezifikation ansehen und eigenen zahlungsfähigen KI-Agenten erstellen
- UCP für Ihren Händler implementieren, um den agentenbasierten Handel zu aktivieren
- AP2 mit A2A für Multi-Agent-Commerce-Workflows verbinden
- Weitere Informationen zur AP2 x402-Erweiterung für Kryptowährungszahlungen