১. সংক্ষিপ্ত বিবরণ
এই কোডল্যাবে, আপনি একটি ADK এজেন্ট চালাবেন যা দুটি ওপেন-সোর্স কমার্স প্রোটোকল ব্যবহার করে একাধিক থিয়েটার মার্চেন্টের কাছ থেকে সিনেমার টিকিট বুক করে।
- ইউসিপি (ইউনিভার্সাল কমার্স প্রোটোকল) : এজেন্টদের মার্চেন্ট খুঁজে বের করা, ক্যাটালগ অনুসন্ধান করা এবং চেকআউট প্রক্রিয়া পরিচালনা করার জন্য একটি স্ট্যান্ডার্ড।
- এপি২ (এজেন্ট পেমেন্টস প্রোটোকল) : ক্রিপ্টোগ্রাফিকভাবে স্বাক্ষরিত ম্যান্ডেট ব্যবহার করে নিরাপদ ও যাচাইযোগ্য পেমেন্ট অনুমোদনের একটি প্রোটোকল।
সিনেএজেন্ট নামক ডেমো অ্যাপটি ভিন্ন ভিন্ন সক্ষমতা (আসন নির্বাচন, বিশেষায়িত ফরম্যাট এবং অর্থপ্রদানের পদ্ধতি) সম্পন্ন দুটি নকল থিয়েটার মার্চেন্টের সাথে সংযুক্ত হয় এবং অনুসন্ধান থেকে শুরু করে অর্থপ্রদান পর্যন্ত সম্পূর্ণ বুকিং প্রক্রিয়াটি পরিচালনা করে।
আপনি যা শিখবেন
-
/.well-known/ucpপ্রোফাইলের মাধ্যমে UCP মার্চেন্ট ডিসকভারি কীভাবে কাজ করে - একটি ADK এজেন্ট কীভাবে ক্যাটালগ অনুসন্ধান করতে এবং চেকআউট তৈরি করতে UCP ব্যবহার করে
- AP2 কীভাবে লেনদেন সুরক্ষিত করে (চেকআউটম্যান্ডেট, পেমেন্টম্যান্ডেট)
- এজেন্টিক ই-কমার্স সুরক্ষিত করতে এন্ড-টু-এন্ড UCP এবং AP2 প্রোটোকল কীভাবে কাজ করে
আপনার যা যা লাগবে
- বিলিং সক্ষম একটি গুগল ক্লাউড প্রজেক্ট
- ক্রোমের মতো একটি ওয়েব ব্রাউজার
- পাইথন ৩.১১+ এবং ইউভি , যদি আপনি ক্লাউড শেলের পরিবর্তে আপনার নিজের মেশিনে কোডটি চালান।
এই কোডল্যাবটি সেইসব মধ্যম স্তরের ডেভেলপারদের জন্য, যাদের পাইথন এবং গুগল ক্লাউড সম্পর্কে কিছুটা ধারণা আছে। এই কোডল্যাবটি সম্পূর্ণ করতে প্রায় ৩০ মিনিট সময় লাগে।
এই কোডল্যাবে তৈরি রিসোর্সগুলোর খরচ ৫ ডলারের কম হওয়া উচিত।
২. ইউসিপি এবং এপি২ প্রোটোকল বোঝা
এজেন্ট তৈরির কাজে ঝাঁপিয়ে পড়ার আগে, চলুন সেই দুটি প্রোটোকল বুঝে নিই যা এই সুরক্ষিত এজেন্টিক বাণিজ্যকে সম্ভব করে তোলে।
এই কোডল্যাবে UCP পাইথন SDK সহ UCP সংস্করণ 2026-08-25 এবং AP2 পাইথন SDK সহ AP2 v0.2 ব্যবহৃত হয়েছে।
সার্বজনীন বাণিজ্য প্রোটোকল ( ইউসিপি )
UCP কৃত্রিম বুদ্ধিমত্তার এজেন্টদের ব্যবসায়ীদের সাথে যোগাযোগের পদ্ধতিকে প্রমিত করে। এটি একটি প্রমিত রিসোর্স মডেল প্রবর্তনের মাধ্যমে, এজেন্টদের প্রতিটি দোকানের জন্য নিজস্ব এপিআই শেখার সমস্যার সমাধান করে।
এটি যেভাবে কাজ করে:
- আবিষ্কার : প্রতিটি UCP-সম্মত মার্চেন্ট একটি নির্দিষ্ট স্থানে একটি প্রোফাইল প্রকাশ করে:
/.well-known/ucp। উদাহরণ: এভারলেনের UCP এন্ডপয়েন্ট । যখন কোনো এজেন্ট এই প্রোফাইলটি পড়ে, তখন এটি যা খোঁজে তা হলো:- কার্যক্ষমতা : একটি ব্যবসা যে স্বতন্ত্র মূল বৈশিষ্ট্যগুলো সমর্থন করে, যেমন ক্যাটালগ অনুসন্ধান বা চেকআউট।
- সার্ভিস : ডেটা আদান-প্রদানের জন্য ব্যবহৃত নিম্ন-স্তরের যোগাযোগ স্তর। উদাহরণ: REST API, MCP (মডেল কনটেক্সট প্রোটোকল), A2A (এজেন্টটুএজেন্ট প্রোটোকল)।
- এক্সটেনশন : কোনো ব্যবসায়ীর যদি বিশেষ কোনো আচরণের প্রয়োজন হয়, তবে তিনি এই প্রোফাইলে কাস্টম এক্সটেনশন নির্ধারণ করতে পারেন।
- কী (Keys) : মার্চেন্টের পাবলিক সাইনিং কী, যা এজেন্টরা মার্চেন্টের স্বাক্ষর যাচাই করার জন্য ব্যবহার করে।
- অপারেশনসমূহ : একবার আবিষ্কৃত হলে, এজেন্ট অপারেশন সম্পাদন করার জন্য প্রদত্ত সার্ভিস এন্ডপয়েন্টটি ব্যবহার করে। এই কোডল্যাবে, আমরা সার্ভিস ট্রান্সপোর্ট হিসেবে মডেল কনটেক্সট প্রোটোকল (MCP) ব্যবহার করি। এজেন্ট আবিষ্কৃত সক্ষমতাগুলো—যেমন প্রোডাক্ট অনুসন্ধান করা, চেকআউট তৈরি করা এবং কেনাকাটা সম্পন্ন করা—ব্যবহার করার জন্য এই এন্ডপয়েন্টে JSON-RPC 2.0 কল করে।

এজেন্ট পেমেন্ট প্রোটোকল ( AP2 )
AP2 ব্যবহারকারীদের পক্ষ থেকে এজেন্টদের দ্বারা পেমেন্ট অনুমোদনের পদ্ধতিকে প্রমিত করে। এটি এজেন্টদের দ্বারা সংবেদনশীল পেমেন্ট ক্রেডেনশিয়াল পরিচালনার নিরাপত্তা সমস্যার সমাধান করে।
এটি যেভাবে কাজ করে:
- মার্চেন্ট সিগনেচার : যখন কোনো এজেন্ট UCP প্রোটোকল ব্যবহার করে একটি চেকআউট তৈরি করেন, তখন মার্চেন্ট চেকআউটটিতে (লাইন আইটেম এবং টোটাল) স্বাক্ষর করেন এবং
ap2.merchant_authorizationএ সেই স্বাক্ষরটি ফেরত পাঠান। এটি একটি প্রাইস লক গ্যারান্টি হিসেবে কাজ করে। স্বাক্ষর করার পর যদি মার্চেন্ট মূল্য পরিবর্তন করেন, তাহলে স্বাক্ষরটি আর মেলে না। - চেকআউট ম্যান্ডেট এবং পেমেন্ট ম্যান্ডেট : চেকআউটের বিষয়বস্তু যাচাই করার পর, ব্যবহারকারী (অথবা ব্যবহারকারীর পক্ষে নিযুক্ত প্রতিনিধি) দুটি ম্যান্ডেটে স্বাক্ষর করেন।
CheckoutMandateমার্চেন্ট-স্বাক্ষরিত চেকআউটটি থাকে এবং এটি মার্চেন্টকে জানায় যে ব্যবহারকারী এটি অনুমোদন করেছেন।PaymentMandateসেই চেকআউটের জন্য অর্থপ্রদানের পরিমাণ অনুমোদন করে। উভয়ই স্বাক্ষরিত চেকআউটের একটি হ্যাশকে নির্দেশ করে এবং ব্যবহারকারীর ক্রিপ্টোগ্রাফিক স্বাক্ষর বহন করে। - স্বাক্ষর যাচাইকরণ : মার্চেন্ট উভয় ম্যান্ডেটই গ্রহণ করে। এটি
CheckoutMandateথাকা ব্যবহারকারীর স্বাক্ষর যাচাই করে এবং পরীক্ষা করে দেখে যে এর ভেতরের চেকআউটে মার্চেন্টের নিজের স্বাক্ষর রয়েছে কি না।PaymentMandateপেমেন্ট পক্ষের (একটি ক্রেডেনশিয়াল প্রোভাইডার বা পেমেন্ট প্রসেসর) কাছে যায়, যারা কোনো অর্থ পাঠানোর আগে এটি যাচাই করে। সবকিছু বৈধ হলে, লেনদেনটি সম্পন্ন হয়।
এই "ডাবল লক" সিস্টেমটি নিশ্চিত করে যে মার্চেন্টরা অতিরিক্ত চার্জ করতে পারবে না এবং এজেন্টরা অনুমোদন ছাড়া খরচ করতে পারবে না। ম্যান্ডেট হলো SD-JWT (সিলেক্টিভ ডিসক্লোজার JWT) ক্রেডেনশিয়াল, যা প্রতিটি পক্ষের শুধুমাত্র প্রয়োজনীয় ফিল্ডগুলো প্রকাশ করে ব্যবহারকারীর গোপনীয়তা রক্ষা করে। AP2 v0.2-এ, AP2 v0.1-এর CartMandate CheckoutMandate দ্বারা প্রতিস্থাপন করা হয়েছে।

৩. আপনার পরিবেশ প্রস্তুত করুন
গুগল ক্লাউড প্রজেক্ট সেটআপ
একটি গুগল ক্লাউড প্রজেক্ট তৈরি করুন
- গুগল ক্লাউড কনসোলের প্রজেক্ট সিলেক্টর পেজে, একটি গুগল ক্লাউড প্রজেক্ট নির্বাচন করুন বা তৈরি করুন ।
- আপনার ক্লাউড প্রোজেক্টের জন্য বিলিং চালু আছে কিনা তা নিশ্চিত করুন। কোনো প্রোজেক্টে বিলিং চালু আছে কিনা তা কীভাবে পরীক্ষা করবেন, তা জেনে নিন।
ক্লাউড শেল শুরু করুন
ক্লাউড শেল হলো গুগল ক্লাউডে চালিত একটি কমান্ড-লাইন পরিবেশ, যা প্রয়োজনীয় টুলস সহ আগে থেকেই লোড করা থাকে।
- Google Cloud কনসোলের শীর্ষে থাকা Activate Cloud Shell-এ ক্লিক করুন।
- ক্লাউড শেলে সংযুক্ত হওয়ার পর, আপনার প্রমাণীকরণ যাচাই করুন:
gcloud auth list - আপনার প্রজেক্টটি কনফিগার করা হয়েছে কিনা তা নিশ্চিত করুন:
gcloud config get project - আপনার প্রজেক্টটি প্রত্যাশা অনুযায়ী সেট করা না থাকলে, এটি সেট করুন:
export PROJECT_ID=<YOUR_PROJECT_ID> gcloud config set project $PROJECT_ID
এপিআই সক্ষম করুন
প্রয়োজনীয় API-গুলো সক্রিয় করতে নিম্নলিখিত কমান্ডটি চালান:
gcloud services enable aiplatform.googleapis.com
ডিরেক্টরি কাঠামো সেটআপ করুন
এই কোডল্যাবের জন্য একটি ফোল্ডার তৈরি করতে এবং এর ভিতরে এজেন্ট কোডের জন্য একটি agent_payments ফোল্ডার তৈরি করতে নিম্নলিখিত কমান্ডগুলি কপি-পেস্ট করুন:
mkdir -p ~/adk-agent-commerce/agent_payments
cd ~/adk-agent-commerce
জেমিনি মডেলগুলিতে অ্যাক্সেস করুন
আপনার প্রজেক্ট ও লোকেশন দিয়ে agent_payments/.env তৈরি করতে এবং আপনার গুগল ক্লাউড প্রজেক্টের মাধ্যমে ADK-কে 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
নির্ভরতা ইনস্টল করুন
পরিবেশ ও নির্ভরতা ব্যবস্থাপনার জন্য uv সাথে গুগল ক্লাউড শেল আগে থেকেই ইনস্টল করা থাকে।
- আপনার
adk-agent-commerceফোল্ডারের রুটে একটিpyproject.tomlফাইল তৈরি করুন এবং এতে নিম্নলিখিত বিষয়বস্তু যোগ করুন। এই ফাইলটি প্রোজেক্টের মেটাডেটা এবং নির্ভরতা নির্ধারণ করে।
[project]
name = "agent-payments-demo"
version = "0.1.0"
description = "CineAgent booking agent using UCP and AP2"
requires-python = ">=3.11"
dependencies = [
"google-adk",
"fastapi",
"uvicorn",
"httpx",
"ucp-sdk",
"ap2 @ git+https://github.com/google-agentic-commerce/AP2.git@main",
]
AP2 SDK-টি এর গিটহাব রিপোজিটরি থেকে ইনস্টল করা হয়, কারণ এটি এখনও PyPI-তে প্রকাশিত হয়নি। (PyPI-তে থাকা ap2 প্যাকেজটি একটি সম্পর্কহীন প্রকল্প।)
- ভার্চুয়াল এনভায়রনমেন্ট তৈরি করতে এবং সমস্ত ডিপেন্ডেন্সি ইনস্টল করতে নিম্নলিখিত কমান্ডটি চালান:
uv sync
uv এই কোডল্যাবের জন্য একটি বিচ্ছিন্ন পাইথন পরিবেশ তৈরি করে, তাই আপনাকে কিছু সক্রিয় করতে হবে না। পাইথন কমান্ডের আগে 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 প্রোটোকলের একটি নির্দিষ্ট অপারেশনের সাথে ম্যাপ করা থাকে:
সরঞ্জাম | এটা যা করে | প্রোটোকল অ্যাকশন |
| ব্যবসায়ীদের এবং তাদের সক্ষমতা খুঁজুন | কোয়েরি |
| ব্যবসায়ীদের মধ্যে ক্যাটালগ অনুসন্ধান করুন | JSON-RPC থেকে MCP এন্ডপয়েন্ট |
| একটি নির্দিষ্ট দোকানে শো-টাইম জেনে নিন। | JSON-RPC থেকে MCP এন্ডপয়েন্ট |
| চেকআউট সেশন শুরু করুন | JSON-RPC থেকে MCP এন্ডপয়েন্ট |
| পেমেন্ট অনুমোদন করুন এবং অর্ডারটি সম্পন্ন করুন। | এপি২ ম্যান্ডেটে স্বাক্ষর করে এমসিপি-র কাছে পাঠিয়েছেন |
জেমিনি মডেলটি কথোপকথনের উপর ভিত্তি করে সিদ্ধান্ত নেবে কখন কোন টুলকে ডাকা হবে । এরপর আমাদের কাজ হলো 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-তেই মার্চেন্টদের কল করার জন্য ক্লায়েন্ট অন্তর্ভুক্ত নেই, তাই এই হেল্পারগুলো সেই অংশটি সামলায়।
- আপাতত, এগুলোকে সহায়ক অবজেক্ট হিসেবে বিবেচনা করুন :
-
_ucp.discover(url): কোনো মার্চেন্টের প্রোফাইল সংগ্রহ ও যাচাই করে। -
_ucp.mcp_call(url, method, params): মার্চেন্টের MCP এন্ডপয়েন্টে একটি JSON-RPC 2.0 অনুরোধ পাঠায়।
-
থিয়েটার আবিষ্কার করুন
এই টুলটি ইউসিপি প্রক্রিয়ার প্রথম ধাপ। এটি খুঁজে বের করে যে কোন কোন মার্চেন্ট বিদ্যমান এবং তারা কী সমর্থন করে।
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)
এর কাজ হলো :
- এটি সার্ভার দ্বারা প্রদত্ত মার্চেন্ট ইউআরএল-এর একটি তালিকার উপর পুনরাবৃত্তি করে। এই কোডল্যাবের পরবর্তী অংশে আমরা দুটি মক মার্চেন্ট সেটআপ করব।
- প্রতিটি URL-এর জন্য, এটি
_ucp.discover(url)কল করে, যা/.well-known/ucpএন্ডপয়েন্টে হিট করে। - এটি নাম, সক্ষমতা এবং পেমেন্ট হ্যান্ডলারদের একটি সারসংক্ষেপ তালিকায় সংগ্রহ করে।
- এটি এজেন্টের পড়ার জন্য তালিকাটিকে একটি JSON স্ট্রিং হিসেবে ফেরত দেয়।
সিনেমা অনুসন্ধান করুন
এই টুলটি খুঁজে পাওয়া সমস্ত বিক্রেতার মধ্যে অনুসন্ধান করে এবং ফলাফলগুলোকে একত্রিত করে। এটি অত্যন্ত গুরুত্বপূর্ণ, কারণ একই সিনেমা একাধিক প্রেক্ষাগৃহে ভিন্ন ভিন্ন ফরম্যাটে (আইম্যাক্স, ডলবি) এবং ভিন্ন ভিন্ন দামে প্রদর্শিত হতে পারে।
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)
এর কাজ হলো :
- এটি আবিষ্কৃত সমস্ত প্রেক্ষাগৃহের মধ্যে চক্রাকারে ঘোরে।
- এটি মার্চেন্টের MCP এন্ডপয়েন্টে একটি সার্চ ক্যাটালগ JSON-RPC রিকোয়েস্ট (
_ucp.mcp_call(url, "search_catalog", {"catalog": {"query": query}})) পাঠায়। - এরপর এটি ফলাফলগুলো পার্স করে সিনেমা এবং তাদের 'ভেরিয়েন্ট' (যা নির্দিষ্ট শো-টাইম এবং ফরম্যাট নির্দেশ করে) খুঁজে বের করার জন্য কিছু পরিষ্করণ করে। সিনেমাগুলোকে আইডি অনুসারে গ্রুপ করা হয়, যাতে ব্যবহারকারী একই সিনেমার একাধিক এন্ট্রি দেখতে না পান।
চলচ্চিত্রের বিস্তারিত জানুন
এই টুলটি একটি নির্দিষ্ট প্রেক্ষাগৃহে একটি নির্দিষ্ট সিনেমার সম্পূর্ণ ক্যাটালগের বিবরণ খুঁজে বের করে।
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)
এর কাজ হলো :
- এটি
catalog.idsএ নির্দিষ্টmovie_idপাস করে মার্চেন্টের MCP এন্ডপয়েন্টে `lookup_catalogমেথডটিকে কল করে। এর ফলে সেই নির্দিষ্ট থিয়েটারের শো-টাইম এবং সিটের প্রাপ্যতার মতো বিস্তারিত তথ্য ফেরত আসে।
৬. এজেন্ট টুল তৈরি করুন: চেকআউট ও পেমেন্ট
এই টুলগুলো চেকআউট এবং ক্রয় প্রক্রিয়া পরিচালনা করে। এখানেই নিরাপদ লেনদেন নিশ্চিত করতে 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)
এর কাজ হলো :
- এটি মার্চেন্টের MCP এন্ডপয়েন্টে
create_checkoutমেথডটিকে কল করে। - এটি ব্যবহারকারীর অনুরোধ করা
showtime_idএবংquantityপ্রেরণ করে। - বণিক তার নিজস্ব কী দিয়ে স্বাক্ষরিত একটি চেকআউট ফেরত দেয়।
দ্রষ্টব্য : আপনি যদি রেসপন্স ডেটা পরীক্ষা করেন, তাহলে দেখতে পাবেন যে ap2.merchant_authorization ফিল্ডটিতে চেকআউটের উপর মার্চেন্টের ক্রিপ্টোগ্রাফিক স্বাক্ষর থাকে, যা উদ্ধৃত মূল্যটিকে লক করে দেয়। তারা পরবর্তীতে এটি পরিবর্তন করতে পারে না!
সম্পূর্ণ ক্রয়
এই টুলটিতে তিনটি ঘটনা ঘটে:
- আমরা চেকআউটটি গ্রহণ করি এবং তাতে থাকা বিক্রেতার স্বাক্ষর যাচাই করি।
- AP2 SDK ব্যবহার করে CheckoutMandate এবং PaymentMandate তৈরি ও স্বাক্ষর করুন।
- ক্রয়টি সম্পন্ন করার জন্য উভয় আদেশপত্রই বিক্রেতার কাছে পাঠিয়ে দিন।
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)
দুটি ম্যান্ডেট কেন? চেকআউটম্যান্ডেট মার্চেন্টকে প্রমাণ করে যে, ব্যবহারকারী মার্চেন্টের স্বাক্ষরিত মূল্যে এই নির্দিষ্ট চেকআউটটি অনুমোদন করেছেন। পেমেন্টম্যান্ডেট পেমেন্ট পক্ষকে প্রমাণ করে যে, ব্যবহারকারী এই চার্জটি অনুমোদন করেছেন। প্রক্রিয়াটি হলো:
Merchant signs checkout -> User signs mandates -> Merchant and payment side verify -> Order completes ।
চেকপয়েন্ট: সম্পূর্ণ tools.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-গুলো দেখিয়ে দিলেই কাজ শেষ। এই কোডল্যাবের জন্য, আমাদের স্থানীয়ভাবে পরীক্ষা করার জন্য দুটি জিনিস প্রয়োজন:
- মক মার্চেন্ট : স্থানীয় সার্ভার যা UCP এন্ডপয়েন্ট অনুকরণ করে, যাতে আপনার কাছে পরীক্ষা করার জন্য একটি ভিত্তি থাকে।
- প্রোটোকল হেল্পার : পাতলা র্যাপার যা 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 ডিসকভারি। এটি মার্চেন্টের ক্যাপাবিলিটি, MCP এন্ডপয়েন্ট URL, গৃহীত পেমেন্ট পদ্ধতি এবং পাবলিক সাইনিং কী ফেরত দেয়। -
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
আপনার মার্চেন্টের ক্যাপাবিলিটি, এমসিপি এন্ডপয়েন্ট ইউআরএল, পেমেন্ট হ্যান্ডলার এবং পাবলিক কী দেখা উচিত।
৮. ADK Web দিয়ে এজেন্টটি চালান
চলুন ADK CLI-এর বিল্ট-ইন ওয়েব UI ব্যবহার করি! এটি ব্রাউজারে একটি চ্যাট ইন্টারফেস প্রদান করে এবং টুল নিশ্চিতকরণের অনুরোধগুলো স্বয়ংক্রিয়ভাবে পরিচালনা করে।
আপনার প্রজেক্টটি এখন দেখতে এইরকম হবে:
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 ওয়েব UI চালু করুন:
cd ~/adk-agent-commerce
uv run adk web --port 8080 --allow_origins '*'
আপনি এমন আউটপুট দেখতে পাবেন যা থেকে বোঝা যাবে যে সার্ভারটি http://127.0.0.1:8080 ঠিকানায় চালু আছে।
এজেন্টের সাথে কথা বলুন
- URL-এর উপর Ctrl বা Cmd চেপে, অথবা Web Preview বাটনে ক্লিক করে এবং পোর্ট 8080-এ Preview নির্বাচন করে ADK Web UI খুলুন।
- যদি আগে থেকে নির্বাচিত না থাকে, তাহলে ড্রপ-ডাউন মেনু থেকে
agent_paymentsনির্বাচন করুন। আপনি একটি চ্যাট ইন্টারফেস দেখতে পাবেন। - জিজ্ঞাসা করে দেখতে পারেন: "এখন কী কী সিনেমা চলছে?"
- এজেন্টটি নেপথ্যে থেকে প্রেক্ষাগৃহ খুঁজে বের করবে এবং ক্যাটালগ অনুসন্ধান করবে, এবং UCP-এর মাধ্যমে উভয় বিক্রেতার কাছ থেকে ফলাফল একত্রিত করবে।
- টিকিট বুক করতে বলুন: "সন্ধ্যা ৭টার জন্য ওপেনহাইমারের ২টি টিকিট বুক করুন" ।
- যখন এজেন্ট
complete_purchaseকল করার চেষ্টা করে, তখন লক্ষ্য করুন কীভাবে ADK ওয়েব UI-তে ক্রয়ের বিবরণসহ একটি কনফার্মেশন কার্ড দেখানো হয়! - লেনদেনটি অনুমোদন করতে, কার্ডের ওপর থাকা ‘Confirmed’ চেকবক্সটি নির্বাচন করুন এবং ‘Submit’ বাটনে ক্লিক করুন।
- এজেন্ট ক্রয়টি সম্পন্ন করবে এবং টিকিট কোডসহ আপনার অর্ডার নিশ্চিতকরণ ফেরত পাঠাবে!
নেপথ্যে যা ঘটেছিল তা এখানে দেওয়া হলো:
-
create_checkout→ মার্চেন্ট তার নিজস্ব কী (ap2.merchant_authorization, অর্থাৎ প্রাইস লক) দিয়ে স্বাক্ষরিত একটি চেকআউট ফেরত দিয়েছে। -
complete_purchase→ মার্চেন্টের স্বাক্ষর যাচাই করা হয়েছে, একটি CheckoutMandate এবং একটি PaymentMandate তৈরি করা হয়েছে, উভয়কে SD-JWT হিসেবে স্বাক্ষর করা হয়েছে, এবং সেগুলো মার্চেন্টের কাছে পাঠানো হয়েছে। - মার্চেন্ট উভয় ম্যান্ডেট যাচাই করেছে এবং পরীক্ষা করে দেখেছে যে সেগুলি চেকআউটের দিকে নির্দেশ করছে যেখানে স্বাক্ষর করা হয়েছে → টিকিট ইস্যু করেছে (নকল মডেলে)
৯. পরিষ্কার করুন
স্থানীয় সার্ভারগুলো চালু থাকা এড়াতে, রিসোর্সগুলো পরিষ্কার করুন:
- টার্মিনালে
adk webচালানোর সময়, এজেন্ট সার্ভারটি বন্ধ করতে Ctrl+C চাপুন। - টার্মিনালে
merchants.pyচালু থাকা অবস্থায়, মক মার্চেন্টগুলো বন্ধ করতে Ctrl+C চাপুন। - (ঐচ্ছিক) আপনি যদি এই কোডল্যাবের জন্য একটি নতুন গুগল ক্লাউড প্রজেক্ট তৈরি করে থাকেন এবং সেটি মুছে ফেলতে চান, তাহলে নিম্নলিখিত কমান্ডটি চালান, প্রতিস্থাপন করে।
এর প্রজেক্ট আইডি সহ:
gcloud projects delete <YOUR_PROJECT_ID>
১০. অভিনন্দন! 🎉
আপনি একটি ADK এজেন্ট তৈরি করেছেন যা UCP এবং AP2 ব্যবহার করে মার্চেন্ট খুঁজে বের করে, ক্যাটালগ ব্রাউজ করে এবং কেনাকাটা সম্পন্ন করে।
আপনি যা শিখেছেন
এই কোডল্যাবে, আপনি একটি ADK এজেন্ট তৈরি করেছেন যা সুরক্ষিত কমার্স ফ্লো পরিচালনা করে। আপনি যা তৈরি করেছেন এবং যে মূল ধারণাগুলো প্রয়োগ করেছেন তার একটি সারসংক্ষেপ নিচে দেওয়া হলো:
আপনি যা তৈরি করেছেন:
- UCP এবং AP2 অপারেশনসমূহকে আবৃতকারী ৫টি এজেন্ট টুল : ডিসকভারি, ক্যাটালগ সার্চ, চেকআউট, পেমেন্ট।
- AP2 ম্যান্ডেট স্বাক্ষর : মার্চেন্ট-স্বাক্ষরিত চেকআউট (প্রাইস লক) + চেকআউটম্যান্ডেট এবং পেমেন্টম্যান্ডেট (ব্যবহারকারীর অনুমোদন)।
- একাধিক প্রেক্ষাগৃহে অনুসন্ধান : একজন এজেন্ট একাধিক প্রেক্ষাগৃহে অনুসন্ধান করে ফলাফল একত্রিত করছেন।
মূল ধারণা:
প্রোটোকল | এটা যা করে | এটি কীভাবে কাজ করে |
ইউসিপি ডিসকভারি | এজেন্ট ব্যবসায়ীদের এবং তাদের সক্ষমতা খুঁজে বের করে। | |
ইউসিপি এমসিপি | এজেন্ট ক্যাটালগ ব্রাউজ করে, চেকআউট তৈরি করে। | মার্চেন্টের এমসিপি এন্ডপয়েন্টে JSON-RPC 2.0 কল |
বণিক অনুমোদন | বণিক উদ্ধৃত মূল্য স্থির করে। | ব্যবসায়ী কর্তৃক স্বাক্ষরিত, এতে প্রতিটি আইটেম ও মোট যোগফল অন্তর্ভুক্ত রয়েছে। |
AP2 চেকআউট ম্যান্ডেট | ব্যবহারকারী সঠিক চেকআউট অনুমোদন করেন। | ব্যবহারকারী কর্তৃক স্বাক্ষরিত, এতে মার্চেন্ট-স্বাক্ষরিত চেকআউট অন্তর্ভুক্ত রয়েছে। |
এপি২ পেমেন্ট ম্যান্ডেট | ব্যবহারকারী চার্জ অনুমোদন করেন | ব্যবহারকারী দ্বারা স্বাক্ষরিত, চেকআউট হ্যাশকে নির্দেশ করে। |
উৎপাদনে কী ভিন্নতা আছে?
এই কোডল্যাবে মক ব্যবহার করা হয়েছে। প্রোডাকশনে:
- UCP ডিসকভারি হার্ডকোডেড লোকালহোস্ট ইউআরএল-এর পরিবর্তে একটি রেজিস্ট্রিকে ভিত্তি করে সমাধান করে।
- MCP এন্ডপয়েন্টগুলো প্রকৃত ব্যবসায়ীদের দ্বারা হোস্ট করা হয়: একই JSON-RPC 2.0 প্রোটোকল, আসল ইনভেন্টরি।
- AP2 ম্যান্ডেটগুলি ব্যবহারকারীর বিশ্বস্ত ডিভাইসে বা একটি বিশ্বস্ত প্ল্যাটফর্ম দ্বারা স্বাক্ষরিত হয়, এজেন্ট দ্বারা স্টার্টআপের সময় তৈরি করা কোনো কী দিয়ে নয়।
- স্বাক্ষর করার কীগুলো প্রতিটি পক্ষের UCP প্রোফাইল থেকে আসে (এর পরিবর্তে মক মার্চেন্টরা প্রতিটি অনুরোধে এজেন্টের পাবলিক কী পেয়ে থাকে)।
- পেমেন্ট অনুমোদন একটি ক্রেডেনশিয়াল প্রোভাইডারের মাধ্যমে সম্পন্ন হয়, যা পেমেন্টম্যান্ডেট যাচাই করে এবং ব্যবহারকারীর সম্মতি চায়।
- ফ্রন্টএন্ড টুলের ফলাফলগুলোকে একটি সমৃদ্ধ UI (প্রোডাক্ট গ্রিড, চেকআউট সামারি, কনফার্মেশন কার্ড) হিসেবে রেন্ডার করে।
পরবর্তী পদক্ষেপ
- AP2 প্রোটোকল স্পেসিফিকেশনটি অন্বেষণ করুন এবং আপনার নিজস্ব পেমেন্ট-সক্ষম এজেন্ট তৈরি করুন।
- আপনার মার্চেন্টের জন্য এজেন্টিক কমার্স সক্ষম করতে ইউসিপি প্রয়োগ করুন।
- একাধিক এজেন্ট কমার্স ওয়ার্কফ্লোর জন্য AP2-কে A2A- এর সাথে সংযুক্ত করুন
- ক্রিপ্টোকারেন্সি পেমেন্টের জন্য AP2 x402 এক্সটেনশন সম্পর্কে জানুন