1. Genel Bakış
Bu codelab'de, iki açık kaynaklı ticaret protokolü kullanarak birden fazla sinema satıcısından sinema bileti ayırtan bir ADK aracısı çalıştıracaksınız:
- UCP (Evrensel Ticaret Protokolü): Ajanların satıcıları keşfetmesi, kataloglarda arama yapması ve ödeme akışlarını yönetmesi için kullanılan bir standarttır.
- AP2 (Agent Payments Protocol): Kriptografik olarak imzalanmış yetkiler kullanılarak güvenli ve doğrulanabilir ödeme yetkilendirmesi için kullanılan bir protokoldür.
CineAgent adlı demo uygulaması, farklı özelliklere (koltuk seçimi, özel formatlar ve ödeme yöntemleri) sahip iki sahte sinema satıcısına bağlanır ve arama işleminden ödemeye kadar tüm rezervasyon akışını yönetir.
Neler öğreneceksiniz?
- UCP'de satıcı keşfi,
/.well-known/ucpprofilleri üzerinden nasıl çalışır? - ADK aracısının kataloglarda arama yapmak ve ödeme oluşturmak için UCP'yi kullanma şekli
- AP2 zorunlulukları (CheckoutMandate, PaymentMandate) işlemleri nasıl güvence altına alır?
- Uçtan uca UCP ve AP2 protokollerinin, ajan tabanlı e-ticaretin güvenliğini sağlamak için işleyiş şekli
İhtiyacınız olanlar
- Faturalandırmanın etkin olduğu bir Google Cloud projesi
- Chrome gibi bir web tarayıcısı
- Cloud Shell yerine kodu kendi makinenizde çalıştırıyorsanız Python 3.11+ ve uv
Bu codelab, Python ve Google Cloud hakkında bilgi sahibi olan orta düzey geliştiriciler içindir. Bu codelab'in tamamlanması yaklaşık 30 dakika sürer.
Bu codelab'de oluşturulan kaynakların maliyeti 5 ABD dolarından az olmalıdır.
2. UCP ve AP2 protokollerini anlama
Aracı oluşturmaya başlamadan önce, bu güvenli aracı tabanlı ticareti mümkün kılan iki protokolü anlayalım.
Bu codelab'de UCP Python SDK ile 2026-08-25 UCP sürümü ve AP2 Python SDK ile AP2 v0.2 sürümü kullanılmaktadır.
Evrensel Ticaret Protokolü (UCP)
UCP, yapay zeka ajanlarının satıcılarla etkileşim kurma şeklini standart hâle getirir. Standartlaştırılmış bir kaynak modeli sunarak aracıların her mağaza için özel API'leri öğrenmesi sorununu çözer.
İşleyiş şekli:
- Bulma: UCP'ye uygun her satıcı, standart bir konumda profil gösterir:
/.well-known/ucp. Örnek: Everlane'in UCP uç noktası.Bir temsilci bu profili okuduğunda şunları arar:- Özellikler: İşletmenin desteklediği bağımsız temel özellikler (ör. katalogda arama veya ödeme).
- Hizmetler: Veri alışverişi için kullanılan alt düzey iletişim katmanları. Örnekler: REST API, Model Bağlam Protokolü (MCP), A2A (Agent2Agent Protocol).
- Uzantılar: Bir satıcının özel davranışa ihtiyacı varsa bu profilde özel uzantılar tanımlayabilir.
- Anahtarlar: Satıcının imzalarını kontrol etmek için aracıların kullandığı, satıcının ortak imzalama anahtarları.
- İşlemler: Ajan, keşfedildikten sonra işlemleri gerçekleştirmek için sağlanan hizmet uç noktasını kullanır. Bu codelab'de, hizmet aktarımı olarak Model Bağlam Protokolü (MCP)'yi kullanıyoruz. Aracı, keşfedilen özellikleri (ürün arama, ödeme oluşturma ve satın alma işlemlerini tamamlama) çağırmak için bu uç noktaya JSON-RPC 2.0 çağrıları yapar.

Agent Payments Protocol (AP2)
AP2, ödemelerin kullanıcılar adına aracılar tarafından nasıl yetkilendirileceğini standartlaştırır. Hassas ödeme bilgilerini işleyen aracıların güvenlik sorununu çözer.
İşleyiş şekli:
- Satıcı imzası: Bir ajan, UCP protokolünü kullanarak ödeme oluşturduğunda satıcı, ödemeyi (satır öğeleri ve toplamlar) imzalar ve imzayı
ap2.merchant_authorizationiçinde döndürür. Fiyat sabitleme garantisi görevi görür. Satıcı, imzaladıktan sonra fiyatı değiştirirse imza artık eşleşmez. - Ödeme ve ödeme talimatı: Kullanıcı (veya kullanıcı adına hareket eden aracı) ödeme içeriğini doğruladıktan sonra iki talimat imzalar.
CheckoutMandate, satıcı tarafından imzalanmış ödeme işlemini içerir ve satıcıya kullanıcının bunu onayladığını bildirir.PaymentMandate, söz konusu ödeme için ödeme tutarını yetkilendirir. Her ikisi de imzalı ödeme işleminin karma değerine referans verir ve kullanıcının kriptografik imzasını taşır. - İmza Doğrulaması: Satıcı, her iki yetkiyi de alır.
CheckoutMandateüzerindeki kullanıcı imzasını doğrular ve içindeki ödeme işleminin satıcının kendi imzasını taşıdığını kontrol eder.PaymentMandate, ödeme tarafına (bir kimlik bilgisi sağlayıcı veya ödeme işlemcisi) gider. Bu taraf, herhangi bir para transferi yapmadan önce 'yı doğrular. Her şey geçerliyse işlem devam eder.
Bu "çift kilit" sistemi, satıcıların fazla ücret almasını ve aracıların yetkisiz harcama yapmasını engeller. Yetkiler, yalnızca her tarafın ihtiyaç duyduğu alanları göstererek kullanıcı gizliliğini koruyan SD-JWT (Seçici Açıklama JWT) kimlik bilgileridir. AP2 v0.2'de CheckoutMandate, AP2 v0.1'deki CartMandate'nin yerini alır.

3. Ortamınızı ayarlama
Google Cloud projesi kurulumu
Google Cloud projesi oluşturma
- Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
- Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını nasıl kontrol edeceğinizi öğrenin.
Cloud Shell'i Başlatma
Cloud Shell, Google Cloud'da çalışan ve gerekli araçların önceden yüklendiği bir komut satırı ortamıdır.
- Google Cloud konsolunun üst kısmından Activate Cloud Shell'i (Cloud Shell'i etkinleştir) tıklayın.
- Cloud Shell'e bağlandıktan sonra kimlik doğrulamanızı onaylayın:
gcloud auth list - Projenizin yapılandırıldığını onaylayın:
gcloud config get project - Projeniz beklendiği gibi ayarlanmamışsa ayarlayın:
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
API'leri etkinleştir
Gerekli API'leri etkinleştirmek için aşağıdaki komutu çalıştırın:
gcloud services enable aiplatform.googleapis.com
Dizin Yapısını Ayarlama
Bu codelab için bir klasör oluşturmak üzere aşağıdaki komutları kopyalayıp yapıştırın. Klasörün içinde, aracı kodunun yer alacağı bir agent_payments klasörü olmalıdır:
mkdir -p ~/adk-agent-commerce/agent_payments
cd ~/adk-agent-commerce
Gemini modellerine erişim
Projeniz ve konumunuzla agent_payments/.env oluşturmak ve ADK'nın Google Cloud projeniz üzerinden Gemini'ı çağırmasını sağlamak için aşağıdaki komutu kopyalayıp yapıştırın. Sinema Ajanı, hangi araçların çağrılacağına karar vermek için Gemini'ı kullanır. ADK bu dosyayı otomatik olarak yüklediğinden ayarlar yeni terminallerde de çalışır.
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
Bağımlılıkları Yükleme
Google Cloud Shell, ortamı ve bağımlılıkları yönetmek için uv önceden yüklenmiş olarak gelir.
adk-agent-commerceklasörünüzün kök dizininde birpyproject.tomldosyası oluşturun ve aşağıdaki içeriği ekleyin. Bu dosya, proje meta verilerini ve bağımlılıklarını tanımlar.
[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",
]
AP2 SDK, henüz PyPI'de yayınlanmadığı için GitHub deposundan yüklenir. (PyPI'deki ap2 paketi, alakasız bir projedir.)
- Sanal ortamı oluşturmak ve tüm bağımlılıkları yüklemek için aşağıdaki komutu çalıştırın:
uv sync
uv, bu codelab için izole bir Python ortamı oluşturur. Bu nedenle herhangi bir şeyi etkinleştirmeniz gerekmez. Python komutlarının önüne uv run ekleyin.
4. Temsilciyi tanımlama
Herhangi bir araç mantığı yazmadan önce, agent.py adlı bir dosyada aracıyı tanımlayalım. Bu ajan, film rezervasyonu akışının düzenleyicisi olarak hareket eder.
agent_payments/agent.py oluşturma:
"""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),
],
)
Kod Açıklaması
Bu aracı tanımında neler olduğunu inceleyelim:
model=Gemini(...): Akıl yürütme ve araç kullanımı için Gemini 3.8 Flash'ı kullanıyoruz.instruction: Bu istem, ajanın davranışını yönlendirir. Bu istem, aracıya UCP ve AP2'yi kullanmasını açıkça söyler, mevcut araçları listeler ve "Asla veri uydurma" ve "Fiyatlar sent cinsindendir" gibi önemli kurallar belirler.tools: Bu, aracının kullanıcının isteklerine göre çağırmayı seçebileceği Python işlevlerinin (bir sonraki adımda oluşturacağız) bir listesidir.require_confirmation: Herhangi bir aracıFunctionTool(my_function,require_confirmation=True)ile sarmalayabilirsiniz. Tetiklendiğinde aracı duraklatır ve aracı çalıştırmadan önce basit bir "evet" veya "hayır" onayı bekler. Burada,complete_purchasearacı yürütülmeden önce ajan, kullanıcı onayı için duraklatılıyor.
Araç Listesi
Ajan tanımı, ne oluşturmamız gerektiğini belirtir. Her araç, UCP veya AP2 protokolündeki belirli bir işlemle eşlenir:
Araç | Ne işe yarar? | Protokol İşlemi |
| Satıcıları ve özelliklerini bulma | Sorgular |
| Satıcılar arasında katalog arama | MCP uç noktasına JSON-RPC |
| Belirli bir satıcının gösterim saatlerini öğrenme | MCP uç noktasına JSON-RPC |
| Ödeme oturumu başlatma | MCP uç noktasına JSON-RPC |
| Ödemeyi yetkilendirin ve siparişi tamamlayın | AP2 Yetkilerini İmzalama ve MCP'ye Gönderme |
Gemini modeli, sohbete göre her aracın ne zaman çağrılacağına karar verir. Bir sonraki görevimiz, her aracın tools.py içinde ne yaptığını uygulamaktır.
5. Aracı araçlarını oluşturma: Keşif ve Göz Atma
Şimdi temsilcinin filmlere göz atmak ve filmleri keşfetmek için kullanacağı araçları uygulayalım. Her araç bir UCP işlemini kapsar.
agent_payments/tools.py adlı yeni bir dosya oluşturun ve aşağıdaki kodu kopyalayıp yapıştırın:
"""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])
Kurulumu Anlama
Bu codelab'in ajanı oluşturmaya odaklanmasını sağlamak için iki yardımcı sınıf (UCPClient ve AP2Handler) kullanıyoruz. Bu sınıfları sonraki bir adımda inceleyeceğiz.
- Nedir?: Bunlar, sahte satıcılarla iletişim kurmak için bu codelab'de yazdığımız küçük yardımcı sınıflardır. Resmi SDK'lar protokol parçalarını sağlar: UCP SDK'sında her UCP şeması için veri modelleri bulunur ve AP2 SDK'sı imzalı yetkiler oluşturup doğrular. Her iki SDK'da da satıcıları aramak için bir istemci bulunmadığından bu yardımcılar bu kısmı yönetir.
- Şimdilik bunları yardımcı nesneler olarak değerlendirin:
_ucp.discover(url): Bir satıcının profilini getirir ve doğrular._ucp.mcp_call(url, method, params): Satıcının MCP uç noktasına JSON-RPC 2.0 isteği gönderir.
Sinemaları keşfetme
Bu araç, UCP akışının ilk adımıdır. Hangi satıcıların olduğunu ve hangi özellikleri desteklediklerini bulur.
tools.py uygulamasına ekleme:
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)
Bu işlem ne yapar?
- Sunucu tarafından sağlanan satıcı URL'lerinin listesini yineler. Bu codelab'in ilerleyen bölümünde iki sahte satıcı oluşturacağız.
- Her URL için
_ucp.discover(url)çağrısı yapılır. Bu çağrı,/.well-known/ucpuç noktasına ulaşır. - Adı, özellikleri ve ödeme işleyicilerini özet bir listede toplar.
- Listeyi, temsilcinin okuması için JSON dizesi olarak döndürür.
Filmlerde Ara
Bu araç, bulunan tüm satıcıları arar ve sonuçları birleştirir. Aynı film, farklı formatlarda (IMAX, Dolby) ve farklı fiyatlarla birden fazla sinemada gösteriliyor olabileceğinden bu bilgi çok önemlidir.
tools.py uygulamasına ekleme:
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)
Bu işlem ne yapar?
- Bulunan tüm sinemaları döngüye alır.
- Satıcının MCP uç noktasına bir arama kataloğu JSON-RPC isteği (
_ucp.mcp_call(url, "search_catalog", {"catalog": {"query": query}})) gönderir. - Ardından, sonuçları ayrıştırarak filmleri ve "varyantlarını" (belirli gösterim saatlerini ve formatları temsil eder) bulmak için biraz temizlik yapar. Filmleri kimliğe göre gruplandırır. Böylece kullanıcı, filmlerin yinelenen girişlerini görmez.
Film Ayrıntılarını Alma
Bu araç, belirli bir sinemadaki belirli bir filme ait tüm katalog ayrıntılarını alır.
tools.py uygulamasına ekleme:
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)
Bu işlem ne yapar?
lookup_catalogyöntemini satıcının MCP uç noktasında çağırır vemovie_iddeğerinicatalog.idsiçinde iletir. Bu işlem, söz konusu sinemayla ilgili gösterim saatleri ve koltuk durumu gibi ayrıntılı bilgileri döndürür.
6. Aracı araçlarını oluşturma: Ödeme
Bu araçlar, ödeme ve satın alma sürecini yönetir. Güvenli işlemler için AP2 protokolü devreye girer.
Ödeme oluşturma
Bu araç, belirli bir gösterim zamanı için belirli bir sinemada ödeme oturumu başlatır.
tools.py uygulamasına ekleme:
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)
Bu işlem ne yapar?
- Satıcının MCP uç noktasında
create_checkoutyöntemini çağırır. - Kullanıcının istediği
showtime_idvequantitydeğerlerini iletir. - Satıcı, satıcının anahtarıyla imzalanmış bir ödeme döndürür.
Not: Yanıt verilerini incelerseniz ap2.merchant_authorization alanında, ödeme sırasında satıcının kriptografik imzası bulunur. Bu imza, teklif edilen fiyatı kilitler. Bu adı daha sonra değiştiremezler.
Satın Alma İşlemini Tamamlayın
Bu araçta üç şey olur:
- Ödeme işlemini alır ve satıcının imzasını doğrularız.
- AP2 SDK ile CheckoutMandate ve PaymentMandate oluşturup imzalayın.
- Satın alma işlemini tamamlamak için her iki yetkiyi de satıcıya gönderin.
tools.py uygulamasına ekleme:
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)
Neden iki yetki? CheckoutMandate, kullanıcının bu ödemeyi satıcının imzaladığı fiyattan onayladığını satıcıya kanıtlar. PaymentMandate, ödeme tarafına kullanıcının bu ücreti yetkilendirdiğini kanıtlar. Akış:
Merchant signs checkout -> User signs mandates -> Merchant and payment side verify -> Order completes.
Kontrol noktası: Tam tools.py
Tam tools.py artık 5 araç işlevine ve UCP ile AP2 istemcileri için modül düzeyinde başlatmaya sahip. Şu şekilde göründüğünü doğrulayın:
"""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. Çalıştırılabilir hale getirme
Gerçek UCP satıcılarında, ajanı URL'lerine yönlendirmeniz yeterli olur. Bu codelab'de yerel olarak test etmek için iki şeye ihtiyacımız var:
- Sahte satıcılar: UCP uç noktalarını simüle eden yerel sunucular sayesinde test edebileceğiniz bir öğe elde edersiniz.
- Protokol yardımcıları: HTTP üzerinden satıcılara çağrı yapan ve protokol verileri ile imzalar için UCP ve AP2 SDK'larını kullanan ince sarmalayıcılar
Not: Bu kodu dikkatlice okumanız gerekmez. Bu dosyalar, gerçek satıcıları ve kullanıcının cüzdanını simüle eder. Olduğu gibi kopyalayın.
Protokol yardımcıları
UCP SDK'sı veri modelleri sağlar, AP2 SDK'sı ise yetkileri imzalar ve doğrular ancak ikisi de satıcılarla iletişim kurmak için bir istemci içermez. Bu iki dosya, söz konusu boşluğu doldurur. ucp_client.py ve ap2_handler.py olarak adlandırılırlar, böylece ap2 paketini gölgelemezler.
agent_payments/ucp_client.py oluşturma:
"""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 oluşturma:
"""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),
)
Sahte satıcılar
agent_payments/merchants.py oluşturma:
"""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
Bu işlem, her biri iki uç nokta içeren iki FastAPI sunucusu oluşturur:
GET /.well-known/ucp: UCP keşfi. Satıcının özellikleri, MCP uç nokta URL'si, kabul edilen ödeme yöntemleri ve herkese açık imzalama anahtarını döndürür.POST /mcp: MCP (Model Bağlam Protokolü) işlemleri. Katalog arama, ödeme ve ödeme için JSON-RPC 2.0 çağrılarını işler.
Her satıcı, ödeme işlemlerini kendi anahtarıyla imzalar, bir siparişi tamamlamadan önce AP2 zorunluluklarını doğrular ve her yanıtı UCP SDK modellerine göre kontrol eder.
Satıcıları yeni bir terminalde başlatın (çalışmaya devam etmeleri gerekir):
cd ~/adk-agent-commerce
uv run python agent_payments/merchants.py
Aşağıdaki bilgileri görürsünüz:
Merchants running: Meridian (:8081), StarLight (:8082)
İlk terminalinize dönerek UCP keşfini doğrulayın:
curl -s http://localhost:8081/.well-known/ucp | uv run python -m json.tool
Satıcının özellikleri, MCP uç nokta URL'si, ödeme işleyicileri ve herkese açık anahtarı gösterilir.
8. ADK Web ile temsilciyi çalıştırma
ADK KSA'nın yerleşik Web Kullanıcı Arayüzü'nü kullanalım. Bu uzantı, tarayıcıda bir sohbet arayüzü sağlar ve araç onay istemlerini otomatik olarak işler.
Projeniz aşağıdaki gibi görünecektir:
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
Dene
İlk terminalinizde adk-agent-commerce klasörüne (agent_payments klasörünün bir üstünde) gidin ve ADK Web kullanıcı arayüzünü başlatın:
cd ~/adk-agent-commerce
uv run adk web --port 8080 --allow_origins '*'
Sunucunun http://127.0.0.1:8080 adresinde çalıştığını belirten bir çıkış görmeniz gerekir.
Temsilciyle konuşma
- URL'yi Ctrl veya Cmd tuşunu basılı tutarak tıklayarak ya da Web Önizlemesi düğmesini tıklayıp 8080 bağlantı noktasında önizle'yi seçerek ADK Web kullanıcı arayüzünü açın.
- Henüz seçili değilse açılır menüden
agent_paymentssimgesini seçin. Bir sohbet arayüzü görürsünüz. - "Hangi filmler gösteriliyor?" diye sormayı deneyin.
- Aracı, perde arkasında tiyatroları keşfedip kataloglarda arama yaparak sonuçları UCP üzerinden her iki satıcıdan da toplar.
- Bilet rezervasyonu yapmasını isteyin: "Oppenheimer için saat 19:00'a 2 bilet ayırt".
- Temsilci
complete_purchasenumarasına aramayı denediğinde ADK Web kullanıcı arayüzünün, satın alma ayrıntılarını içeren bir onay kartı gösterdiğini fark edin. - İşlemi yetkilendirmek için karttaki Onaylandı onay kutusunu işaretleyip Gönder'i tıklayın.
- Temsilci, satın alma işlemini tamamlayıp bilet kodlarıyla birlikte sipariş onayınızı size geri gönderir.
Kamera arkasında yaşananlar:
create_checkout→ satıcı, anahtarıyla imzalanmış bir ödeme döndürdü (ap2.merchant_authorization, fiyat kilidi)complete_purchase→ satıcının imzasını doğruladı, CheckoutMandate ve PaymentMandate oluşturdu, her ikisini de SD-JWT olarak imzaladı ve satıcıya gönderdi- Satıcı, her iki yetkiyi de doğruladı ve imzalanan ödeme sayfasına yönlendirdiklerini kontrol etti → biletleri düzenledi (deneme sürümünde)
9. Temizleme
Yerel sunucuların çalışır durumda kalmasını önlemek için kaynakları temizleyin:
adk webkomutunun çalıştırıldığı terminalde, aracı sunucusunu durdurmak için Ctrl+C tuşlarına basın.merchants.pykomutunun çalıştırıldığı terminalde, sahte satıcıları durdurmak için Ctrl+C tuşlarına basın.- (İsteğe bağlı) Bu codelab için yeni bir Google Cloud projesi oluşturduysanız ve bunu silmek istiyorsanız
yerine proje kimliğini yazarak aşağıdaki komutu çalıştırın:
gcloud projects delete <YOUR_PROJECT_ID>
10. Tebrikler! 🎉
UCP ve AP2 kullanarak satıcıları keşfeden, kataloglara göz atan ve satın alma işlemlerini tamamlayan bir ADK aracısı oluşturdunuz.
Öğrendikleriniz
Bu codelab'de, güvenli ticari akışları işleyen bir ADK aracısı oluşturdunuz. Oluşturduğunuz öğelerin ve uyguladığınız temel kavramların özeti:
Oluşturduğunuz öğeler:
- UCP ve AP2 işlemlerini kapsayan 5 aracı: keşif, katalog arama, ödeme.
- AP2 yetkili imzası: satıcı tarafından imzalanan ödeme (fiyat sabitleme) + CheckoutMandate ve PaymentMandate (kullanıcı yetkilendirmesi).
- Çok satıcılı arama: Birden fazla sinemaya sorgu gönderen ve sonuçları birleştiren tek bir temsilci.
Temel Kavramlar:
Protokol | Ne işe yarar? | İşleyiş şekli |
UCP Discovery | Ajan, satıcıları ve özelliklerini bulur. |
|
UCP MCP | Ajan, kataloglara göz atar ve ödeme işlemleri oluşturur | Satıcının MCP uç noktasına yapılan JSON-RPC 2.0 çağrıları |
Satıcı yetkilendirme | Satıcı, belirtilen fiyatı sabitler. | Satıcı tarafından imzalanmış, satır öğelerini ve toplamları kapsar |
AP2 CheckoutMandate | Kullanıcı, tam ödeme işlemini onaylar | Kullanıcı tarafından imzalanır ve satıcı tarafından imzalanmış ödeme işlemi içerir. |
AP2 PaymentMandate | Kullanıcı, ödemeyi yetkilendirir. | Kullanıcı tarafından imzalanır, ödeme karmasına referans verir. |
Üretimde ne gibi farklılıklar var?
Bu codelab'de sahte veriler kullanılır. Üretimde:
- UCP keşfi, sabit kodlanmış localhost URL'lerine değil, bir kayıt defterine göre çözümlenir.
- MCP uç noktaları gerçek satıcılar tarafından barındırılır: aynı JSON-RPC 2.0 protokolü, gerçek envanter
- AP2 zorunlulukları, kullanıcının güvenilir cihazında veya güvenilir bir platform tarafından imzalanır. Başlangıçta aracı tarafından oluşturulan bir anahtarla imzalanmaz.
- İmzalama anahtarları, her tarafın UCP profilinden gelir (sahte satıcılar, her istekte aracının ortak anahtarını alır).
- Ödeme yetkilendirmesi, PaymentMandate'i doğrulayan ve kullanıcının iznini isteyen bir kimlik bilgisi sağlayıcı üzerinden yapılır.
- Ön uç, araç sonuçlarını zengin kullanıcı arayüzü (ürün ızgaraları, ödeme özetleri, onay kartları) olarak oluşturur.
Sonraki adımlar
- AP2 protokol spesifikasyonunu inceleyin ve ödeme özellikli kendi aracınızı oluşturun.
- Ajan tabanlı ticareti etkinleştirmek için satıcınızda UCP'yi uygulayın
- Çok temsilcili ticari iş akışları için AP2'yi A2A ile bağlama
- Kripto para ödemeleri için AP2 x402 uzantısı hakkında bilgi edinin.