تجارت امن با نمایندگان با AP2 و UCP

۱. مرور کلی

در این آزمایشگاه کد، شما یک عامل ADK را اجرا خواهید کرد که بلیط‌های فیلم را در چندین سینما با استفاده از دو پروتکل تجاری متن‌باز رزرو می‌کند:

  • UCP (پروتکل تجارت جهانی) : استانداردی برای نمایندگان جهت کشف فروشندگان، جستجوی کاتالوگ‌ها و مدیریت جریان‌های پرداخت.
  • AP2 (پروتکل پرداخت‌های عامل) : پروتکلی برای مجوز پرداخت امن و قابل تأیید با استفاده از دستورات امضا شده رمزنگاری شده.

اپلیکیشن آزمایشی CineAgent به دو فروشنده‌ی سینماهای آزمایشی با قابلیت‌های مختلف (انتخاب صندلی، قالب‌های تخصصی و روش‌های پرداخت) متصل می‌شود و کل فرآیند رزرو را از جستجو تا پرداخت هماهنگ می‌کند.

آنچه یاد خواهید گرفت

  • نحوه‌ی کشف تاجر UCP از طریق پروفایل‌های /.well-known/ucp چگونه است؟
  • چگونه یک نماینده ADK از UCP برای جستجوی کاتالوگ‌ها و ایجاد صندوق‌ها استفاده می‌کند
  • چگونه AP2 (CheckoutMandate، PaymentMandate) تراکنش‌های امن را الزامی می‌کند
  • نحوه عملکرد پروتکل‌های سرتاسری UCP و AP2 برای ایمن‌سازی تجارت الکترونیک عامل‌محور

آنچه نیاز دارید

  • یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب
  • یک مرورگر وب مانند کروم
  • پایتون ۳.۱۱+ و uv ، اگر کد را به جای Cloud Shell روی دستگاه خودتان اجرا کنید

این آزمایشگاه کد برای توسعه‌دهندگان سطح متوسط ​​است که با پایتون و گوگل کلود آشنایی دارند. تکمیل این آزمایشگاه کد تقریباً 30 دقیقه طول می‌کشد.

منابع ایجاد شده در این آزمایشگاه کد باید کمتر از ۵ دلار هزینه داشته باشند.

۲. درک پروتکل‌های UCP و AP2

قبل از اینکه به ساخت عامل بپردازیم، بیایید دو پروتکلی را که این تجارت عامل‌محور امن را ممکن می‌سازند، درک کنیم.

این آزمایشگاه کد از UCP نسخه 2026-08-25 به همراه UCP Python SDK و AP2 نسخه 0.2 به همراه AP2 Python SDK استفاده می‌کند.

پروتکل تجارت جهانی ( UCP )

UCP نحوه تعامل عوامل هوش مصنوعی با فروشندگان را استاندارد می‌کند. این استاندارد با معرفی یک مدل منبع استاندارد، مشکل نیاز عوامل به یادگیری APIهای سفارشی برای هر فروشگاه را حل می‌کند.

چگونه کار می‌کند:

  1. کشف : هر فروشنده‌ای که از UCP پیروی می‌کند، یک پروفایل را در یک مکان استاندارد قرار می‌دهد: /.well-known/ucp . مثال: نقطه پایانی UCP در Everlane . وقتی یک نماینده این پروفایل را می‌خواند، به دنبال موارد زیر می‌گردد:
    • قابلیت‌ها : ویژگی‌های اصلی مستقل که یک کسب‌وکار از آنها پشتیبانی می‌کند، مانند جستجو در کاتالوگ یا پرداخت.
    • سرویس‌ها : لایه‌های ارتباطی سطح پایین‌تر که برای تبادل داده‌ها استفاده می‌شوند. مثال‌ها: REST API، MCP (پروتکل زمینه مدل)، A2A (پروتکل عامل به عامل)
    • افزونه‌ها : اگر یک فروشنده به رفتار خاصی نیاز داشته باشد، می‌تواند افزونه‌های سفارشی را در این پروفایل تعریف کند.
    • کلیدها : کلیدهای امضای عمومی تاجر که کارگزاران برای بررسی امضاهای تاجر از آنها استفاده می‌کنند.
  2. عملیات : پس از کشف، عامل از نقطه پایانی سرویس ارائه شده برای انجام عملیات استفاده می‌کند. در این آزمایشگاه کد، ما از پروتکل زمینه مدل (MCP) به عنوان انتقال سرویس استفاده می‌کنیم. عامل فراخوانی‌های JSON-RPC 2.0 را به این نقطه پایانی انجام می‌دهد تا قابلیت‌های کشف شده را فراخوانی کند: جستجوی محصولات، ایجاد صندوق‌ها و تکمیل خریدها.

گردش کار UCP

پروتکل پرداخت‌های عامل ( AP2 )

AP2 نحوه‌ی تأیید پرداخت‌ها توسط نمایندگان به نمایندگی از کاربران را استانداردسازی می‌کند. این استاندارد مشکل امنیتی مربوط به مدیریت اعتبارنامه‌های حساس پرداخت توسط نمایندگان را حل می‌کند.

چگونه کار می‌کند:

  1. امضای فروشنده : وقتی یک نماینده با استفاده از پروتکل UCP یک تسویه حساب ایجاد می‌کند، فروشنده تسویه حساب (شامل ردیف اقلام و جمع کل) را امضا می‌کند و امضا را در ap2.merchant_authorization برمی‌گرداند. این به عنوان تضمین قفل قیمت عمل می‌کند. اگر فروشنده پس از امضا قیمت را تغییر دهد، امضا دیگر مطابقت ندارد.
  2. دستور پرداخت و دستور پرداخت : پس از تأیید محتوای دستور پرداخت، کاربر (یا نماینده از طرف کاربر) دو دستور را امضا می‌کند. CheckoutMandate شامل دستور پرداخت امضا شده توسط فروشنده است و به فروشنده می‌گوید که کاربر آن را تأیید کرده است. دستور PaymentMandate مبلغ پرداختی برای آن دستور پرداخت را تأیید می‌کند. هر دو به هش دستور پرداخت امضا شده اشاره دارند و حاوی امضای رمزنگاری کاربر هستند.
  3. تأیید امضا : فروشنده هر دو دستور را دریافت می‌کند. امضای کاربر را در CheckoutMandate تأیید می‌کند و بررسی می‌کند که آیا صندوق داخل آن امضای خود فروشنده را دارد یا خیر. PaymentMandate به سمت پرداخت (ارائه‌دهنده اعتبار یا پردازنده پرداخت) می‌رود که قبل از انتقال هرگونه وجه، آن را تأیید می‌کند. اگر همه چیز معتبر باشد، تراکنش ادامه می‌یابد.

این سیستم «قفل دوگانه» تضمین می‌کند که فروشندگان نمی‌توانند بیش از حد هزینه دریافت کنند و نمایندگان نمی‌توانند بدون مجوز هزینه کنند. مجوزها، اعتبارنامه‌های SD-JWT (افشای انتخابی JWT) هستند که با آشکار کردن فقط فیلدهایی که هر طرف نیاز دارد، از حریم خصوصی کاربر محافظت می‌کنند. در AP2 نسخه 0.2، CheckoutMandate جایگزین CartMandate از AP2 نسخه 0.1 شده است.

گردش کار AP2

۳. محیط خود را آماده کنید

راه‌اندازی پروژه گوگل کلود

ایجاد یک پروژه ابری گوگل

  1. در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .
  2. مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

شروع پوسته ابری

Cloud Shell یک محیط خط فرمان است که در Google Cloud اجرا می‌شود و ابزارهای لازم از قبل روی آن بارگذاری شده‌اند.

  1. روی فعال کردن Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
  2. پس از اتصال به Cloud Shell، احراز هویت خود را تأیید کنید:
    gcloud auth list
    
  3. تأیید کنید که پروژه شما پیکربندی شده است:
    gcloud config get project
    
  4. اگر پروژه شما مطابق انتظار تنظیم نشده است، آن را تنظیم کنید:
    export PROJECT_ID=<YOUR_PROJECT_ID>
    gcloud config set project $PROJECT_ID
    

فعال کردن APIها

برای فعال کردن API های مورد نیاز، دستور زیر را اجرا کنید:

gcloud services enable aiplatform.googleapis.com

ساختار دایرکتوری راه‌اندازی

دستورات زیر را کپی و پیست کنید تا یک پوشه برای این codelab ایجاد شود، که پوشه agent_payments درون آن برای کد agent قرار دارد:

mkdir -p ~/adk-agent-commerce/agent_payments
cd ~/adk-agent-commerce

به مدل‌های Gemini دسترسی پیدا کنید

دستور زیر را کپی و پیست کنید تا agent_payments/.env را با پروژه و موقعیت مکانی خود ایجاد کنید و ADK از طریق پروژه Google Cloud شما Gemini را فراخوانی کند. Cine Agent از Gemini برای تصمیم‌گیری در مورد ابزارهایی که باید فراخوانی شوند استفاده می‌کند. ADK این فایل را به طور خودکار بارگذاری می‌کند، بنابراین تنظیمات در ترمینال‌های جدید نیز کار می‌کنند.

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

نصب وابستگی‌ها

پوسته ابری گوگل (Google Cloud Shell) به صورت پیش‌فرض با uv برای مدیریت محیط و وابستگی‌ها نصب شده است.

  1. یک فایل pyproject.toml در ریشه پوشه adk-agent-commerce خود ایجاد کنید و محتوای زیر را به آن اضافه کنید. این فایل، متادیتا و وابستگی‌های پروژه را تعریف می‌کند.
[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",
]

SDK مربوط به AP2 از مخزن گیت‌هاب آن نصب می‌شود زیرا هنوز در PyPI منتشر نشده است. (بسته‌ی ap2 در PyPI یک پروژه‌ی نامرتبط است.)

  1. دستور زیر را برای ایجاد محیط مجازی و نصب تمام وابستگی‌ها اجرا کنید:
uv sync

uv یک محیط پایتون ایزوله برای این codelab ایجاد می‌کند، بنابراین نیازی به فعال کردن چیزی ندارید. دستورات پایتون را با uv run شروع کنید.

۴. عامل را تعریف کنید

قبل از نوشتن هرگونه منطق ابزار، بیایید خود عامل را در فایلی به نام agent.py تعریف کنیم. این عامل به عنوان هماهنگ‌کننده جریان رزرو فیلم عمل خواهد کرد.

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),
    ],
)

توضیح کد

بیایید آنچه را که در این تعریف عامل اتفاق می‌افتد، تجزیه و تحلیل کنیم:

  • model=Gemini(...) : ما از Gemini 3.8 Flash برای استدلال و استفاده از ابزار استفاده می‌کنیم.
  • instruction : این دستورالعملی است که رفتار عامل را هدایت می‌کند. این دستورالعمل به صراحت به عامل می‌گوید که از UCP و AP2 استفاده کند، ابزارهای موجود را فهرست می‌کند و قوانین مهمی مانند «هرگز داده‌ها را اختراع نکنید» و «قیمت‌ها به سنت هستند» را تعیین می‌کند.
  • tools : این لیستی از توابع پایتون (که در ادامه خواهیم ساخت) است که عامل می‌تواند بر اساس درخواست‌های کاربر، آنها را فراخوانی کند.
  • require_confirmation : می‌توانید هر ابزاری را با FunctionTool(my_function,require_confirmation=True) پوشش دهید. وقتی فعال می‌شود، عامل مکث می‌کند و قبل از اجرای ابزار، منتظر یک تأیید ساده "بله" یا "خیر" می‌ماند. در اینجا، قبل از اجرای ابزار complete_purchase ، عامل برای تأیید انسانی مکث می‌کند.

فهرست ابزارها

تعریف عامل، آنچه را که باید بسازیم، اعلام می‌کند. هر ابزار به یک عملیات خاص در پروتکل UCP یا AP2 نگاشت می‌شود:

ابزار

چه کاری انجام می‌دهد؟

اقدام پروتکلی

discover_theaters

یافتن بازرگانان و قابلیت‌های آنها

کوئری‌های /.well-known/ucp

search_movies

جستجوی کاتالوگ‌ها در بین فروشگاه‌ها

JSON-RPC به نقطه پایانی MCP

get_movie_detail

دریافت زمان‌های نمایش در یک فروشگاه خاص

JSON-RPC به نقطه پایانی MCP

create_checkout

شروع جلسه تسویه حساب

JSON-RPC به نقطه پایانی MCP

complete_purchase

پرداخت را تأیید کنید و سفارش را تکمیل کنید

احکام AP2 را امضا و به MCP ارسال می‌کند

مدل Gemini بر اساس مکالمه تصمیم می‌گیرد که چه زمانی هر ابزار را فراخوانی کند . کار بعدی ما پیاده‌سازی عملکرد هر ابزار در tools.py است.

۵. ابزارهای عامل را بسازید: کشف و مرور

حالا بیایید ابزارهایی را که عامل برای مرور و کشف فیلم‌ها استفاده خواهد کرد، پیاده‌سازی کنیم. هر ابزار یک عملیات UCP را در بر می‌گیرد.

یک فایل جدید به نام agent_payments/tools.py ایجاد کنید و کد زیر را کپی و در آن پیست کنید:

"""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])

درک تنظیمات

برای اینکه این کدنویسی روی ساخت عامل متمرکز بماند، از دو کلاس کمکی UCPClient و AP2Handler استفاده می‌کنیم که در مرحله بعدی به آنها خواهیم پرداخت.

  • آنها چیستند؟ : آنها کلاس‌های کمکی کوچکی هستند که ما برای این آزمایشگاه کد نوشتیم تا با بازرگانان ساختگی صحبت کنند. SDK های رسمی قطعات پروتکل را ارائه می‌دهند: UCP SDK دارای مدل‌های داده برای هر طرح UCP است و AP2 SDK دستورات امضا شده را ایجاد و تأیید می‌کند. هیچ یک از SDK ها شامل کلاینتی برای فراخوانی بازرگانان نیستند، بنابراین این helper ها آن بخش را مدیریت می‌کنند.
  • فعلاً، با آنها به عنوان اشیاء کمکی رفتار کنید :
    • _ucp.discover(url) : نمایه یک فروشنده را دریافت و اعتبارسنجی می‌کند.
    • _ucp.mcp_call(url, method, params) : یک درخواست JSON-RPC 2.0 به نقطه پایانی MCP فروشنده ارسال می‌کند.

تئاترها را کشف کنید

این ابزار اولین قدم در جریان UCP است. این ابزار مشخص می‌کند که چه فروشندگانی وجود دارند و از چه چیزهایی پشتیبانی می‌کنند.

به 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)

این چه کاری انجام می‌دهد :

  1. این کد، فهرستی از آدرس‌های اینترنتی فروشگاه‌های ارائه شده توسط سرور را مرور می‌کند. در این آزمایشگاه کد، در بخش بعدی دو فروشگاه آزمایشی راه‌اندازی خواهیم کرد.
  2. برای هر URL، تابع _ucp.discover(url) را فراخوانی می‌کند که به نقطه پایانی /.well-known/ucp برخورد می‌کند.
  3. این برنامه نام، قابلیت‌ها و گردانندگان پرداخت را در یک لیست خلاصه جمع‌آوری می‌کند.
  4. این لیست را به عنوان یک رشته JSON برای خواندن توسط عامل برمی‌گرداند.

جستجوی فیلم‌ها

این ابزار در تمام فروشگاه‌های کشف‌شده جستجو می‌کند و نتایج را ادغام می‌کند. این امر بسیار مهم است زیرا ممکن است یک فیلم در چندین سینما با فرمت‌های مختلف (IMAX، Dolby) و قیمت‌های مختلف پخش شود.

به 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)

این چه کاری انجام می‌دهد :

  1. این حلقه تمام تئاترهایی را که کشف شده‌اند، طی می‌کند.
  2. این یک درخواست JSON-RPC کاتالوگ جستجو ( _ucp.mcp_call(url, "search_catalog", {"catalog": {"query": query}}) ) را به نقطه پایانی MCP فروشنده ارسال می‌کند.
  3. سپس کمی پاکسازی انجام می‌دهد تا نتایج را تجزیه کند و فیلم‌ها و «انواع» آنها (که نشان‌دهنده زمان نمایش و فرمت‌های خاص هستند) را پیدا کند. فیلم‌ها را بر اساس شناسه گروه‌بندی می‌کند تا کاربر ورودی‌های تکراری فیلم را نبیند.

جزئیات فیلم را دریافت کنید

این ابزار جزئیات کامل کاتالوگ یک فیلم خاص را در یک سینمای خاص دریافت می‌کند.

به 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)

این چه کاری انجام می‌دهد :

  • این متد، متد lookup_catalog را در نقطه پایانی MCP فروشنده فراخوانی می‌کند و movie_id خاص را در catalog.ids ارسال می‌کند. این متد اطلاعات دقیقی مانند زمان نمایش‌ها و در دسترس بودن صندلی برای آن سینمای خاص را برمی‌گرداند.

۶. ابزارهای نمایندگی را بسازید: پرداخت و تسویه حساب

این ابزارها جریان پرداخت و خرید را مدیریت می‌کنند. اینجاست که پروتکل AP2 برای تضمین تراکنش‌های امن وارد عمل می‌شود.

ایجاد پرداخت

این ابزار یک جلسه تسویه حساب را در یک سینمای خاص برای یک زمان نمایش مشخص آغاز می‌کند.

به 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)

این چه کاری انجام می‌دهد :

  1. این متد create_checkout را در نقطه پایانی MCP فروشنده فراخوانی می‌کند.
  2. این تابع showtime_id و quantity درخواستی کاربر را ارسال می‌کند.
  3. فروشنده، رسیدی را که با کلید فروشنده امضا شده بود، برمی‌گرداند.

توجه : اگر داده‌های پاسخ را بررسی کنید، فیلد ap2.merchant_authorization حاوی امضای رمزنگاری‌شده‌ی فروشنده روی صفحه‌ی پرداخت است که قیمت اعلام‌شده را قفل می‌کند. آن‌ها نمی‌توانند بعداً آن را تغییر دهند!

خرید کامل

سه اتفاق در این ابزار رخ می‌دهد:

  1. ما رسید پرداخت را دریافت می‌کنیم و امضای فروشنده را روی آن تأیید می‌کنیم.
  2. با استفاده از AP2 SDK، فرم‌های CheckoutMandate و PaymentMandate را ایجاد و امضا کنید.
  3. هر دو دستور را برای تکمیل خرید به فروشنده ارسال کنید.

به 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)

چرا دو دستور؟ دستور پرداخت (CheckoutMandate) به فروشنده ثابت می‌کند که کاربر دقیقاً همین پرداخت را با قیمتی که فروشنده امضا کرده، تأیید کرده است. دستور پرداخت (PaymentMandate) به طرف پرداخت ثابت می‌کند که کاربر این هزینه را مجاز دانسته است. روند کار به این صورت است:

Merchant signs checkout -> User signs mandates -> Merchant and payment side verify -> Order completes .

نقطه بازرسی: tools.py کامل.py

فایل کامل tools.py شما اکنون باید شامل ۵ تابع ابزار و مقداردهی اولیه در سطح ماژول برای کلاینت‌های UCP و AP2 باشد. بررسی کنید که به شکل زیر باشد:

"""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)

۷. آن را قابل اجرا کنید

با فروشندگان واقعی UCP، شما آدرس URL آنها را به نماینده نشان می‌دهید و کار تمام است. برای این آزمایشگاه کد، ما به دو چیز برای آزمایش محلی نیاز داریم:

  1. بازرگانان ساختگی : سرورهای محلی که نقاط پایانی UCP را شبیه‌سازی می‌کنند تا شما چیزی برای آزمایش روی آنها داشته باشید
  2. کمک‌کننده‌های پروتکل : پوشش‌های نازکی که از طریق HTTP با فروشندگان تماس می‌گیرند و از UCP و AP2 SDK برای داده‌های پروتکل و امضاها استفاده می‌کنند.

توجه : لازم نیست این کد را با دقت بخوانید. این فایل‌ها، فروشگاه‌های واقعی و کیف پول کاربر را شبیه‌سازی می‌کنند. آن‌ها را به همان شکل کپی کنید.

دستیاران پروتکل

UCP SDK مدل‌های داده را ارائه می‌دهد و AP2 SDK دستورات را امضا و تأیید می‌کند، اما هیچ‌کدام شامل کلاینتی برای ارتباط با فروشندگان نیستند. این دو فایل این خلا را پر می‌کنند. آن‌ها ucp_client.py و ap2_handler.py نام دارند، بنابراین بسته ap2 را در سایه قرار نمی‌دهند.

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()

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),
        )

بازرگانان قلابی

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

این دو سرور FastAPI ایجاد می‌کند که هر کدام دو نقطه پایانی دارند:

  • GET /.well-known/ucp : کشف UCP. قابلیت‌های فروشنده، URL نقطه پایانی MCP، روش‌های پرداخت پذیرفته‌شده و کلید امضای عمومی را برمی‌گرداند.
  • POST /mcp : عملیات MCP (پروتکل زمینه مدل). فراخوانی‌های JSON-RPC 2.0 را برای جستجوی کاتالوگ، پرداخت و پرداخت مدیریت می‌کند.

هر فروشنده، رسیدهای خود را با کلید خود امضا می‌کند، قبل از تکمیل سفارش، الزامات AP2 را تأیید می‌کند و هر پاسخ را با مدل‌های UCP SDK مقایسه می‌کند.

فروشندگان را در یک ترمینال جدید شروع کنید (آنها باید در حال اجرا بمانند):

cd ~/adk-agent-commerce
uv run python agent_payments/merchants.py

شما باید ببینید:

Merchants running: Meridian (:8081), StarLight (:8082)

در ترمینال اول خود، کشف UCP را تأیید کنید:

curl -s http://localhost:8081/.well-known/ucp | uv run python -m json.tool

شما باید قابلیت‌های فروشنده، URL نقطه پایانی MCP، کنترل‌کننده‌های پرداخت و کلید عمومی را ببینید.

۸. اجرای Agent با ADK Web

بیایید از رابط کاربری وب داخلی ADK CLI استفاده کنیم! این رابط کاربری یک چت در مرورگر فراهم می‌کند و به طور خودکار درخواست‌های تأیید ابزار را مدیریت می‌کند.

پروژه شما اکنون باید به این شکل باشد:

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

امتحانش کن

در اولین ترمینال خود، به پوشه adk-agent-commerce (یک پوشه بالاتر از agent_payments ) بروید و رابط کاربری وب ADK را اجرا کنید:

cd ~/adk-agent-commerce
uv run adk web --port 8080 --allow_origins '*'

باید خروجی را ببینید که نشان می‌دهد سرور در http://127.0.0.1:8080 در حال اجرا است.

با نماینده صحبت کنید

  1. رابط کاربری وب ADK را با فشردن کلیدهای Ctrl یا Cmd و کلیک روی URL، یا با کلیک روی دکمه پیش‌نمایش وب و انتخاب پیش‌نمایش روی پورت ۸۰۸۰، باز کنید.
  2. اگر از قبل انتخاب نشده است، از منوی کشویی، agent_payments انتخاب کنید. یک رابط چت مشاهده خواهید کرد.
  3. سعی کنید بپرسید: «چه فیلم‌هایی در حال پخش هستند؟»
  4. این نماینده، سینماها را کشف کرده و کاتالوگ‌های پشت صحنه را جستجو می‌کند و نتایج هر دو فروشنده را از طریق UCP جمع‌آوری می‌کند.
  5. برای رزرو بلیط بپرسید: «برای ساعت ۷ بعد از ظهر، ۲ بلیط برای اوپنهایمر رزرو کنید» .
  6. وقتی اپراتور سعی می‌کند تابع complete_purchase فراخوانی کند، توجه کنید که رابط کاربری وب ADK چگونه یک کارت تأیید با جزئیات خرید نشان می‌دهد!
  7. برای تأیید تراکنش، کادر تأیید شده روی کارت را علامت بزنید و روی ارسال کلیک کنید.
  8. نماینده خرید را تکمیل کرده و تأیید سفارش شما را به همراه کدهای بلیط برمی‌گرداند!

در پشت صحنه چه اتفاقی افتاد:

  1. create_checkout → فروشنده یک رسید پرداخت امضا شده با کلید آن ( ap2.merchant_authorization ، قفل قیمت) را برگرداند.
  2. complete_purchase → امضای فروشنده را تأیید کرد، یک CheckoutMandate و یک PaymentMandate ایجاد کرد که هر دو به عنوان SD-JWT امضا شده بودند و آنها را برای فروشنده ارسال کرد.
  3. فروشنده هر دو دستور را تأیید کرد و بررسی کرد که آیا آنها به صندوقی که امضا کرده اشاره می‌کنند یا خیر → بلیط‌های صادر شده (در شبیه‌سازی)

۹. تمیز کردن

برای جلوگیری از اجرای سرورهای محلی، منابع را پاک کنید:

  1. در ترمینالی که adk web در حال اجرا است، کلیدهای Ctrl+C را فشار دهید تا سرور عامل متوقف شود.
  2. در ترمینالی که merchants.py در حال اجرا است، کلیدهای Ctrl+C را فشار دهید تا نمایش merchantهای ساختگی متوقف شود.
  3. (اختیاری) اگر یک پروژه جدید Google Cloud برای این آزمایشگاه کد ایجاد کرده‌اید و می‌خواهید آن را حذف کنید، دستور زیر را اجرا کنید و عبارت زیر را جایگزین کنید: با شناسه پروژه آن:
gcloud projects delete <YOUR_PROJECT_ID>

۱۰. تبریک می‌گویم! 🎉

شما یک عامل ADK ساختید که فروشندگان را کشف می‌کند، کاتالوگ‌ها را مرور می‌کند و با استفاده از UCP و AP2 خریدها را تکمیل می‌کند.

آنچه آموختید

در این آزمایشگاه کد، شما یک عامل ADK ساختید که جریان‌های تجاری امن را مدیریت می‌کند. در اینجا خلاصه‌ای از آنچه ساختید و مفاهیم کلیدی که به کار بردید، آمده است:

چیزی که ساختی:

  • ۵ ابزار عامل که عملیات UCP و AP2 را پوشش می‌دهند: کشف، جستجوی کاتالوگ، پرداخت، پرداخت.
  • امضای دستور AP2 : پرداخت امضا شده توسط فروشنده (قفل قیمت) + دستور پرداخت و دستور پرداخت (مجوز کاربر).
  • جستجوی چند فروشنده : یک نماینده چندین سینما را جستجو می‌کند و نتایج را ادغام می‌کند.

مفاهیم کلیدی:

پروتکل

چه کاری انجام می‌دهد؟

چگونه کار می‌کند؟

کشف UCP

نماینده، بازرگانان و قابلیت‌های آنها را پیدا می‌کند

/.well-known/ucp → قابلیت‌ها، نقطه پایانی MCP، روش‌های پرداخت، کلیدها

UCP MCP

نماینده کاتالوگ‌ها را مرور می‌کند، صندوق‌ها را ایجاد می‌کند

فراخوانی‌های JSON-RPC 2.0 به نقطه پایانی MCP فروشنده

مجوز فروشنده

فروشنده قیمت اعلام شده را قفل می‌کند

امضا شده توسط تاجر، شامل اقلام ردیف + جمع کل

AP2 CheckoutManagement

کاربر پرداخت دقیق را تأیید می‌کند

توسط کاربر امضا شده، حاوی رسید پرداخت امضا شده توسط فروشنده است

دستور پرداخت AP2

کاربر هزینه را تأیید می‌کند

توسط کاربر امضا شده است، به هش پرداخت ارجاع می‌دهد

چه تفاوتی در تولید وجود دارد؟

این آزمایشگاه کد از mockها استفاده می‌کند. در مرحله‌ی تولید:

  • کشف UCP در برابر یک رجیستری، نه URL های محلی میزبان کدگذاری شده، پاسخ می‌دهد.
  • نقاط پایانی MCP توسط بازرگانان واقعی میزبانی می‌شوند: همان پروتکل JSON-RPC 2.0، موجودی واقعی
  • دستورات AP2 روی دستگاه مورد اعتماد کاربر یا توسط یک پلتفرم مورد اعتماد امضا می‌شوند، نه با کلیدی که عامل در هنگام راه‌اندازی تولید می‌کند.
  • کلیدهای امضا از پروفایل UCP هر طرف می‌آیند (فروشندگان ساختگی در هر درخواست، کلید عمومی نماینده را دریافت می‌کنند)
  • مجوز پرداخت از طریق یک ارائه‌دهنده اعتبارنامه انجام می‌شود که PaymentMandate را تأیید کرده و رضایت کاربر را جویا می‌شود.
  • فرانت‌اند نتایج ابزار را به صورت رابط کاربری غنی (شبکه‌های محصول، خلاصه‌های پرداخت، کارت‌های تأیید) ارائه می‌دهد.

مراحل بعدی

اسناد مرجع