تأمين التجارة باستخدام "الوكيل الآمن" من خلال AP2 وبروتوكول UCP

1. نظرة عامة

في هذا الدرس التطبيقي حول الترميز، ستشغّل وكيلاً ADK يحجز تذاكر سينما لدى عدة تجّار باستخدام بروتوكولَي تجارة مفتوحَي المصدر:

  • بروتوكول Universal Commerce Protocol ‏ (UCP): هو معيار يتيح للوكلاء العثور على التجّار والبحث في الكتالوجات وإدارة عمليات الدفع.
  • ‫AP2 (بروتوكول دفع الوكيل): هو بروتوكول لتفويض الدفع الآمن الذي يمكن التحقّق منه باستخدام تفويضات موقّعة بالتشفير.

يربط التطبيق التجريبي، CineAgent، بين تاجرَين وهميَّين لبيع تذاكر السينما لديهما إمكانات مختلفة (اختيار المقاعد، والتنسيقات المتخصصة، وطُرق الدفع) وينسّق عملية الحجز الكاملة من البحث إلى الدفع.

أهداف الدورة التعليمية

  • طريقة عمل ميزة "استكشاف التاجر" في بروتوكول UCP من خلال /.well-known/ucp الملفات الشخصية
  • كيف يستخدم وكيل ADK بروتوكول UCP للبحث في الكتالوجات وإنشاء عمليات دفع
  • كيف تضمن تفويضات AP2 (CheckoutMandate وPaymentMandate) أمان المعاملات؟
  • طريقة عمل بروتوكولَي UCP وAP2 للتشفير التام بين الأطراف من أجل تأمين التجارة الإلكترونية بالذكاء الاصطناعي الوكيل

المتطلبات

  • مشروع Google Cloud تم تفعيل الفوترة فيه
  • متصفّح ويب، مثل Chrome
  • ‫Python 3.11 والإصدارات الأحدث وuv، إذا كنت تنفّذ الرمز البرمجي على جهازك بدلاً من Cloud Shell

هذا الدرس التطبيقي حول الترميز مخصّص للمطوّرين المتوسطي الخبرة الذين لديهم بعض المعرفة بلغة Python وGoogle Cloud. يستغرق إكمال هذا الدرس العملي حوالي 30 دقيقة.

يجب أن تكون تكلفة الموارد التي تم إنشاؤها في هذا الدرس التطبيقي حول الترميز أقل من 5 دولارات أمريكية.

2. التعرّف على بروتوكولَي UCP وAP2

قبل أن نبدأ في إنشاء الوكيل، دعونا نتعرّف على البروتوكولَين اللذين يتيحان هذه التجارة الآمنة المستندة إلى الوكلاء.

يستخدم هذا الدرس التطبيقي حول الترميز الإصدار 2026-08-25 من UCP مع حزمة تطوير البرامج (SDK) للغة Python من UCP، والإصدار 0.2 من AP2 مع حزمة تطوير البرامج (SDK) للغة Python من AP2.

بروتوكول Universal Commerce Protocol‏ (UCP)

يضع بروتوكول UCP معايير موحّدة لطريقة تفاعل وكلاء الذكاء الاصطناعي مع التجّار. يحلّ هذا الإطار مشكلة اضطرار الوكلاء إلى تعلُّم واجهات برمجة تطبيقات مخصّصة لكل متجر من خلال تقديم نموذج موارد موحّد.

طريقة العمل:

  1. الاكتشاف: يعرض كل تاجر متوافق مع UCP ملفًا شخصيًا في موقع عادي: /.well-known/ucp. مثال: نقطة نهاية UCP في Everlane.عندما يقرأ وكيل هذا الملف الشخصي، يبحث عن:
    • الإمكانات: الميزات الأساسية المستقلة التي يوفّرها النشاط التجاري، مثل البحث في الكتالوج أو الدفع
    • الخدمات: طبقات الاتصال ذات المستوى الأدنى المستخدَمة لتبادل البيانات أمثلة: REST API، وMCP (بروتوكول سياق النموذج)، وA2A (بروتوكول Agent2Agent).
    • الإضافات: إذا كان التاجر بحاجة إلى سلوك متخصص، يمكنه تحديد الإضافات المخصّصة في هذا الملف.
    • المفاتيح: مفاتيح التوقيع العامة الخاصة بالتاجر، والتي تستخدمها البرامج للتحقّق من تواقيع التاجر.
  2. العمليات: بعد اكتشاف نقطة النهاية، يستخدم الوكيل نقطة نهاية الخدمة المقدَّمة لتنفيذ العمليات. في هذا الدرس التطبيقي حول الترميز، نستخدم بروتوكول سياق النموذج (MCP) لنقل البيانات بين الخدمات. يُجري الوكيل طلبات JSON-RPC 2.0 إلى نقطة النهاية هذه لاستدعاء الإمكانات التي تم اكتشافها، مثل البحث عن المنتجات وإنشاء عمليات دفع وإكمال عمليات الشراء.

سير عمل UCP

بروتوكول دفعات الوكلاء (AP2)

يضع AP2 معيارًا موحّدًا لكيفية تفويض الوكلاء لإجراء عمليات الدفع نيابةً عن المستخدمين. يحلّ هذا الخيار مشكلة الأمان المتعلّقة بتعامل الموظفين مع بيانات اعتماد الدفع الحسّاسة.

طريقة العمل:

  1. توقيع التاجر: عندما ينشئ وكيل عملية دفع باستخدام بروتوكول UCP، يوقّع التاجر على عملية الدفع (بنود الطلب والمبالغ الإجمالية) ويعيد التوقيع في ap2.merchant_authorization. وهي تعمل كضمان لتثبيت السعر. إذا غيّر التاجر السعر بعد التوقيع، لن تتطابق التوقيعات بعد ذلك.
  2. تفويض الدفع عند إتمام عملية الشراء وتفويض الدفع: بعد التحقّق من محتوى عملية الشراء، يوقّع المستخدم (أو الوكيل بالنيابة عن المستخدم) تفويضَين. يحتوي CheckoutMandate على عملية الدفع الموقّعة من التاجر ويُعلم التاجر بأنّ المستخدم وافق عليها. يوافق PaymentMandate على مبلغ الدفع لعملية الدفع هذه. يشير كل منهما إلى تجزئة لعملية الدفع الموقَّعة ويتضمّن التوقيع المشفر للمستخدم.
  3. التحقّق من التوقيع: يتلقّى التاجر كلا التفويضين. يتحقّق من توقيع المستخدم على CheckoutMandate ويتأكّد من أنّ عملية الدفع داخلها تحمل توقيع التاجر. تنتقل PaymentMandate إلى جهة الدفع (مقدّم بيانات اعتماد أو معالج دفع)، والتي تتحقّق منها قبل تحويل أي أموال. إذا كانت كل المعلومات صالحة، ستتم المعاملة.

يضمن نظام "القفل المزدوج" هذا ألا يفرض التجّار رسومًا مفرطة وألا ينفق الوكلاء بدون إذن. التفويضات هي بيانات اعتماد SD-JWT (Selective Disclosure JWT)، التي تحمي خصوصية المستخدم من خلال الكشف فقط عن الحقول التي يحتاجها كل طرف. في الإصدار 0.2 من AP2، يحلّ CheckoutMandate محلّ CartMandate من الإصدار 0.1 من AP2.

سير عمل AP2

3- إعداد البيئة

إعداد مشروع Google Cloud

إنشاء مشروع على Google Cloud

  1. في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على السحابة الإلكترونية أو أنشِئ مشروعًا على السحابة الإلكترونية.
  2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع

بدء Cloud Shell

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
    

تفعيل واجهات برمجة التطبيقات

نفِّذ الأمر التالي لتفعيل واجهات برمجة التطبيقات المطلوبة:

gcloud services enable aiplatform.googleapis.com

إعداد بنية الدليل

انسخ الأوامر التالية والصِقها لإنشاء مجلد لهذا الدرس التطبيقي حول الترميز، مع مجلد agent_payments بداخله لرمز الوكيل:

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

استخدام نماذج Gemini

انسخ الأمر التالي والصقه لإنشاء agent_payments/.env باستخدام مشروعك وموقعك الجغرافي، ولتطلب من ADK التواصل مع Gemini من خلال مشروعك على Google Cloud. يستخدم Cine Agent Gemini لتحديد الأدوات التي يجب استدعاؤها. يحمّل "حزمة تطوير تطبيقات Android" هذا الملف تلقائيًا، لذا تعمل الإعدادات أيضًا في المحطات الطرفية الجديدة.

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

تثبيت الحِزم التابعة

يتم تثبيت uv مسبقًا في Google Cloud Shell لإدارة البيئة والملحقات.

  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 من مستودع GitHub لأنّها لم تُنشر على PyPI بعد. (الحزمة ap2 على PyPI هي مشروع غير ذي صلة).

  1. نفِّذ الأمر التالي لإنشاء البيئة الافتراضية وتثبيت جميع الاعتماديات:
uv sync

تنشئ uv بيئة Python معزولة لهذا الدرس التطبيقي حول الترميز، لذا لن تحتاج إلى تفعيل أي شيء. ابدأ أوامر Python بالرمز uv run.

4. تحديد الوكيل

قبل كتابة أي منطق للأداة، لنحدّد الوكيل نفسه في ملف باسم 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: هذه قائمة بدوال Python (التي سننشئها لاحقًا) يمكن للوكيل اختيار استدعائها استنادًا إلى طلبات المستخدم.
  • ‫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.

5- إنشاء أدوات الوكيل: الاستكشاف والتصفّح

لننفّذ الآن الأدوات التي سيستخدمها الوكيل لتصفّح الأفلام واكتشافها. تغلف كل أداة عملية 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 الرسمية أجزاء البروتوكول: تحتوي حزمة تطوير البرامج (SDK) لبروتوكول UCP على نماذج بيانات لكل مخطط UCP، وتنشئ حزمة تطوير البرامج (SDK) لبروتوكول AP2 تفويضات موقَّعة وتتحقّق منها. لا تتضمّن أيّ من حزمتَي SDK برنامجًا للعميل لإجراء مكالمات مع التجّار، لذا تتولّى هذه الأدوات المساعدة هذا الجزء.
  • في الوقت الحالي، يمكنك التعامل معها كعناصر مساعدة:
    • ‫_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. تتكرّر هذه العملية على قائمة بعناوين URL الخاصة بالتجّار يقدّمها الخادم. في هذا الدرس التطبيقي، سنعدّ متجرَين وهميَّين في القسم التالي.
  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. تعرض هذه الطريقة معلومات مفصّلة، مثل أوقات العرض وتوفّر المقاعد في قاعة السينما المحدّدة.

6. إنشاء أدوات الوكيل: الدفع

تتولّى هذه الأدوات عملية الدفع والشراء. وهنا يأتي دور بروتوكول 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. أنشئ CheckoutMandate وPaymentMandate ووقِّعهما باستخدام حزمة تطوير البرامج (SDK) الخاصة بمنصة AP2.
  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

يجب أن يحتوي tools.py الكامل الآن على 5 وظائف أدوات وإعداد على مستوى الوحدة لبرامج 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)

7. إتاحة إمكانية تشغيلها

مع التجّار الحقيقيين في "بروتوكول UCP"، يمكنك توجيه الوكيل إلى عناوين URL الخاصة بهم، وبذلك تكون قد انتهيت. في هذا الدرس التطبيقي حول الترميز، نحتاج إلى عنصرَين لاختبار التطبيق على الجهاز المحلي:

  1. التجّار الوهميون: خوادم محلية تحاكي نقاط نهاية UCP لتوفير عناصر يمكنك اختبارها
  2. أدوات مساعدة البروتوكول: أغلفة بسيطة تتواصل مع التجّار عبر HTTP وتستخدم حِزم تطوير البرامج (SDK) الخاصة ببروتوكولَي UCP وAP2 للحصول على بيانات البروتوكول والتواقيع

ملاحظة: لست بحاجة إلى قراءة هذا الرمز بعناية. تحاكي هذه الملفات التجّار الحقيقيين ومحفظة المستخدم. نسخها كما هي

تطبيقات مساعدة للبروتوكولات

تقدّم حزمة تطوير البرامج (SDK) لمنصة UCP نماذج البيانات، وتوقّع حزمة تطوير البرامج (SDK) لمنصة AP2 التفويضات وتتحقّق منها، ولكن لا تتضمّن أيّ منهما برنامجًا للعملاء للتواصل مع التجّار. ويعمل هذان الملفان على سدّ هذه الفجوة. تمت تسميتهما 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 قبل إكمال الطلب، ويراجع كل ردّ مقابل نماذج حزمة تطوير البرامج (SDK) الخاصة بمنصة UCP.

ابدأ التجار في نافذة طرفية جديدة (يجب أن يظلوا يعملون):

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 وخدمات معالجة الدفعات والمفتاح العام.

8. تشغيل الوكيل باستخدام ADK Web

لنستخدِم واجهة مستخدم الويب المضمّنة في واجهة سطر الأوامر (CLI) الخاصة بـ ADK. يوفّر ذلك واجهة محادثة في المتصفّح ويتعامل تلقائيًا مع طلبات تأكيد الأدوات.

يجب أن يبدو مشروعك الآن على النحو التالي:

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 من خلال النقر على عنوان URL مع الضغط على Ctrl أو Cmd، أو من خلال النقر على الزر معاينة الويب واختيار المعاينة على المنفذ 8080.
  2. انقر على agent_payments من القائمة المنسدلة إذا لم يكن محدّدًا. ستظهر لك واجهة محادثة.
  3. جرِّب طرح السؤال: "ما هي الأفلام التي يتم عرضها؟"
  4. سيكتشف الوكيل دور السينما ويبحث في الكتالوجات وراء الكواليس، ويجمع النتائج من كلا التجّار عبر بروتوكول UCP.
  5. اطلب حجز تذاكر: "أريد حجز تذكرتَين لفيلم Oppenheimer في الساعة 7 مساءً".
  6. عندما يحاول الوكيل الاتصال بـ complete_purchase، لاحظ كيف تعرض واجهة مستخدم الويب في "حزمة تطوير التطبيقات" بطاقة تأكيد تتضمّن تفاصيل عملية الشراء.
  7. للسماح بإجراء المعاملة، ضَع علامة في مربّع الاختيار تم التأكيد على البطاقة وانقر على إرسال.
  8. سيكمل الموظف عملية الشراء وسيرسل إليك تأكيد الطلب مع رموز التذاكر.

إليك ما حدث وراء الكواليس:

  1. create_checkout → ردّ التاجر على عملية الدفع الموقّعة بمفتاحه (ap2.merchant_authorization، أي قفل السعر)
  2. complete_purchase → تم التحقّق من توقيع التاجر، وتم إنشاء CheckoutMandate وPaymentMandate، وتم التوقيع على كليهما كرموز SD-JWT، وتم إرسالهما إلى التاجر
  3. تحقّق التاجر من كلا التفويضَين وتأكّد من أنّهما يشيران إلى عملية الدفع التي تم التوقيع عليها → تم إصدار التذاكر (في النموذج التجريبي)

9. تَنظيم

لتجنُّب ترك الخوادم المحلية قيد التشغيل، عليك تنظيف الموارد باتّباع الخطوات التالية:

  1. في نافذة الوحدة الطرفية التي يتم فيها تشغيل adk web، اضغط على Ctrl+C لإيقاف خادم الوكيل.
  2. في نافذة الوحدة الطرفية التي يتم فيها تشغيل merchants.py، اضغط على Ctrl+C لإيقاف التجار التجريبيين.
  3. (اختياري) إذا أنشأت مشروعًا جديدًا على Google Cloud لهذا الدرس العملي وأردت حذفه، نفِّذ الأمر التالي، مع استبدال برقم تعريف المشروع:
gcloud projects delete <YOUR_PROJECT_ID>

10. تهانينا! 🎉

لقد أنشأت وكيل ADK يتيح للمستخدمين العثور على التجّار وتصفّح الكتالوجات وإكمال عمليات الشراء باستخدام UCP وAP2.

ما تعلّمته

في هذا الدرس التطبيقي حول الترميز، أنشأت وكيل ADK يتعامل مع مسارات التجارة الآمنة. في ما يلي ملخّص لما أنشأته والمفاهيم الأساسية التي طبّقتها:

ما أنشأته:

  • 5 أدوات وكيل تتضمّن عمليات UCP وAP2: الاستكشاف والبحث في الفهرس والدفع.
  • توقيع تفويض AP2: عملية دفع يوقّع عليها التاجر (تثبيت السعر) + CheckoutMandate وPaymentMandate (موافقة المستخدم).
  • البحث لدى عدة تجار: وكيل واحد يستعلم من عدة دور سينما ويدمج النتائج.

المفاهيم الأساسية:

البروتوكول

وظيفتها

آلية العمل

إعلانات Discovery على "منصّة الحملات الموحّدة"

يعثر الوكيل على التجّار وإمكاناتهم

/.well-known/ucp → الإمكانات ونقطة نهاية MCP وطرق الدفع والمفاتيح

UCP MCP

يتصفّح الوكيل الكتالوجات وينشئ عمليات دفع

طلبات JSON-RPC 2.0 إلى نقطة نهاية MCP الخاصة بالتاجر

تفويض التاجر

يثبّت التاجر السعر المحدّد

موقّعة من التاجر، وتشمل تفاصيل السلع والمبالغ الإجمالية

AP2 CheckoutMandate

يوافق المستخدم على عملية الدفع المحدّدة

موقّع من المستخدم، ويتضمّن عملية الدفع الموقّعة من التاجر

AP2 PaymentMandate

يوافق المستخدم على تحصيل الرسوم

موقّع من المستخدم، ويشير إلى تجزئة الدفع

ما هي الاختلافات في عملية الإنتاج؟

يستخدم هذا الدرس التطبيقي نماذج محاكاة. في مرحلة الإنتاج:

  • يتم حلّ اكتشاف UCP من خلال سجلّ، وليس من خلال عناوين URL ثابتة على المضيف المحلي.
  • تستضيف نقاط نهاية MCP التجّار الفعليون: بروتوكول JSON-RPC 2.0 نفسه، والمستودع الفعلي
  • يتم توقيع متطلبات AP2 على جهاز المستخدم الموثوق به أو من خلال منصة موثوق بها، وليس باستخدام مفتاح ينشئه الوكيل عند بدء التشغيل.
  • تأتي مفاتيح التوقيع من ملف UCP الخاص بكل طرف (يتلقّى التجار الوهميون المفتاح العام للوكيل في كل طلب بدلاً من ذلك).
  • تتم الموافقة على الدفع من خلال مقدّم بيانات اعتماد يتحقّق من PaymentMandate ويطلب موافقة المستخدم.
  • تعرض واجهة المستخدم نتائج الأداة على شكل واجهة مستخدم غنية (شبكات المنتجات، وملخّصات الدفع، وبطاقات التأكيد).

الخطوات التالية

المستندات المرجعية