1. Présentation
Dans cet atelier de programmation, vous allez exécuter un agent ADK qui réserve des billets de cinéma auprès de plusieurs marchands de cinéma à l'aide de deux protocoles commerciaux Open Source :
- UCP (Universal Commerce Protocol) : norme permettant aux agents de découvrir des marchands, de rechercher des catalogues et de gérer les flux de paiement.
- AP2 (Agent Payments Protocol) : protocole permettant d'autoriser les paiements de manière sécurisée et vérifiable à l'aide de mandats signés de manière cryptographique.
L'application de démonstration CineAgent se connecte à deux faux marchands de cinéma dotés de différentes fonctionnalités (sélection de sièges, formats spécialisés et modes de paiement) et orchestre l'ensemble du processus de réservation, de la recherche au paiement.
Points abordés
- Fonctionnement de la découverte des marchands UCP via les profils
/.well-known/ucp - Comment un agent ADK utilise UCP pour rechercher des catalogues et créer des paiements
- Comment les mandats AP2 (CheckoutMandate, PaymentMandate) sécurisent les transactions
- Comment les protocoles UCP et AP2 de bout en bout sécurisent le commerce électronique agentique
Prérequis
- Un projet Google Cloud avec facturation activée
- Un navigateur Web (par exemple, Chrome)
- Python 3.11 ou version ultérieure et uv, si vous exécutez le code sur votre propre machine au lieu de Cloud Shell
Cet atelier de programmation s'adresse aux développeurs intermédiaires qui connaissent déjà Python et Google Cloud. Cet atelier de programmation prend environ 30 minutes.
Les ressources créées dans cet atelier de programmation devraient coûter moins de 5 $.
2. Comprendre les protocoles UCP et AP2
Avant de commencer à créer l'agent, examinons les deux protocoles qui rendent possible ce commerce agentique sécurisé.
Cet atelier de programmation utilise la version 2026-08-25 d'UCP avec le SDK Python UCP et AP2 v0.2 avec le SDK Python AP2.
Universal Commerce Protocol (UCP)
L'UCP standardise la façon dont les agents IA interagissent avec les marchands. Il résout le problème des agents qui doivent apprendre des API personnalisées pour chaque magasin en introduisant un modèle de ressources standardisé.
Fonctionnement :
- Découverte : chaque marchand conforme à l'UCP expose un profil à un emplacement standard :
/.well-known/ucp. Exemple : Point de terminaison UCP d'Everlane.Lorsqu'un agent lit ce profil, il recherche les éléments suivants :- Fonctionnalités : fonctionnalités de base autonomes proposées par une entreprise, comme la recherche dans le catalogue ou le règlement.
- Services : couches de communication de niveau inférieur utilisées pour échanger des données. Exemples : API REST, MCP (Model Context Protocol), A2A (Agent2Agent Protocol).
- Extensions : si un marchand a besoin d'un comportement spécialisé, il peut définir des extensions personnalisées dans ce profil.
- Clés : clés de signature publiques du marchand, que les agents utilisent pour vérifier les signatures du marchand.
- Opérations : une fois le point de terminaison du service découvert, l'agent l'utilise pour effectuer des opérations. Dans cet atelier de programmation, nous utilisons le Model Context Protocol (MCP) comme transport de service. L'agent effectue des appels JSON-RPC 2.0 à ce point de terminaison pour invoquer les fonctionnalités découvertes : recherche de produits, création de paiements et finalisation d'achats.

Agent Payments Protocol (AP2)
AP2 standardise la façon dont les paiements sont autorisés par les agents au nom des utilisateurs. Elle résout le problème de sécurité lié à la gestion des identifiants de paiement sensibles par les agents.
Fonctionnement :
- Signature du marchand : lorsqu'un agent crée un paiement à l'aide du protocole UCP, le marchand signe le paiement (articles et totaux) et renvoie la signature dans
ap2.merchant_authorization. Il agit comme une garantie de blocage du prix. Si le marchand modifie le prix après la signature, celle-ci ne correspond plus. - Mandat de paiement et mandat de paiement à la caisse : après avoir vérifié le contenu de la commande, l'utilisateur (ou l'agent en son nom) signe deux mandats. Le
CheckoutMandatecontient le paiement signé par le marchand et indique à ce dernier que l'utilisateur l'a approuvé. LePaymentMandateautorise le montant du paiement pour ce règlement. Les deux font référence à un hachage du paiement signé et comportent la signature cryptographique de l'utilisateur. - Validation de la signature : le marchand reçoit les deux mandats. Il vérifie la signature de l'utilisateur sur le
CheckoutMandateet s'assure que le paiement qu'il contient porte la propre signature du marchand. LePaymentMandateest envoyé au service de paiement (fournisseur d'identifiants ou processeur de paiement), qui le vérifie avant de transférer l'argent. Si tout est valide, la transaction est effectuée.
Ce système de "double verrouillage" garantit que les marchands ne peuvent pas facturer de montants trop élevés et que les agents ne peuvent pas dépenser sans autorisation. Les mandats sont des identifiants SD-JWT (Selective Disclosure JWT), qui protègent la confidentialité des utilisateurs en ne révélant que les champs dont chaque partie a besoin. Dans AP2 v0.2, CheckoutMandate remplace CartMandate d'AP2 v0.1.

3. Configurer votre environnement
Configurer un projet Google Cloud
Créer un projet Google Cloud
- Dans la console Google Cloud, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.
- Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.
Démarrer Cloud Shell
Cloud Shell est un environnement de ligne de commande exécuté dans Google Cloud et fourni avec les outils nécessaires.
- Cliquez sur Activer Cloud Shell en haut de la console Google Cloud.
- Une fois connecté à Cloud Shell, vérifiez votre authentification :
gcloud auth list - Vérifiez que votre projet est configuré :
gcloud config get project - Si votre projet n'est pas défini comme prévu, définissez-le :
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
Activer les API
Exécutez la commande suivante pour activer les API requises :
gcloud services enable aiplatform.googleapis.com
Configurer la structure des répertoires
Copiez et collez les commandes suivantes pour créer un dossier pour cet atelier de programmation, avec un dossier agent_payments à l'intérieur pour le code de l'agent :
mkdir -p ~/adk-agent-commerce/agent_payments
cd ~/adk-agent-commerce
Accéder aux modèles Gemini
Copiez et collez la commande suivante pour créer agent_payments/.env avec votre projet et votre emplacement, et pour que ADK appelle Gemini via votre projet Google Cloud. L'agent Cine utilise Gemini pour décider quels outils appeler. ADK charge automatiquement ce fichier, ce qui permet aux paramètres de fonctionner également dans les nouveaux terminaux.
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
Installer des dépendances
Google Cloud Shell est préinstallé avec uv pour gérer l'environnement et les dépendances.
- Créez un fichier
pyproject.tomlà la racine de votre dossieradk-agent-commerceet ajoutez-y le contenu suivant. Ce fichier définit les métadonnées et les dépendances du projet.
[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",
]
Le SDK AP2 s'installe à partir de son dépôt GitHub, car il n'est pas encore publié sur PyPI. (Le package ap2 sur PyPI est un projet distinct.)
- Exécutez la commande suivante pour créer l'environnement virtuel et installer toutes les dépendances :
uv sync
uv crée un environnement Python isolé pour cet atelier de programmation. Vous n'avez donc rien à activer. Faites précéder les commandes Python de uv run.
4. Définir l'agent
Avant d'écrire une logique d'outil, définissons l'agent lui-même dans un fichier nommé agent.py. Cet agent servira d'orchestrateur pour le flux de réservation de billets de cinéma.
Créez une agent_payments/agent.py :
"""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),
],
)
Explication du code
Décomposons ce qui se passe dans cette définition d'agent :
model=Gemini(...): nous utilisons Gemini 3.8 Flash pour le raisonnement et l'utilisation d'outils.instruction: il s'agit du prompt qui guide le comportement de l'agent. Il indique explicitement à l'agent d'utiliser UCP et AP2, liste les outils disponibles et définit des règles essentielles telles que "N'inventez jamais de données" et "Les prix sont en centimes".tools: il s'agit d'une liste de fonctions Python (que nous allons créer ensuite) que l'agent peut choisir d'appeler en fonction des demandes de l'utilisateur.require_confirmation: vous pouvez encapsuler n'importe quel outil avecFunctionTool(my_function,require_confirmation=True). Lorsqu'il est déclenché, l'agent s'interrompt et attend une simple approbation par un "oui" ou un "non" avant d'exécuter l'outil. Ici, avant d'exécuter l'outilcomplete_purchase, l'agent s'interrompt pour obtenir une confirmation humaine.
Liste des outils
La définition de l'agent déclare ce que nous devons créer. Chaque outil correspond à une opération spécifique dans le protocole UCP ou AP2 :
Outil | Description | Action de protocole |
| Trouver des marchands et leurs fonctionnalités | Requêtes |
| Rechercher des catalogues de différents marchands | Point de terminaison JSON-RPC vers MCP |
| Obtenir les horaires des séances dans un cinéma spécifique | Point de terminaison JSON-RPC vers MCP |
| Démarrer une session de paiement | Point de terminaison JSON-RPC vers MCP |
| Autoriser le paiement et finaliser la commande | Signe les mandats AP2 et les envoie à MCP |
Le modèle Gemini décidera quand appeler chaque outil en fonction de la conversation. Notre prochaine tâche consiste à implémenter ce que fait chaque outil dans tools.py.
5. Créer les outils de l'agent : découverte et navigation
Implémentons maintenant les outils que l'agent utilisera pour parcourir et découvrir des films. Chaque outil encapsule une opération UCP.
Créez un fichier nommé agent_payments/tools.py et copiez-collez le code suivant :
"""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])
Comprendre la configuration
Pour que cet atelier de programmation reste axé sur la création de l'agent, nous utilisons deux classes d'assistance, UCPClient et AP2Handler, que nous examinerons dans une étape ultérieure.
- De quoi s'agit-il ? : Il s'agit de petites classes d'assistance que nous avons écrites pour cet atelier de programmation afin de communiquer avec les marchands fictifs. Les SDK officiels fournissent les éléments de protocole : le SDK UCP contient des modèles de données pour chaque schéma UCP, et le SDK AP2 crée et valide les mandats signés. Aucun SDK n'inclut de client pour appeler les marchands. Ces helpers gèrent donc cette partie.
- Pour l'instant, traitez-les comme des objets d'assistance :
_ucp.discover(url): récupère et valide le profil d'un marchand._ucp.mcp_call(url, method, params): envoie une requête JSON-RPC 2.0 au point de terminaison MCP du marchand.
Découvrir les cinémas
Cet outil est la première étape du flux UCP. Il identifie les marchands existants et les fonctionnalités qu'ils prennent en charge.
Ajoutez les éléments suivants à tools.py :
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)
Fonction :
- Il itère sur une liste d'URL de marchands fournies par le serveur. Dans cet atelier de programmation, nous allons configurer deux marchands fictifs dans la section suivante.
- Pour chaque URL, il appelle
_ucp.discover(url), qui atteint le point de terminaison/.well-known/ucp. - Il collecte le nom, les fonctionnalités et les gestionnaires de paiement dans une liste récapitulative.
- Il renvoie la liste sous forme de chaîne JSON pour que l'agent puisse la lire.
Rechercher des films
Cet outil recherche tous les marchands découverts et fusionne les résultats. C'est essentiel, car le même film peut être projeté dans plusieurs cinémas avec des formats (IMAX, Dolby) et des prix différents.
Ajoutez les éléments suivants à tools.py :
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)
Fonction :
- Il parcourt tous les cinémas détectés.
- Il envoie une requête JSON-RPC de catalogue de recherche (
_ucp.mcp_call(url, "search_catalog", {"catalog": {"query": query}})) au point de terminaison MCP du marchand. - Il effectue ensuite un peu de nettoyage pour analyser les résultats et trouver les films et leurs "variantes" (qui représentent des horaires et des formats spécifiques). Regroupe les films par ID pour que l'utilisateur ne voie pas d'entrées de films en double.
Obtenir les détails d'un film
Cet outil permet d'obtenir tous les détails du catalogue pour un film spécifique dans un cinéma spécifique.
Ajoutez les éléments suivants à tools.py :
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)
Fonction :
- Il appelle la méthode
lookup_catalogsur le point de terminaison MCP du marchand, en transmettant lemovie_idspécifique danscatalog.ids. Vous obtiendrez des informations détaillées, comme les horaires des séances et les places disponibles pour ce cinéma en particulier.
6. Créer les outils de l'agent : paiement et règlement
Ces outils gèrent le processus de paiement et d'achat. C'est là qu'intervient le protocole AP2 pour garantir la sécurité des transactions.
Créer une page de paiement
Cet outil lance une session de paiement dans un cinéma spécifique pour une séance spécifique.
Ajoutez les éléments suivants à tools.py :
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)
Fonction :
- Elle appelle la méthode
create_checkoutsur le point de terminaison MCP du marchand. - Il transmet les
showtime_idetquantitydemandés par l'utilisateur. - Le marchand renvoie un paiement signé avec sa clé.
Remarque : Si vous examinez les données de réponse, le champ ap2.merchant_authorization contient la signature cryptographique du marchand pour le paiement, ce qui bloque le prix indiqué. Ils ne pourront pas le modifier par la suite.
Finaliser l'achat
Cet outil permet d'effectuer trois actions :
- Nous récupérons le paiement et vérifions la signature du marchand.
- Créez et signez les CheckoutMandate et PaymentMandate avec le SDK AP2.
- Envoyez les deux mandats au marchand pour finaliser l'achat.
Ajoutez les éléments suivants à tools.py :
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)
Pourquoi deux mandats ? Le CheckoutMandate prouve au marchand que l'utilisateur a approuvé ce paiement exact, au prix indiqué par le marchand. Le PaymentMandate prouve au côté paiement que l'utilisateur a autorisé ce débit. Le flux est organisé ainsi :
Merchant signs checkout -> User signs mandates -> Merchant and payment side verify -> Order completes.
Point de contrôle : tools.py
Votre tools.py complet doit maintenant comporter cinq fonctions d'outil et une initialisation au niveau du module pour les clients UCP et AP2. Vérifiez qu'il ressemble à ceci :
"""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. Rendre le code exécutable
Avec de vrais marchands UCP, il vous suffirait d'indiquer les URL à l'agent. Pour cet atelier de programmation, nous avons besoin de deux éléments pour effectuer des tests en local :
- Marchands fictifs : serveurs locaux qui simulent des points de terminaison UCP pour vous permettre d'effectuer des tests
- Assistance pour les protocoles : wrappers fins qui appellent les marchands via HTTP et utilisent les SDK UCP et AP2 pour les données et les signatures de protocole
Remarque : Vous n'avez pas besoin de lire attentivement ce code. Ces fichiers simulent de vrais marchands et le portefeuille d'un utilisateur. Copiez-les tels quels.
Assistance pour les protocoles
Le SDK UCP fournit des modèles de données, et le SDK AP2 signe et valide les mandats, mais aucun des deux n'inclut de client pour communiquer avec les marchands. Ces deux fichiers comblent cette lacune. Ils sont nommés ucp_client.py et ap2_handler.py afin de ne pas masquer le package ap2.
Créez une agent_payments/ucp_client.py :
"""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()
Créez une agent_payments/ap2_handler.py :
"""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),
)
Marchands fictifs
Créez une agent_payments/merchants.py :
"""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
Cela crée deux serveurs FastAPI, chacun avec deux points de terminaison :
GET /.well-known/ucp: découverte UCP. Renvoie les capacités du marchand, l'URL du point de terminaison MCP, les modes de paiement acceptés et la clé de signature publique.POST /mcp: opérations MCP (Model Context Protocol). Gère les appels JSON-RPC 2.0 pour la recherche dans le catalogue, le règlement et le paiement.
Chaque marchand signe ses paiements avec sa propre clé, vérifie les mandats AP2 avant de finaliser une commande et vérifie chaque réponse par rapport aux modèles du SDK UCP.
Démarrez les marchands dans un nouveau terminal (ils doivent rester en cours d'exécution) :
cd ~/adk-agent-commerce
uv run python agent_payments/merchants.py
Vous devriez obtenir le résultat suivant :
Merchants running: Meridian (:8081), StarLight (:8082)
De retour dans votre premier terminal, vérifiez la découverte UCP :
curl -s http://localhost:8081/.well-known/ucp | uv run python -m json.tool
Vous devriez voir les capacités du marchand, l'URL du point de terminaison MCP, les gestionnaires de paiement et la clé publique.
8. Exécuter l'agent avec ADK Web
Utilisons l'UI Web intégrée à la CLI de l'ADK. Cela fournit une interface de chat dans le navigateur et gère automatiquement les invites de confirmation des outils.
Votre projet doit maintenant se présenter comme suit :
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
Essayer
Dans votre premier terminal, accédez au dossier adk-agent-commerce (un dossier au-dessus de agent_payments) et démarrez l'UI Web d'ADK :
cd ~/adk-agent-commerce
uv run adk web --port 8080 --allow_origins '*'
Le résultat qui s'affiche doit indiquer que le serveur s'exécute sur http://127.0.0.1:8080.
Parler à l'agent
- Ouvrez l'interface utilisateur Web de l'ADK en cliquant sur l'URL avec Ctrl ou Cmd, ou en cliquant sur le bouton Aperçu sur le Web et en sélectionnant Prévisualiser sur le port 8080.
- Sélectionnez
agent_paymentsdans le menu déroulant si ce n'est pas déjà fait. Une interface de chat s'affiche. - Essayez de demander Quels sont les films à l'affiche ?
- L'agent découvre les cinémas et recherche des catalogues en coulisses, en agrégeant les résultats des deux marchands via UCP.
- Demandez à réserver des billets : "Réserve deux billets pour Oppenheimer à 19h."
- Lorsque l'agent tente d'appeler
complete_purchase, notez que l'UI Web d'ADK affiche une fiche de confirmation avec les détails de l'achat. - Pour autoriser la transaction, cochez la case Confirmé sur la carte, puis cliquez sur Envoyer.
- L'agent finalisera l'achat et vous enverra la confirmation de votre commande avec les codes des billets.
Voici ce qui s'est passé en coulisses :
create_checkout→ le marchand a renvoyé un paiement signé avec sa clé (ap2.merchant_authorization, le prix fixe)complete_purchase→ a vérifié la signature du marchand, créé un CheckoutMandate et un PaymentMandate, signé les deux en tant que SD-JWT et les a envoyés au marchand- Le marchand a vérifié les deux mandats et s'est assuré qu'ils pointaient vers le paiement qu'il a signé → émission de tickets (dans la simulation)
9. Effectuer un nettoyage
Pour éviter de laisser des serveurs locaux en cours d'exécution, nettoyez les ressources :
- Dans le terminal exécutant
adk web, appuyez sur Ctrl+C pour arrêter le serveur de l'agent. - Dans le terminal exécutant
merchants.py, appuyez sur Ctrl+C pour arrêter les marchands fictifs. - (Facultatif) Si vous avez créé un projet Google Cloud pour cet atelier de programmation et que vous souhaitez le supprimer, exécutez la commande suivante en remplaçant
par son ID de projet :
gcloud projects delete <YOUR_PROJECT_ID>
10. Félicitations ! 🎉
Vous avez créé un agent ADK qui découvre des marchands, parcourt des catalogues et effectue des achats à l'aide d'UCP et d'AP2.
Ce que vous avez appris
Dans cet atelier de programmation, vous avez créé un agent ADK qui gère les flux commerciaux sécurisés. Voici un résumé de ce que vous avez créé et des concepts clés que vous avez appliqués :
Ce que vous avez créé :
- Cinq outils d'agent encapsulant les opérations UCP et AP2 : découverte, recherche dans le catalogue, règlement et paiement.
- Signature du mandat AP2 : finalisation de la commande signée par le marchand (prix fixe) + CheckoutMandate et PaymentMandate (autorisation de l'utilisateur).
- Recherche multimarchands : un agent interroge plusieurs cinémas et fusionne les résultats.
Concepts clés :
Protocole | Description | Fonctionnement |
Découverte de l'UCP | L'agent trouve des marchands et leurs capacités |
|
UCP MCP | L'agent parcourt les catalogues et crée des paiements | Appels JSON-RPC 2.0 au point de terminaison MCP du marchand |
Autorisation du marchand | Le marchand bloque le prix indiqué | Signé par le marchand, couvre les éléments de ligne et les totaux |
AP2-CheckoutMandate | L'utilisateur approuve le paiement exact | Signé par l'utilisateur, contient le paiement signé par le marchand |
AP2-PaymentMandate | L'utilisateur autorise le débit | Signé par l'utilisateur, fait référence au hachage du paiement |
Qu'est-ce qui change en production ?
Cet atelier de programmation utilise des mocks. En production :
- La découverte UCP est résolue par rapport à un registre, et non par rapport à des URL localhost codées en dur.
- Les points de terminaison MCP sont hébergés par de vrais marchands : même protocole JSON-RPC 2.0, inventaire réel
- Les mandats AP2 sont signés sur l'appareil de confiance de l'utilisateur ou par une plate-forme de confiance, et non avec une clé générée par l'agent au démarrage.
- Les clés de signature proviennent du profil UCP de chaque partie (les marchands fictifs reçoivent la clé publique de l'agent dans chaque requête).
- L'autorisation de paiement passe par un fournisseur d'identifiants qui vérifie le PaymentMandate et demande le consentement de l'utilisateur.
- Le frontend affiche les résultats des outils sous forme d'UI enrichie (grilles de produits, récapitulatifs de paiement, cartes de confirmation).
Étapes suivantes
- Explorez les spécifications du protocole AP2 et créez votre propre agent compatible avec les paiements.
- Implémenter l'UCP pour votre marchand afin d'activer le commerce agentique
- Connectez AP2 à A2A pour les workflows commerciaux multi-agents
- En savoir plus sur l'extension AP2 x402 pour les paiements en cryptomonnaie