ادائیگی کرنے والے ایجنٹس: پروڈکشن میں ACP، AP2، x402، اور MPP

یہ ان چار پروٹوکولز کا فوری کورس ہے جو OpenAI Agents SDK systems کو رقم خرچ کرنے کے قابل بناتے ہیں: merchants کے پاس، APIs کے مقابل، دوسرے ایجنٹس کے ساتھ، اور کھلی معیشت میں۔ یہ ان انجینئرز کے لیے ہے جو ایجنٹس ship کر چکے ہیں اور اب انہیں ادائیگی کے قابل بنانا چاہتے ہیں۔

19 تصورات۔ 5 فیصلے۔ 3 diagrams۔ سیکھنے کے چار راستے۔ Reader track خالص پڑھائی کے 2-3 گھنٹے لیتا ہے: چار-layer stack، ہر protocol کی گہرائی، composition rules، کوئی setup نہیں۔ Beginner، Intermediate، اور Advanced tracks ایجنٹس کو protocols سے جوڑنے، composition کو پائیدار طریقے سے چلانے، اور identity، spend، disputes کو سنبھالنے میں بڑھتی ہوئی عملی گہرائی شامل کرتے ہیں۔ یہ تقریباً 1 دن، 2-3 دن، اور 4-5 دن لیتے ہیں۔ دیانت دار اندازہ: پڑھنے کے لیے 2-3 گھنٹے، اور team کو اس stack کو working habit بنانے کے لیے 4-5 دن۔ Part 5 کی decision lab سے پہلے اپنا track منتخب کریں۔

یہ کورس ایک مرکزی خیال پر کھڑا ہے: چاروں پروٹوکولز حریف نہیں، layers ہیں۔ زیادہ تر articles پوچھتے ہیں: "ACP یا x402؟" یہ سوال ہی protocol کی نوعیت کو غلط سمجھتا ہے۔ 2026 میں ship ہونے والا حقیقی system کئی protocols کو ساتھ استعمال کرتا ہے، کیونکہ ہر protocol agent-commerce problem کی ایک الگ layer حل کرتا ہے۔ Consumer shopping agent commerce layer پر ACP اور settlement پر card rails استعمال کرتا ہے۔ API-paying agent دونوں جگہ x402 استعمال کر سکتا ہے، کیونکہ machine-to-machine micropayments میں یہ دو layers ایک ہو جاتی ہیں۔ Enterprise procurement agent پہلے AP2 mandates سے ثابت کرتا ہے کہ انسان نے spend authorize کیا، پھر settlement پر Stripe MPP استعمال کرتا ہے۔ آپ use case پڑھ کر درست composition منتخب کرنا سیکھیں گے۔

اگر آپ نے Agent Factory کے باقی courses نہیں کیے

یہ کورس چند related courses کے نام لیتا ہے: Build AI Agents crash course (SDK basics)، Production Worker crash course (Inngest کے ساتھ agents کو durably چلانا)، Eval-Driven Development crash course، اور Choosing Agentic Architectures crash course۔ آپ یہ کورس ان کے بغیر بھی پڑھ سکتے ہیں۔ چار protocols، layering، SDK code، اور decision discipline اپنی جگہ مکمل ہیں۔ ایک چیز مدد دیتی ہے: Part 3 کا code فرض کرتا ہے کہ آپ Agent، Runner.run()، اور @function_tool پڑھ سکتے ہیں۔ اگر یہ نئے ہیں تو پہلے Build AI Agents crash course یا OpenAI Agents SDK docs skim کریں، پھر واپس آئیں۔

اگر آپ کا stack مختلف ہے تو ہر protocol کس چیز سے map ہوتا ہے

اگر آپ OpenAI Agents SDK کے ساتھ Stripe، Coinbase، اور Cloudflare استعمال نہیں کر رہے، تو یہ table ہر reference implementation کو عام alternatives سے map کرتی ہے۔ Protocol specs stack-agnostic ہیں؛ فرق صرف primitive names کا ہوتا ہے۔

Protocol	بنیادی reference SDK (2026)	عام alternatives	License / governance
ACP (Agentic Commerce Protocol)	Stripe SDK (stripe) مع OpenAI Agents SDK؛ أدوات خادم PayPal ACP؛ بیانات اعتماد Worldpay	Adyen ACP، وواجہة checkout API أصلیة من Shopify	Apache 2.0، OpenAI مع Stripe فی github.com/agentic-commerce-protocol/agentic-commerce-protocol
AP2 (Agent Payments Protocol)	Google ADK مع تنفیذات مرجعیة فی Python وTypeScript وKotlin وGo	LangGraph مع توقیع تفویضات مخصص، أو AutoGen مع a2a-x402	Apache 2.0، Google مع أکثر من 60 شریکا فی github.com/google-agentic-commerce/AP2
x402	x402-client (Python)، و@x402/client (JS/TS)، وCoinbase Developer Platform، وCloudflare withX402Client، وAgentPay MCP	تنفیذات مباشرة ل EIP-3009؛ Lobster.cash؛ محافظ وکلاء من Crossmint	Apache 2.0، أنشأتہ Coinbase، وہو الآن تحت x402 Foundation التابعة ل Linux Foundation
MPP (Machine Payments Protocol)	Stripe PaymentIntents مع امتدادات MPP؛ وTempo blockchain SDK	Lightning Network مباشرة؛ Tempo native SDKs	Apache 2.0، Stripe مع Tempo؛ المواصفات فی mpp.dev
A2A (Agent2Agent، الطبقة التی یوسعہا AP2)	Google ADK	تنفیذات A2A مخصصة	Apache 2.0، Google مع Linux Foundation
MCP (Model Context Protocol، طبقة الاکتشاف)	خوادم وعملاء Anthropic MCP؛ ودعم MCP فی openai-agents	LangChain MCP	MIT، Anthropic

اس table کو یوں استعمال کریں: جب course کہتا ہے کہ agent کی @function_tool کو Stripe ACP endpoint سے wire کریں، اور آپ Adyen plus LangGraph پر ہیں، تو اسے یوں پڑھیں کہ equivalent LangGraph tool کو Adyen ACP endpoint سے wire کریں۔ دلیل وہی رہتی ہے؛ names بدلتے ہیں۔ صرف یہ course پڑھنے کے لیے Stripe stack سیکھنے کی ضرورت نہیں۔ Primitives map کریں، framework follow کریں، اور اسے اپنے stack پر apply کریں۔

لغت

📖 اس course کی اصطلاحات: پہلی reading پر کھولیں، بعد میں واپس دیکھیں

چار headline protocols

• پروٹوکول ACP (Agentic Commerce Protocol). Consumer-shopping protocol، جسے OpenAI اور Stripe نے بنایا۔ یہ govern کرتا ہے کہ agent کسی شخص کی طرف سے حقیقی merchant پر checkout کیسے complete کرتا ہے۔ ChatGPT Instant Checkout اسی سے چلتا ہے۔ یہ زیادہ تر commerce layer میں رہتا ہے۔ Apache 2.0۔
• پروٹوکول AP2 (Agent Payments Protocol). Authorization protocol، جسے Google نے 60+ partners کے ساتھ بنایا۔ یہ signed "mandates" بناتا ہے جو ثابت کرتے ہیں کہ انسان نے agent کو spend کرنے کی اجازت دی۔ یہ خود money move نہیں کرتا؛ یہ ثابت کرتا ہے کہ spend authorized تھا۔ Apache 2.0۔
• پروٹوکول x402۔ HTTP-native settlement protocol، جسے Coinbase نے بنایا اور اب Linux Foundation govern کرتی ہے۔ یہ unused HTTP 402 "Payment Required" status code کو revive کرتا ہے تاکہ agent stablecoin کے ذریعے 1-2 seconds میں API call کی payment کر سکے۔ Apache 2.0۔
• پروٹوکول MPP (Machine Payments Protocol). Stripe اور Tempo کا settlement protocol۔ اس کی خاص trick "session" ہے: agent پہلے spending cap approve کرتا ہے، پھر اس cap کے خلاف بہت سی چھوٹی payments stream کرتا ہے۔ Multi-rail: stablecoin، Lightning، cards۔ Apache 2.0۔

یہ layers پورے course کی ریڑھ کی ہڈی ہیں

• یہ Discovery layer ہے۔ یہ وہ layer ہے جہاں agent معلوم کرتا ہے کہ وہ کیا خرید سکتا ہے۔ اس کا جواب MCP servers، A2A، agent directories، یا AI shopping surfaces دیتے ہیں۔ سوال: "کیا available ہے؟"
• یہ Authorization layer ہے (Identity and Authorization بھی)۔ یہ وہ layer ہے جو money move ہونے سے پہلے دو چیزیں ثابت کرتی ہے: انسان نے اس spending کی اجازت دی، اور agent واقعی وہی ہے جو وہ claim کر رہا ہے۔ سوال: "کیا مجھے یہ spend کرنے کی اجازت ہے؟"
• یہ Commerce layer ہے۔ وہ layer جو پوری purchase چلاتی ہے: cart، checkout، fulfillment، dispute، refund۔ سوال: "پوری purchase lifecycle کیا ہے؟" Plain API calls میں یہ layer مکمل skip ہو جاتی ہے۔
• یہ Settlement layer ہے۔ وہ layer جہاں واقعی money ہاتھ بدلتی ہے۔ سوال: "money اصل میں کہاں move ہوتی ہے؟"
• یہ Settlement rail ہے (یا rail)۔ وہ اصل pipe جس سے money گزرتی ہے: card networks (Stripe کے ذریعے Visa/Mastercard)، blockchain پر stablecoins، bank transfer (ACH/SEPA)، یا Lightning۔ "rail منتخب کریں" کا مطلب ہے "money کیسے move ہو گی، یہ منتخب کریں۔"

بدائیات التفویض

• تفویض (AP2). إثبات رقمی موقّع بأن إنسانا فوّض نوعا محددا من الإنفاق. لدی AP2 ثلاثة: Intent وCart وPayment (أدناہ). تشکل معا سلسلة یمکنک تدقیقہا لاحقا.
• تفویض Intent Mandate. أول تفویض، یوقّعہ المستخدم قبل أن یبدأ الوکیل: قواعد المہمة. مثال: "اشتر حذاء بسعر أقل من 120 دولارا." یضع الحدود التی یجب أن یبقی الوکیل داخلہا.
• تفویض Cart Mandate. التفویض الأوسط، یوقّعہ المستخدم بعد أن یبنی الوکیل سلة محددة: "نعم، ہذہ العناصر بالضبط وبہذا السعر بالضبط." یستخدم فی التدفقات التی یکون فیہا إنسان حاضر للموافقة.
• تفویض Payment Mandate. التفویض الأخیر، یوقّع، أو یولد آلیا مقابل Intent Mandate، عند لحظة الدفع: "فوّض ہذہ الدفعة بالضبط علی ہذہ السکة بالضبط."
• رمز SPT (Shared Payment Token). بدائیة ACP. رمز لمرة واحدة من معالج الدفع (Stripe)، مقفل علی تاجر واحد، وسقف مبلغ واحد، ونافذة زمنیة قصیرة واحدة. إذا حاول وکیل مسموح لہ بإنفاق 50 دولارا أن ینفق 1000 دولار، یفشل SPT ببساطة. إنہ ابن عم Payment Mandate علی سکک البطاقات.
• غیر قابل للإنکار. سجل موقّع لا یستطیع الموقّع أن ینکر لاحقا أنہ أنشأہ. سلسلة تفویضات AP2 غیر قابلة للإنکار: عبارة "لم أفوض ہذا" لا تصمد أمام توقیع المستخدم التشفیری نفسہ.

بدائیات التسویة والعملات المشفرة

• عملة مستقرة. عملة مشفرة مربوطة بقیمة مستقرة، غالبا دولار أمریکی واحد. یستخدمہا الوکلاء حتی تبقی "دفعة 0.05 دولار" مساویة لخمسة سنتات بین الإرسال والتسویة.
• عملة USDC. العملة المستقرة المرتبطة بالدولار التی تستخدمہا معظم مدفوعات x402. یفترض أن یساوی USDC واحد دولارا أمریکیا واحدا. تصدرہا Circle.
• رمز HTTP 402 Payment Required. رمز حالة HTTP محجوز منذ 1997 لکنہ بقی غیر مستخدم إلی أن أحیاہ x402. یرد الخادم ب "402" مع متطلبات الدفع؛ ثم یعید العمیل المحاولة ومعہ إثبات دفع موقّع.
• معیار EIP-3009 (transferWithAuthorization). معیار Ethereum الذی یبنی علیہ x402. یسمح للمشتری بتوقیع دفعة خارج السلسلة یرسلہا طرف آخر إلی السلسلة، فلا یدفع المشتری رسوم gas ولا یلمس blockchain مباشرة.
• دور Facilitator (x402). طرف ثالث اختیاری یتحقق من التوقیع ویرسل الدفع علی السلسلة لصالح التاجر، حتی لا یضطر التاجر إلی تشغیل سباکة blockchain الخاصة بہ. تشغل Coinbase وCloudflare facilitators.
• معیار CAIP-2. طریقة قیاسیة لتسمیة blockchain حتی یبقی البروتوکول محایدا تجاہ السلسلة. یکتب x402 السلاسل بصیغة CAIP-2.
• مخطط EIP-155 / chain id. نظام الترقیم داخل CAIP-2 للسلاسل المشابہة ل Ethereum. یعنی eip155:8453 سلسلة Base؛ والرقم ہو chain id. (ستری eip155:8453 فی کود x402؛ ومعناہ ببساطة "Base.")
• محفظة عقد ذکی. محفظة crypto تفرض قواعد إنفاقہا (سقف کل معاملة، سقف یومی، سقف کل مستلم) بکود علی blockchain نفسہا. وبما أن السلسلة تفرض ہذہ الحدود، فإنہا تصمد حتی إذا اختل کود الوکیل نفسہ.
• جلسة MPP. الحرکة الممیزة فی MPP. بدلا من توقیع کل دفعة علی حدة، یفتح الوکیل "جلسة" بسقف إنفاق وحد زمنی، ثم یبث مدفوعات صغیرة مقاسة مقابلہا حتی تغلق. تخیلہا "حسابا مسبق الدفع للوکیل."
• نموذج الجلسات (MPP). الاسم العام للنمط السابق: فوّض سقفا ومدة مسبقا، ثم قس عدة رسوم صغیرة مقابلہ. أرخص من توقیع کل دفعة صغیرة عندما تکون الاستدعاءات متکررة.

مفاہیم التجارة والمال

• التسویة. لحظة انتقال المال فعلا من المشتری إلی البائع. کل ما قبل التسویة ہو تنسیق؛ ولا تتم الصفقة إلا عندما تکتمل التسویة.
• مفہوم Merchant of record (MoR). النشاط التجاری المسؤول قانونیا عن المعاملة: یتعامل مع الضرائب والنزاعات ودعم العملاء. فی ACP یبقی التاجر ہو MoR. وفی استدعاءات x402 البسیطة بین الآلات لا یوجد MoR غالبا.
• آلیة Chargeback. عندما یعکس بنک المشتری دفعة بطاقة، غالبا بعد نزاع. تدعم سکک البطاقات chargebacks؛ ولا یدعم x402 الخالص ذلک. والحاجة إلی chargebacks تحدد کثیرا أی بروتوکول تستخدمہ.
• النزاع. اعتراض رسمی من المشتری علی الرسوم ("لم أفوض ہذا" / "لم یصل المنتج"). تحل البروتوکولات المختلفة النزاعات بطرق مختلفة؛ وغالبا یفرض ہذا الاختلاف اختیار البروتوکول.
• خاصیة Idempotency. خاصیة تجعل تنفیذ العملیة نفسہا مرتین یعطی أثر تنفیذہا مرة واحدة. تہم لأن Stripe یعید webhooks بالمعرف نفسہ event id؛ ومن دون idempotency key یمکن لکودک أن یسترد أو یخصم مرتین.

مکدس الوکیل والبروتوکولات المجاورة

• تجارة الوکلاء. أی معاملة یکون فیہا وکیل ذکاء اصطناعی مستقل ہو المشتری أو البائع أو الاثنین معا، من دون إنسان یضغط زر الشراء فی تلک اللحظة. تختلف عن التسوق "المساعد بالذکاء الاصطناعی" حیث یبقی الشخص ہو من یضغط الزر.
• عدة OpenAI Agents SDK. عدة Python/JavaScript لبناء حلقات وکلاء باستخدام Agent وRunner.run() و@function_tool وحواجز الأمان. فی ہذہ الدورة ہو "العمیل الموحد": یصبح کل بروتوکول دفع أداة واحدة أو أکثر یستطیع الوکیل استدعاءہا.
• معیار MCP (Model Context Protocol). معیار Anthropic المفتوح لتعریض الأدوات والسیاق للوکلاء. فی تجارة الوکلاء یکون غالبا طبقة الاکتشاف: تعثر الوکلاء علی الخدمات القابلة للشراء عبر خوادم MCP. مرخص MIT.
• بروتوکول A2A (Agent2Agent). بروتوکول Google لتخاطب الوکلاء واکتشاف بعضہم. یبنی AP2 فوق A2A: ینتقل التفویض کرسالة A2A. ترخیصہ Apache 2.0.
• بروتوکول UCP (Universal Commerce Protocol). بروتوکول طبقة التجارة من Google، النظیر ل ACP، ومبنی حول واجہات التسوق لدی Google (Gemini وGoogle AI Mode). ینافس ACP فی طبقة التجارة.
• بروتوکول TAP (Trusted Agent Protocol). بروتوکول Visa وCloudflare لإثبات ہویة الوکیل داخل ترویسات طلب HTTP. یثبت من ہو الوکیل لا ما المسموح لہ بإنفاقہ، لذلک یضاف عادة إلی بروتوکول مصادقة آخر بدلا من أن یحل محلہ.
• معیار ERC-8004. معیار علی السلسلة لہویة الوکلاء وسمعتہم: سجل عام للوکلاء مع تاریخ معاملاتہم، حتی یستطیع وکیل لا تربطہ علاقة سابقة أن یفحص سجل وکیل آخر قبل الوثوق بہ.
• tool_input_guardrail. حاجز أمان فی OpenAI Agents SDK یعمل قبل تنفیذ الأداة ویمکنہ رفض الاستدعاء. إنہ طریقة SDK الأصلیة لإیقاف الدفع قبل حدوثہ. وہو عمود ہذہ الدورة: یظہر فی سبع أدوات دفع. (قارن ذلک ب output_guardrail، الذی یعمل علی الرد النہائی للوکیل، أی بعد فوات الأوان لإیقاف الدفع.)

المتطلبات السابقة

ستستفید من ہذہ الدورة أکثر إذا کان لدیک:

1. الدورة المکثفة فی بناء وکلاء الذکاء الاصطناعی، أو خبرة مکافئة فی SDK. تعرض تکاملات البروتوکولات علی شکل کود SDK، لذلک تحتاج إلی قراءة Agent وRunner.run() و@function_tool براحة. راجع الدورة المکثفة فی بناء وکلاء الذکاء الاصطناعی.
2. الدورة المکثفة فی اختیار المعماریات الوکیلة، أو حس تصمیم مکافئ. یبنی إطار "أی ترکیب لأی حالة استخدام" فی الجزء 5 علی انضباط اختیار الأنماط. راجع الدورة المکثفة فی اختیار المعماریات الوکیلة.
3. أساسیات HTTP. رموز الحالة، ودورة الطلب/الاستجابة، والترویسات. یعمل x402 خصوصا علی مستوی HTTP.
4. مفردات دفع أساسیة. التاجر، والتسویة، والنزاع، وchargeback. تشرح الدورة الأجزاء الخاصة بالوکلاء، لکنہا تفترض أنک تعرف معنی "merchant of record".

لا تحتاج إلی خبرة blockchain أو smart-contract (تعلّمک الدورة ما یکفی من x402 وEIP-3009 للمتابعة؛ لا Solidity)، ولا تحتاج إلی خبرة سابقة بأی من البروتوکولات الأربعة. ستتعلمہا کلہا من المصادر الأولیة.

مسارات التعلم الأربعة

تعمل ہذہ الدورة علی أربعة أعماق. اختر مسارک قبل الجزء 5.

المسار	الوقت	ما ستفعلہ	الأنسب لہ
القارئ	2-3 ساعات	اقرأ کل المفاہیم والقرارات، وتجاوز تشغیل الکود.	مہندسون یقررون ہل یستثمرون بعمق أکبر. ومدیرو منتجات ومعماریون یحتاجون الإطار لتقییم عروض الموردین.
المبتدئ	نحو یوم	مسار القارئ مع تشغیل أمثلة عمیل x402 ومعاملة ACP اختباریة واحدة فی Stripe test mode.	مہندسون جدد فی تجارة الوکلاء یریدون وقتا عملیا مع أبسط بروتوکول (x402) وأکثرہا جاہزیة للإنتاج (ACP).
المتوسط	2-3 أیام	مسار المبتدئ مع بناء وکیل یستخدم ACP لنوع من المعاملات وx402 لنوع آخر، ومع ربط فحوص Intent Mandate من AP2.	مہندسون یطلقون نظاما حقیقیا علیہ ترکیب عدة بروتوکولات.
المتقدم	4-5 أیام	مسار المتوسط مع تشغیل النظام المرکب بمتانة (غلاف Inngest)، وربط حدود الإنفاق وبوابات موافقة الإنسان، وقیاس مقاییس trace والکلفة والنزاعات، والتعامل مع دورة استرداد کاملة.	مہندسون مسؤولون عن أنظمة إنتاج تنقل مالا حقیقیا لمستخدمین حقیقیین.

اختبار ذاتی مفید: "فی حالة الاستخدام التی أفکر فیہا، ما أصغر ترکیب بروتوکولات یطلق قیمة؟" إذا لم تستطع الإجابة بعد الجزء 4، فأعد قراءة الجزء 4. وإذا استطعت، فمسارک یصبح مجرد سؤال: إلی أی مدی ترید الانتقال من "أصغر ترکیب" إلی "ترکیب صالح للإنتاج"؟

مکدس الطبقات الأربع

ہذا ہو المخطط الذی یتعلق بہ کل شیء بعدہ.

تلمس کل حالة استخدام فی تجارة الوکلاء الطبقات الأربع کلہا، لکن الحالات المختلفة ترکب بروتوکولات مختلفة فی کل طبقة. وکیل تسوق للمستہلک: MCP للاکتشاف، ورمز دفع مشترک من ACP للتفویض، وACP للتجارة، وسکک البطاقات للتسویة. وکیل یدفع مقابل API: دلیل وکلاء للاکتشاف، وتوقیع EIP-3009 للتفویض، ولا طبقة تجارة إطلاقا، وx402 للتسویة. وکیل مشتریات مؤسسة: دلیل A2A، وتفویض AP2، وACP أو UCP للتجارة، وStripe MPP للتسویة. القاعدة بسیطة: اختر بروتوکولا واحدا لکل طبقة، واجعل حالة الاستخدام تبرر کل اختیار.

الجزء 1: لماذا تحتاج تجارة الوکلاء إلی بروتوکولات جدیدة

ہل تقرأ الجزء 1 قراءة خفیفة؟

یقدم الجزء 1 ستة أسماء (ACP وAP2 وx402 وMPP وMCP وA2A) وثلاث طبقات بسرعة. ہذا مقصود: ہذا الجزء ہو موجز تمہیدی لا غوص عمیق. الحد الأدنی الذی تحتاج إلی حملہ: ACP ہو تسوق المستہلک (Stripe مع OpenAI)، وAP2 ہو تفویضات authorization (Google مع أکثر من 60 شریکا)، وx402 ہو دفع عملة مستقرة لکل طلب عبر HTTP (Coinbase)، وMPP ہو دفع متعدد السکک قائم علی الجلسات (Stripe مع Tempo). أما MCP وA2A فہما کیف تعثر الوکلاء علی بعضہا وتتخاطب، ولیسا بروتوکولی دفع. احمل الأسماء بخفة. یعود الجزء 2 إلی کل واحد منہا بعمق، وستثبت فی القراءة الثانیة.

المفہوم 1: الافتراض الذی انکسر

فی سطر واحد: افترضت أنظمة الدفع أن إنسانا یضغط زر الشراء، ویکسر الوکلاء ہذا الافتراض بثلاث طرق معا.

بنیت أنظمة الدفع علی افتراض ہادئ واحد: إنسان یجلس أمام لوحة المفاتیح ویضغط الشراء. کل شاشة، وکل فحص احتیال، وکل عملیة نزاع، وکل نموذج تسجیل صمم للبشر. تکسر وکلاء الذکاء الاصطناعی ہذا الافتراض بثلاث طرق فی الوقت نفسہ.

الکسر 1: لا تملک الوکلاء عناوین برید إلکترونی. ترید تدفقات الدفع الاستہلاکیة حسابا. والحساب یرید بریدا إلکترونیا ورقم ہاتف، وغالبا اسما. لا یملک الوکیل المستقل أیا من ذلک. إذا زورتہا، فقد أنشأت کیانا یفشل فی KYC لحظة نظر اکتشاف الاحتیال إلیہ. یفترض تدفق التسجیل إنسانا یتقدم لعلاقة؛ أما الوکیل فیحتاج إلی شیء آخر.

الکسر 2: تعمل الوکلاء آلاف المرات فی الثانیة. ترصد أنظمة الاحتیال السلوک الغریب بالمعدل والموقع والنمط. یبدو وکیل یجری 1,000 استدعاء API فی دقیقة واحدة کأنہ ہجوم credential-stuffing تماما. ما ہو طبیعی للوکیل إنذار للإنسان، والسکک مضبوطة للبشر.

الکسر 3: لا تستطیع الوکلاء رفع الہاتف. تفترض تسویة النزاعات إمکانیة الوصول إلی المشتری: "ہل فوّضت ہذا؟" الوکیل الذی فوّض رسما لا یستطیع الرد، وقد لا یعرف الإنسان خلفہ أن الرسوم حدثت أصلا. تحتاج النزاعات إلی نموذج مختلف عندما یکون المشتری برمجیات.

یحتاج کل کسر إلی إصلاح علی مستوی البروتوکول، لا إلی طبقة طلاء علی واجہة المستخدم:

الکسر	ما لا یستطیع إصلاح السکة البشریة فعلہ	ما یعطیک إیاہ إصلاح سکة الوکلاء
لا برید ولا حساب	إجبار الوکلاء علی إنشاء حسابات مزیفة	ہویة تشفیریة (TAP وERC-8004) أو رموز محددة النطاق (ACP SPT وAP2 Mandate)
سلوک عالی التکرار	حجب حرکة مرور تشبہ الہجوم	دفع أصیل فی HTTP لکل طلب (x402) أو جلسات مفوضة مسبقا (MPP)
لا ہاتف للنزاعات	إرسال نزاعات بالبرید لا یستطیع الوکیل قراءتہا	تفویض قائم علی mandates (AP2) مع مسار تدقیق غیر قابل للإنکار

فشل مسار "غلف المدفوعات القدیمة بتجربة وکیل أجمل" بالفعل. جرّبت عدة شرکات ناشئة فی 2024 و2025 أن تعطی الوکلاء حسابات تشبہ حسابات البشر بہویات مخترعة. قبضت علیہا أنظمة کشف الاحتیال، وتراکمت chargebacks، وانہارت علاقات التجار. اتضح أن إصلاحات مستوی البروتوکول مطلوبة لا اختیاریة. لذلک ظہرت ACP وAP2 وx402 وMPP کلہا خلال الاثنی عشر شہرا نفسہا.

خلاصة المفہوم 1: افترضت أنظمة الدفع أن إنسانا یضغط الشراء. یکسر الوکلاء ذلک بثلاث طرق: لا ہویة تقلیدیة، وأنماط سلوک مقلقة، ولا قناة لتوضیح النزاع. یحتاج کل کسر إلی إصلاح علی مستوی البروتوکول. فشل تغلیف السکک القدیمة بتجربة مستخدم أجمل. تغطی البروتوکولات الأربعة مزیجا مختلفا من ہذہ الکسور.

المفہوم 2: لماذا لا یستطیع بروتوکول واحد الفوز

فی سطر واحد: تحدث الکسور فی أربع طبقات مختلفة مع أربعة أصحاب نفوذ مختلفین، لذلک قسمت البروتوکولات العمل حسب الطبقة بدلا من أن یبتلع واحد منہا کل شیء.

سؤال عادل: إذا ظہرت البروتوکولات الأربعة کلہا لإصلاح الکسور الثلاثة نفسہا، فلماذا لم یفز واحد منہا ببساطة؟ الإجابة بنیویة. تقع الکسور فی طبقات مختلفة، والبروتوکول الواحد الذی یحاول إصلاحہا کلہا سیکون أکبر من أن یتبناہ أحد.

فکر فی ما کان یجب أن یحددہ بروتوکول موحد واحد:

1. کیف تعثر الوکلاء علی التجار والخدمات المتاحة. ہذہ ہی طبقة الاکتشاف.
2. کیف تثبت الوکلاء من ہی وأن إنسانا فوّض الإنفاق. ہذہ ہی طبقة التفویض.
3. کیف تدیر الوکلاء شراء کاملا، بما فی ذلک النزاعات والاستردادات. ہذہ ہی طبقة التجارة.
4. کیف یتحرک المال فعلا بین الأطراف. ہذہ ہی طبقة التسویة.

لکل طبقة أصحاب نفوذ أقویاء بالفعل. الاکتشاف لمحرکات البحث وواجہات API. والہویة ل OAuth وسلطات الشہادات. والتجارة ل Stripe وAdyen وShopify. والتسویة ل Visa وMastercard وACH، إضافة إلی سکک crypto الجدیدة. کان بروتوکول موحد سیحتاج إلی اتفاق کل صاحب نفوذ فی کل طبقة. لم یکن ذلک سیحدث.

ما حدث بدلا من ذلک ہو أن کل بروتوکول اختار الطبقة التی یملک راعیہ فیہا أکبر نفوذ:

البروتوکول	أین یملک راعیہ النفوذ	الطبقة التی أخذہا
ACP	تملک OpenAI قناة التسوق (ChatGPT)؛ وتملک Stripe تکامل التجار	التجارة، لتدفقات مشتری بشری عبر ذکاء اصطناعی
AP2	لدی Google محافظ Android وتحالف من 60 شریکا	التفویض، mandates کبیانات اعتماد موقعة
x402	لدی Coinbase بنیة عملات مستقرة؛ ولدی Cloudflare حافة HTTP	التسویة، لمدفوعات صغیرة بین الآلات
MPP	لدی Stripe علاقات التجار؛ ولدی Tempo blockchain	التسویة، لتدفقات المؤسسات ومتعددة السکک

لذلک لا تتقاتل البروتوکولات داخل طبقة؛ بل تتنافس علی تعریف طبقة. فی التسویة، یتنافس x402 وMPP فعلا، وتفوت معظم مقالات "x402 ضد MPP" أن ہذا ہو المکان الوحید الذی یتداخلان فیہ حقا. وفی التجارة، یتنافس ACP وUCP. وفی التفویض، تتنافس AP2 وTAP وERC-8004.

وہنا تصل الفکرة التی تقوم علیہا الدورة کلہا. داخل الطبقة، تختار بروتوکولا واحدا. وعبر الطبقات، ترکب عدة بروتوکولات. البروتوکولات الأربعة لیست بدائل تختار بینہا؛ إنہا طبقات ترصہا. وکیل تسوق للمستہلک یشغّل ACP فی التجارة وسکک البطاقات فی التسویة. وکیل یدفع ل API یشغّل x402 فی التسویة ویتجاوز التجارة کلیا. وکیل مؤسسة یشغّل تفویضات AP2 فی التفویض وMPP فی التسویة. تمشی شجرة القرار فی الجزء 5 طبقة بطبقة. تمسک بہذہ الفکرة: کل قسم بعد ہذا یفترضہا.

خلاصة المفہوم 2: لا یستطیع بروتوکول واحد إصلاح الکسور الأربعة کلہا لأن الکسور تعیش فی أربع طبقات، ولکل طبقة أصحاب نفوذ أقویاء. تتخصص البروتوکولات: ACP فی التجارة، وAP2 فی التفویض، وx402 وMPP فی التسویة. داخل الطبقة تختار واحدا؛ وعبر الطبقات ترکب عدة بروتوکولات.

المفہوم 3: OpenAI Agents SDK بوصفہ العمیل الموحد

فی سطر واحد: لا تتعامل مع أربعة بروتوکولات بأربع طرق مختلفة؛ یصبح کل بروتوکول أداة یستدعیہا الوکیل، ویکون SDK ہو العمیل الواحد الذی یربطہا کلہا.

السؤال العملی: مع أربعة بروتوکولات فی أربع طبقات، کیف یستخدمہا الوکیل فعلا؟ الإجابة فی 2026 ہی أن إطار عمل الوکیل یصبح العمیل الموحد. یعرّض کل بروتوکول SDK أو نقطة نہایة HTTP، ویربطہ إطار العمل کأداة. ہذا صحیح فی OpenAI Agents SDK وLangGraph وAutoGen وCrewAI علی السواء. سنستخدم OpenAI Agents SDK طوال الدورة.

بالنسبة إلی SDK، یتبع کل تکامل بروتوکول الشکل نفسہ: غلف البروتوکول فی دالة واحدة أو أکثر من دوال @function_tool، ومررہا إلی Agent، ودع Runner.run یقود الحلقة.

استدعاءات stripe.PaymentTokens.create وX402Client(wallet=...) وfrom ap2 import ... أدناہ توضیحیة: تبین شکل تکامل البروتوکول. أما طبقة Agent وRunner و@function_tool حولہا فہی حقیقیة وتعمل. راجع الملاحظة بعد الکتلة لمعرفة ما ہو بدیل تعلیمی.

from agents import Agent, Runner, function_tool
import stripe  # for ACP/MPP
from x402_client import X402Client  # for x402
from ap2 import IntentMandate, CartMandate  # for AP2
from decimal import Decimal
from .models import PaymentToolResult, X402PaymentResult  # the shared result models

# Each protocol becomes one or more @function_tool decorated functions
@function_tool
async def acp_checkout(merchant_id: str, items: list, max_amount: Decimal) -> PaymentToolResult:
    """Complete an ACP checkout at a merchant with the given items."""
    # Mint a one-time payment token scoped to this merchant, then POST the order
    spt = stripe.PaymentTokens.create(
        amount=int(max_amount * 100),   # cents as int
        currency="usd",
        merchant_id=merchant_id,
        max_uses=1,
    )
    response = await acp_post(merchant_id, items, spt.token)
    return PaymentToolResult(
        status="success" if response.status == "confirmed" else "failed",
        details={"order_id": response.order_id, "merchant_status": response.status},
    )

@function_tool
async def x402_fetch(url: str, max_payment_usdc: Decimal) -> X402PaymentResult:
    """Fetch a URL that may require x402 payment up to max_payment_usdc."""
    client = X402Client(wallet=agent_wallet, max_per_request=max_payment_usdc)
    response = await client.get(url)
    return X402PaymentResult(
        content=response.content,
        amount_paid_usdc=response.amount_paid_usdc,
        tx_hash=response.payment_proof,
    )

# Compose the tools into an agent
shopping_agent = Agent(
    name="ShoppingAgent",
    instructions="Help the user find and purchase items. Use acp_checkout for retail goods, x402_fetch for paid APIs.",
    tools=[acp_checkout, x402_fetch],
    model="gpt-5.5",
)

# Run the agent. The SDK handles tool selection, the loop, and retries.
result = await Runner.run(shopping_agent, "Buy me a red t-shirt under $30")

ما یعمل وما ہو بدیل ہنا: ربط Agent وRunner.run و@function_tool ہو SDK الحقیقی ویعمل کما ہو مکتوب. عملاء الدفع بدائل تعلیمیة. stripe.PaymentTokens.create لیس استدعاء Stripe حقیقیا (یدمج ACP فی الإنتاج عبر نقاط نہایة Stripe ACP الحیة)، والبانی الغنی X402Client(wallet=..., max_per_request=...) توضیحی أیضا. الحزمة الحقیقیة من جہة المشتری ہی x402-client، والاستدعاء الحی یحتاج إلی حساب ممول ونقطة نہایة 402 حقیقیة، وہو ما لا تفعلہ ہذہ الدورة. یعطی الجزء 3 لکل بروتوکول خلفیة mock قابلة للتشغیل حتی تری الغلاف یعمل من البدایة إلی النہایة من دون نقل مال حقیقی.

الشکل متطابق عبر البروتوکولات الأربعة کلہا. SDK ہو العمیل الموحد؛ کل بروتوکول لیس إلا أداة یفکر فیہا الوکیل ویستدعیہا عندما یحتاج إلیہا. تہم ثلاثة أجزاء من بنیة SDK للمدفوعات:

1. قیمة إرجاع ذات نوع محدد لنتائج الدفع. عندما ترجع أداة الدفع نموذج Pydantic، یحصل مستدل الوکیل علی معلومات نوعیة نظیفة عن ما نجح، وما فشل، وما الخطوة التالیة. یعرّف الجزء 3 نماذج النتائج المشترکة ہذہ مرة واحدة.
2. Runner.run(..., context=...) لسیاق الدفع. یحتاج الوکیل غالبا إلی ہویة المستخدم، وحدود الإنفاق، ومقبض المحفظة. مرر ہذہ عبر معامل context فی SDK بدلا من حشرہا فی التعلیمات. context خاص بکل تشغیل وبکل مستخدم.
3. tool_input_guardrail لحدود الإنفاق. یعمل حاجز إدخال الأداة قبل تنفیذ کل أداة ویمکنہ رفض الاستدعاء. إنہا طریقة SDK الأصلیة لحجب الدفع قبل حدوثہ، لا بعدہ. یشرح المفہوم 15 فرض الحدود علی ثلاثة مستویات. لا یحل output_guardrail علی مستوی الوکیل ہذہ المشکلة، لأنہ یعمل علی الرد النہائی للوکیل بعد أن تکون أی أداة دفع قد عملت بالفعل.

خلاصة المفہوم 3: OpenAI Agents SDK ہو العمیل الموحد للبروتوکولات الأربعة کلہا. یصبح کل واحد منہا دالة @function_tool یستدعیہا الوکیل. تتطابق قیم الإرجاع ذات الأنواع، وcontext، وtool_input_guardrail فی SDK مع قضایا الدفع: نتائج منظمة، وسیاق لکل مستخدم، وإیقاف الدفع قبل حدوثہ. شکل التکامل واحد عبر الأربعة؛ والجزء 3 یملأ تفاصیل کل واحد.

---

---

الجزء 2: الطبقات الأربع بعمق

رأیت الطبقات الأربع فی الجزء 1؛ وہنا نقترب من کل واحدة. تجیب کل طبقة عن سؤال مختلف، ولہا بروتوکولات متنافسة خاصة بہا، وتفرض قرارا واحدا: فی حالة الاستخدام ہذہ، أی بروتوکول یناسب الطبقة ہذہ أفضل؟ اقرأ الجزء 2 قبل الجزء 3. framing الطبقات ہنا ہو ما یجعل تفاصیل البروتوکولات فی الجزء 3 متماسکة بدلا من أن تبدو قائمة منافسین.

المفہوم 4: الطبقة 1، الاکتشاف (کیف تعثر الوکلاء علی ما یمکنہا شراءہ)

فی سطر واحد: الاکتشاف ہو المکان الذی یعرف فیہ الوکیل ما ہو متاح أصلا للشراء، والآلیة الصحیحة تعتمد علی مکان وجود تلک الخدمات فعلا.

قبل أن یستطیع الوکیل إجراء معاملة، علیہ أن یعرف ما الموجود. یحتاج وکیل التسوق إلی تجار یحملون المنتج. ویحتاج وکیل یدفع ل API إلی معرفة أی نقاط نہایة لدیہا البیانات وما تکلفتہا. ویحتاج وکیل المشتریات إلی موردین یجتازون قواعد الامتثال. یجیب الاکتشاف عن سؤال "ما المتاح؟"

تتنافس أربعة خیارات جدیة ہنا فی 2026:

البروتوکول	کیف یعمل	الأنسب لہ
MCP (Anthropic)	تعرّض خوادم الأدوات دوالا قابلة للاستدعاء؛ یتصل الوکیل، ویسرد الأدوات، ویستدعیہا	وصول برمجی إلی خدمات محددة ربطہا المطور؛ عمل وکلاء عالی الحجم؛ طبقة اکتشاف أدوات الوکلاء المہیمنة
A2A (Google)	تنشر الوکلاء ما تقدمہ فی أغلفة قیاسیة؛ وتکتشفہا وکلاء أخری	نظم متعددة الوکلاء تحتاج فیہا الوکلاء إلی العثور علی وکلاء نظراء؛ طبقة الاکتشاف التی یوسعہا AP2
أدلة الوکلاء (Agent.market, lobster.cash, Tenzro)	أسواق عامة تسرد واجہات API وخدمات مدفوعة؛ تستعلمہا الوکلاء کفہرس	خدمات طرف ثالث تکتشف فی وقت التشغیل؛ "الصفحات الصفراء" لتجارة الوکلاء
واجہات التسوق بالذکاء الاصطناعی (ChatGPT Instant Checkout, Google AI Mode, Walmart-in-ChatGPT)	منتجات ذکاء اصطناعی استہلاکیة فیہا اکتشاف منتجات مع checkout عبر ACP مدمج	تدفقات المستہلک حیث یتحدث المستخدم إلی الذکاء الاصطناعی وتظہر المنتجات داخلہ

یدعم SDK بروتوکول MCP دعما أصلیا: اربط خادم MCP بوکیل فی بضعة أسطر، وستصبح کل أدواتہ متاحة لاستدلال الوکیل. أما الاکتشاف غیر القائم علی MCP، فغلّفہ کأداة عادیة @function_tool تستعلم الدلیل وترجع قوائم منظمة.

ربط MCPServerStreamableHttp أدناہ حقیقی وقابل للاستیراد. أما استدعاء agent_market_client فہو توضیحی: یمثل عمیل دلیل. وطبقة @function_tool وAgent حقیقیة.

from agents import Agent, function_tool
from agents.mcp import MCPServerStreamableHttp
from decimal import Decimal

# Wire an MCP discovery server: all its tools become available
research_mcp = MCPServerStreamableHttp(
    name="research-services",
    params={"url": "https://research-services.example.com/mcp"},
)

# Wire a non-MCP directory as a regular tool
@function_tool
async def search_agent_market(query: str, max_price_usdc: Decimal) -> list[dict]:
    """Search Agent.market for x402-paid services matching the query."""
    return await agent_market_client.search(query, max_price_usdc=max_price_usdc)

agent = Agent(
    name="ResearchAgent",
    instructions="Find and use research services. Prefer MCP-discovered tools; fall back to Agent.market for niche needs.",
    mcp_servers=[research_mcp],
    tools=[search_agent_market],
)

الخیار ہنا لیس "MCP ضد A2A ضد الأدلة." بل السؤال: أین تعیش خدمات وکیلی فعلا؟ إذا کانت داخل مؤسستک، فاستخدم MCP. وإذا کانت عبر شبکة من وکلاء شرکاء، فاستخدم A2A. وإذا کانت APIs طرف ثالث تکتشف فی وقت التشغیل، فاستخدم الأدلة. وإذا کانت منتجات استہلاکیة، فاستخدم واجہة تسوق بالذکاء الاصطناعی (ومعہا ACP فی طبقة التجارة). ہذہ لیست خیارات متنافیة؛ الوکیل الحقیقی یستخدم عدة خیارات غالبا.

خلاصة المفہوم 4: یجیب الاکتشاف عن "ما المتاح؟" تتنافس أربعة خیارات: MCP لخوادم الأدوات الداخلیة، وA2A للنظم متعددة الوکلاء، والأدلة لخدمات الطرف الثالث، وواجہات الذکاء الاصطناعی للمنتجات الاستہلاکیة. یدعم SDK بروتوکول MCP أصلیا ویربط الباقی کدوال @function_tool. اختر بناء علی مکان وجود الخدمات؛ فہی لیست متنافیة.

المفہوم 5: الطبقة 2، الہویة والتفویض (إثبات أن الوکیل مسموح لہ)

فی سطر واحد: التفویض ہو المکان الذی یثبت فیہ الوکیل أن الإنسان سمح بہذا الإنفاق وأن الوکیل ہو من یدعی أنہ ہو، قبل انتقال أی مال.

قبل أن یتحرک المال، یجب أن یکون شیئان صحیحین: أن الوکیل ہو من یدعی أنہ ہو، وأن الإنسان فوّض ہذا الإنفاق. ہاتان مشکلتان مختلفتان بحلول مختلفة، وتحسم الطبقة 2 الاثنین قبل حدوث التسویة. إذا تجاوزت الطبقة 2، تحصل علی أحد فشلین: احتیال (یستطیع وکیل أی شخص إنفاق مال أی شخص) أو شلل (تحتاج کل معاملة إلی إنسان یضغط تأکید).

ہذہ ہی أکثر طبقة متنازع علیہا فی 2026. أربعة خیارات، وأربع فلسفات:

البروتوکول	کیف یعمل	أقوی موضع لہ
AP2 Mandates (Google)	بیانات اعتماد موقعة: Intent Mandate ("اشتر حذاء بأقل من 120 دولارا")، وCart Mandate ("ہذہ السلة، ہذا السعر")، وPayment Mandate ("فوّض ہذہ السکة")	تدفقات کثیفة التدقیق تحتاج إلی إثبات موافقة غیر قابل للإنکار؛ تدفقات متعددة الوکلاء حیث لم یر التاجر وکیل المشتری من قبل
ACP SPT (OpenAI plus Stripe)	تصدر Stripe رمزا Shared Payment Token محدد النطاق لتاجر واحد ومبلغ ونافذة زمنیة؛ یقدمہ الوکیل؛ ویتحقق منہ التاجر ویخصم	تسوق المستہلک حیث تکون Stripe ہی المعالج وتحمل سکک البطاقات انضباط chargeback
TAP (Visa plus Cloudflare)	یرکب توقیع ہویة الوکیل فی ترویسات HTTP؛ ویتحقق التجار منہ عبر دلیل Visa	التحقق من الہویة تحدیدا (لا التفویض)؛ یضاف عادة إلی بروتوکول مصادقة آخر ولا یستخدم وحدہ
ERC-8004 plus on-chain reputation	سجل علی السلسلة لہویات الوکلاء وتاریخ المعاملات، مع درجة سمعة من صفقات سابقة	تدفقات متعددة الوکلاء خالصة بلا ثقة سابقة؛ B2B عالی المخاطر حیث تستحق السمعة الفحص

السؤالان اللذان یجب أن تجیب عنہما الطبقة 2، وکیف یجیب کل بروتوکول:

1. "ہل فوّض الإنسان ہذا؟" یجیب AP2 بتفویض وقّعہ المستخدم قبل التفویض. ویجیب ACP ب SPT أصدرتہ Stripe فقط بعد أن فوّض المستخدم علی مستوی الحساب. لا یجیب TAP عن ہذا؛ فہو للہویة فقط. ویجیب ERC-8004 بمعاملات موقعة علی السلسلة.
2. "ہل الوکیل ہو من یدعی أنہ ہو؟" یجیب AP2 بمفتاح التوقیع (لا یستطیع التوقیع إلا الوکیل الحقیقی). ویجیب ACP بأن SPT محدد للتاجر (لا یستطیع استردادہ إلا التاجر المصرح). ویجیب TAP بفحص دلیل Visa. ویجیب ERC-8004 بسجل الہویة علی السلسلة.

یعطیک SDK نقطتی تکامل: حاجز إدخال أداة یعمل قبل أداة الدفع، وسیاق التشغیل الذی یحمل حالة کل مستخدم إلیہما معا.

حاجز الأمان و@function_tool وربط Agent أدناہ من SDK الحقیقی وتعمل (مسارات الخصائص data.context.tool_arguments وdata.context.context مؤکدة مقابل SDK المثبت). أما استدعاء stripe.PaymentTokens.create داخل الأداة فہو توضیحی؛ یستخدم ACP فی الإنتاج نقاط نہایة Stripe ACP الحیة.

from agents import Agent, function_tool, RunContextWrapper
from agents.tool_guardrails import (
    tool_input_guardrail,
    ToolInputGuardrailData,
    ToolGuardrailFunctionOutput,
)
from decimal import Decimal
import json
import stripe

# Pattern 1: a tool input guardrail. Runs BEFORE the payment tool executes.
# This is the SDK-native way to block a payment before it happens.
@tool_input_guardrail
def block_over_user_cap(data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
    """Reject any payment tool call where the request would exceed the user's per-run cap."""
    args = json.loads(data.context.tool_arguments or "{}")          # raw JSON args -> dict
    requested = Decimal(str(args.get("max_amount_usd", 0)))
    ctx = data.context.context                                       # the run context (a dict)
    user_cap = Decimal(str(ctx["user_session"].per_run_spend_cap_usd))
    run_spent = Decimal(str(ctx.get("run_spend_usd", 0)))
    if run_spent + requested > user_cap:
        return ToolGuardrailFunctionOutput.reject_content(
            f"Refusing payment tool: would spend ${run_spent + requested}, exceeds run cap ${user_cap}"
        )
    return ToolGuardrailFunctionOutput.allow()

# Pattern 2: the payment tool itself, guarded at the function-tool level
@function_tool(tool_input_guardrails=[block_over_user_cap])
async def purchase_with_acp(
    ctx: RunContextWrapper,
    merchant_id: str,
    items: list,
    max_amount_usd: Decimal,
) -> PaymentToolResult:
    """Use ACP to buy items from the merchant up to max_amount_usd.
    The guardrail has already verified spend is within bounds before we reach here."""
    user_session = ctx.context["user_session"]
    spt = stripe.PaymentTokens.create(
        amount=int(max_amount_usd * 100),   # Stripe expects cents as int
        currency="usd",
        merchant_id=merchant_id,
        user_session_id=user_session.id,
        max_uses=1,
    )
    response = await acp_post(merchant_id, items, spt.token)
    return PaymentToolResult(
        status="success" if response.status == "confirmed" else "failed",
        details={"order_id": response.order_id, "merchant_status": response.status},
    )

agent = Agent(
    name="ShoppingAgent",
    instructions="Help the user shop. Always verify authorization before any purchase.",
    tools=[purchase_with_acp],
    # No output_guardrails for spend control. Those run on the agent's FINAL output,
    # not on individual tool calls. See Concept 15 for the full three-level enforcement.
)

أی حاجز أمان یوقف الدفع؟

لدی SDK ثلاثة أنواع من حواجز الأمان وتعمل فی لحظات مختلفة. یعمل input_guardrail علی إدخال المستخدم الأول إلی الوکیل. ویعمل output_guardrail علی رد الوکیل النہائی للمستخدم. أما tool_input_guardrail وtool_output_guardrail فیعملان علی کل استدعاء function-tool، قبل تنفیذہ وبعدہ. لسلامة الدفع تحتاج إلی حاجز إدخال الأداة: یعمل قبل أن تعمل أداة الدفع ویمکنہ رفض الاستدعاء. أما حاجز الإخراج فیعمل متأخرا جدا لإیقاف الدفع؛ یفید فی تنظیف الرد النہائی (مثلا حجب بیانات حساسة)، لا فی حجب أداة. یعود المفہوم 15 إلی ذلک؛ فہذا ہو الخطأ الأکثر شیوعا.

ینتہی اختیارک ہنا إلی نموذج الثقة. إذا کان المستخدم مسجلا فی تطبیقک وتستطیع إصدار SPTs عبر Stripe، یعطیک ACP القصة الأکثر جاہزیة للإنتاج. وإذا کنت تحتاج إلی مسارات تدقیق غیر قابلة للإنکار، کما فی الصناعات المنظمة أو مشتریات B2B، تناسبک تفویضات AP2. وإذا کنت تحتاج إلی ہویة تشفیریة وحدہا، منفصلة عن التفویض، فأضف TAP. وفی بیئة متعددة الوکلاء خالصة بلا ثقة مشترکة، یملأ ERC-8004 الفجوة. ہذہ لیست بدائل قابلة للتبادل.

خلاصة المفہوم 5: یجیب التفویض عن سؤالین: "ہل فوّض الإنسان ہذا؟" و"ہل الوکیل ہو من یدعی أنہ ہو؟" تتنافس أربعة بروتوکولات: تفویضات AP2 (تدقیق کثیف)، وACP SPT (أصلی ل Stripe)، وTAP (ہویة فقط)، وERC-8004 (ثقة متعددة الوکلاء). یندمج SDK عبر سیاق التشغیل لفحوص کل أداة وtool_input_guardrail (الذی یعمل قبل کل أداة ویمکنہ رفضہا) لحدود الإنفاق. اختر بناء علی نموذج الثقة.

المفہوم 6: الطبقة 3، التجارة (دورة حیاة الشراء الکاملة)

فی سطر واحد: التجارة ہی کل شیء فی الشراء الحقیقی لیس تفویضا ولا تسویة: السلة، والطلب، والتنفیذ، والنزاع، والاسترداد؛ أما استدعاء API البسیط فیتجاوزہا کلیا.

یغطی التفویض والتسویة معا "ینتقل المال بإذن." أما التجارة فتغطی کل شیء آخر فی الشراء: السلال المنظمة، وتأکید الطلب، وتتبع التنفیذ، وتسویة النزاعات، والاستردادات، وchargebacks، والإرجاعات. ہذہ ہی الطبقة التی تفصل checkout عن تحویل المال. استدعاء API بسیط بین الآلات لا یحتاج إلی طبقة تجارة؛ إنہ مجرد استدعاء API. أما شراء المستہلک فیحتاج إلیہا بوضوح.

ثلاثة خیارات مختلفة فعلیا:

البروتوکول	ما یفعلہ	الأنسب لہ
ACP (OpenAI plus Stripe)	تدفق منظم: صیغة السلة، وتأکید الطلب، وحالة التنفیذ، وتصعید النزاع، والاستردادات. یبقی التاجر merchant of record.	تسوق المستہلک: سلع تجزئة، واشتراکات، وتنفیذ مادی. یشغّل ChatGPT Instant Checkout.
UCP (Google)	دورة حیاة مشابہة، مبنیة حول واجہات التسوق فی Google (Gemini وGoogle AI Mode) وGoogle Pay	تجار Google Shopping؛ ووکلاء علی واجہات Google AI
Direct API (machine-to-machine)	لا بروتوکول تجارة إطلاقا، مجرد HTTP API. الدفع عبر x402 أو MPP. لا سلة ولا نزاعات ولا استردادات.	وصول API، وحوسبة، وتدفقات بیانات: مشتریات یکون الشیء المشتری فیہا استجابة API عدیمة الحالة

إذن یتنافس ACP وUCP؛ أما "API مباشر" فہو غیاب ہذہ الطبقة، لا منافس ثالث، وغالبا یجلس سعیدا إلی جانب لا شیء. تختار منصة المستہلک ACP أو UCP (أو الاثنین إذا امتدت عبر ChatGPT وGemini). ولا تختار سوق API شیئا فی ہذہ الطبقة إطلاقا، لأن مشتریاتہا لا تملک دورة حیاة تدیرہا.

الجزء الذی یستخف بہ معظم المہندسین ہو الاستردادات والنزاعات. العمیل الذی یطلب قمیصا بمقاس خاطئ یتوقع أن یرجعہ. یجب أن یقول بروتوکول التجارة کیف یبدأ الإرجاع، وکیف یسمع الوکیل عنہ، وکیف یعود الاسترداد عبر التسویة. یفعل ACP ذلک جیدا بإبقاء التاجر merchant of record: تعمل آلیات النزاع القائمة (تدفقات chargeback فی Stripe، وسیاسة الإرجاع لدی البائع) کما ہی. وتفشل الطرق المباشرة ل API غالبا لأنہا تتجاہل ذلک. لا یوجد مسار استرداد غالبا، وہذا مقبول فی استدعاء API بقیمة 0.0001 دولار، وخاطئ فی رصید API بقیمة 500 دولار.

تحتاج تدفقات التجارة عادة إلی عدة أدوات تعمل بالتسلسل:

استدعاءات acp_client أدناہ توضیحیة؛ تمثل خلفیة تجارة ACP. نماذج Pydantic و@function_tool وربط Agent حقیقیة.

from agents import Agent, function_tool
from pydantic import BaseModel
from decimal import Decimal

class CartItem(BaseModel):
    sku: str
    quantity: int
    unit_price: Decimal

class OrderResult(BaseModel):
    order_id: str
    status: str  # "confirmed", "fulfilled", "shipped", "delivered"
    tracking_url: str | None = None
    estimated_arrival: str | None = None

@function_tool
async def acp_create_cart(merchant_id: str, items: list[CartItem]) -> PaymentToolResult:
    """Create a cart at an ACP merchant. Does NOT charge yet."""
    cart = await acp_client.cart.create(merchant_id=merchant_id, items=items)
    return PaymentToolResult(
        status="success",
        details={"cart_id": cart.id, "merchant_id": merchant_id, "item_count": len(items)},
    )

@function_tool
async def acp_checkout(cart_id: str, spt_token: str) -> OrderResult:
    """Complete the checkout for a previously-created cart."""
    return await acp_client.checkout.complete(cart_id=cart_id, spt_token=spt_token)

@function_tool
async def acp_check_order_status(order_id: str) -> OrderResult:
    """Get the current status of an order. The agent calls this to follow up."""
    return await acp_client.order.status(order_id=order_id)

@function_tool
async def acp_initiate_refund(order_id: str, reason: str) -> RefundResult:
    """Start a refund for an order. Returns refund_id for follow-up."""
    response = await acp_client.refund.create(order_id=order_id, reason=reason)
    return RefundResult(
        refund_id=response.refund_id,
        order_id=order_id,
        status=response.status,
        amount_refunded_usd=response.amount_refunded_usd,
    )

shopping_agent = Agent(
    name="ShoppingAgent",
    instructions="Help the user shop. Create the cart first, confirm items with the user, then check out. Handle refund requests with an ACP refund.",
    tools=[acp_create_cart, acp_checkout, acp_check_order_status, acp_initiate_refund],
)

السؤال الذی تطرحہ ہنا ہو ہل تحتاج حالة الاستخدام إلی دورة حیاة تجارة أصلا. إذا کانت تحتاجہا (سلة، استرداد، نزاع)، فاختر ACP للوصول إلی ChatGPT أو UCP للوصول إلی Google، أو الاثنین. وإذا لم تکن تحتاجہا، فتجاوز ہذہ الطبقة وانتقل مباشرة من التفویض إلی التسویة. الخطآن ہما: فرض بروتوکول تجارة مستہلک علی استدعاء بین آلات (أکثر مما یلزم)، أو تجاوز التجارة فی شراء مستہلک حقیقی ثم إعادة تنفیذ النزاعات بطریقة ردیئة لاحقا (أقل مما یلزم).

خلاصة المفہوم 6: تتعامل التجارة مع دورة حیاة الشراء الکاملة: السلة، وcheckout، والتنفیذ، والنزاع، والاسترداد. یتنافس ACP وUCP علی تدفقات المستہلک؛ ولا یملک الوصول بین الآلات طبقة تجارة أصلا. آلیات الاسترداد والنزاع ہی الثقل الخفی الذی یفصل بروتوکول التجارة الحقیقی عن بروتوکول الدفع فقط. یربط SDK التجارة کسلسلة أدوات (سلة، checkout، حالة، استرداد). اختر بناء علی حالة الاستخدام: دورة حیاة مطلوبة (ACP/UCP) أو متجاوزة (API مباشر).

المفہوم 7: الطبقة 4، التسویة (حین یتحرک المال فعلا)

فی سطر واحد: التسویة ہی موضع انتقال الدولارات فعلا من حیازة إلی أخری، والاختیار یتعلق غالبا باقتصادیات المعاملة.

انقل القیمة من المشتری إلی البائع. کل ما فوق ہذہ الطبقة تنسیق؛ أما التسویة فہی حیث تنتقل الدولارات (أو العملات المستقرة، أو أی وحدة أخری) فعلا. لا یکون الوکیل قد أکمل معاملة إلا عند اکتمال التسویة.

أربعة خیارات جدیة، لکل منہا اقتصادیاتہ وحدودہ:

البروتوکول	کیف یعمل	الاقتصادیات	الأنسب لہ
x402	أصیل فی HTTP؛ یسوی عبر تحویل عملة مستقرة علی Base/Solana/EVM، موقّع ب EIP-3009	gas أقل من سنت، نہائیة خلال 1-2 ثانیة، بلا رسوم بروتوکول	مدفوعات صغیرة بین الآلات؛ تکرار عال وقیمة منخفضة (وصول API، فوترة لکل استدعاء)
MPP	جلسات: یفوض الوکیل سقفا ومدة مسبقا، ثم یبث مدفوعات مقاسة. متعدد السکک (عملة مستقرة علی Tempo، وLightning، وبطاقات)	رسوم Stripe علی سکک البطاقات؛ شبہ صفر علی العملة المستقرة؛ مناسب للاشتراکات	المؤسسات والتدفقات متعددة السکک؛ الاشتراکات المتکررة؛ حالات تحتاج fiat وcrypto فی غلاف واحد
سکک البطاقات (Stripe/Adyen/Worldpay)	Visa وMastercard وAmex عبر Stripe؛ یقدم الوکیل SPT (ACP) أو Payment Mandate (AP2)؛ ویخصم المعالج من البطاقة	نحو 2.9% زائد 0.30 دولار للبطاقات؛ آلیات نزاع راسخة	تدفقات المستہلک؛ معاملات فیہا تعرض ل chargeback؛ قبول بطاقات دولی
تحویل بنکی / Lightning	ACH وSEPA وBitcoin Lightning	ACH نحو 0.25 دولار ثابت؛ Lightning أقل من سنت؛ SEPA نحو 0.20 یورو	تدفقات عالیة القیمة حیث تؤلم رسوم البطاقة 2.9%؛ مدفوعات صغیرة عابرة للحدود عبر Lightning

یتعلق اختیار التسویة غالبا بالمال. تذہب المدفوعات دون الدولار إلی x402، حیث gas العملة المستقرة أقل من سنت. وتذہب مشتریات المستہلک حتی نحو 1,000 دولار إلی سکک البطاقات عبر ACP، حیث تستحق حمایة chargeback رسوم 2.9%. وتذہب الاشتراکات المتکررة إلی جلسات MPP. وتذہب تحویلات B2B الکبیرة إلی السکک البنکیة أو Lightning. کما أن الطبقات الأعلی تفرض الاختیار عادة: ACP فی التجارة یعنی غالبا سکک البطاقات فی التسویة؛ وخادم MCP المحجوب ب x402 فی الاکتشاف یعنی غالبا x402 فی التسویة.

انتبہ لفخ الأرقام العنوانیة. قد تضلل المقالات التی تستشہد بحجم معاملات x402 أو عدد تکاملات MPP. السؤال الصحیح لیس "أیہما حجمہ أکبر؟" بل "أیہما یناسب اقتصادیات ہذہ المعاملة؟" استدعاء API بقیمة 0.001 دولار علی سکک البطاقات یکلف رسوما أکثر من قیمة الاستدعاء نفسہ. ومشتریات بقیمة 5,000 دولار علی عملة مستقرة x402 ترمی حمایة chargeback التی تمنحہا البطاقة.

تعمل التسویة عادة کأثر جانبی لأداة فی طبقة أعلی: نادرا ما یستدعی الوکیل settle_payment() مباشرة؛ تحدث التسویة داخل acp_checkout() أو x402_fetch(). لکن حدود الإنفاق علی مستوی SDK تبقی مہمة:

استدعاء x402_client.get أدناہ توضیحی؛ یمثل جلب x402 من جہة المشتری. ربط @function_tool وفحص الإنفاق کود Python حقیقیان.

from agents import function_tool, RunContextWrapper
from decimal import Decimal
from .models import X402PaymentResult, PaymentToolResult

@function_tool
async def x402_fetch(
    ctx: RunContextWrapper,
    url: str,
    max_payment_usdc: Decimal,
) -> X402PaymentResult | PaymentToolResult:
    """Fetch a paid URL via x402. Settlement is automatic if cost <= max_payment_usdc."""
    # Check the SDK-level spend tracker before initiating the request
    spent_so_far = Decimal(str(ctx.context.get("session_x402_spend_usdc", Decimal(0))))
    session_cap = ctx.context["user_session"].x402_session_cap_usdc
    if spent_so_far + max_payment_usdc > session_cap:
        return PaymentToolResult(
            status="rejected",
            error=f"Would exceed session spend cap (already spent ${spent_so_far})",
        )

    # Initiate the x402 flow: the server returns 402, the agent retries with a signed payment
    response = await x402_client.get(url, max_payment_usdc=max_payment_usdc)

    # Update the spend tracker, kept in ctx.context for cross-tool visibility
    ctx.context["session_x402_spend_usdc"] = spent_so_far + response.amount_paid_usdc
    return X402PaymentResult(
        content=response.content,
        amount_paid_usdc=response.amount_paid_usdc,
        tx_hash=response.tx_hash,
    )

شیء یجب توضیحہ: فحص if spent_so_far + ... حارس لین داخل جسم الأداة، مفید لفشل سریع ومفہوم للمستخدم، لکنہ لیس السلامة الحقیقیة. السلامة التی تحمیک فعلا ہی محفظة العقد الذکی للوکیل. حتی لو حذفت الفحص داخل الأداة، فإن حدود المحفظة من المفہوم 15 سترفض التحویل علی السلسلة. فحص الأداة لتجربة المستخدم؛ وحدود المحفظة للسلامة.

الحرکة ہنا ہی أن تختار السکة التی تناسب اقتصادیات المعاملة، ثم تؤکد توافقہا مع اختیارک فی التجارة. المدفوعات بین الآلات دون الدولار تذہب إلی x402. مشتریات المستہلک تذہب إلی سکک البطاقات عبر ACP. واشتراکات المؤسسات تذہب إلی MPP. لا تختر التسویة بمعزل؛ اخترہا بوصفہا قاع مکدس مرکب.

خلاصة المفہوم 7: الطبقة 4 (التسویة) ہی حیث یتحرک المال فعلا. تتنافس أربعة خیارات. x402 لمدفوعات العملات المستقرة بین الآلات. وMPP للجلسات متعددة السکک. وسکک البطاقات لمشتریات المستہلک التی تحتاج chargebacks. والبنک أو Lightning للحالات عالیة القیمة أو منخفضة الرسوم جدا. یتعلق الاختیار غالبا بالمال: دون الدولار إلی x402، والمستہلک إلی البطاقات، والمؤسسة إلی MPP. یشغّل SDK التسویة کأثر جانبی لأدوات الطبقات الأعلی. یحد الإنفاق علی مستوی التشغیل والجلسة باستخدام RunContextWrapper، وحدود المحفظة علی السلسلة ہی الطبقة التی لا یستطیع شیء تجاوزہا.

---

الجزء 3: البروتوکولات الأربعة بعمق، مع تکامل OpenAI Agents SDK

وضع الجزءان 1 و2 الإطار: أربع طبقات، وعدة بروتوکولات فی کل طبقة، وSDK بوصفہ العمیل الموحد. یمشی الجزء 3 عبر البروتوکولات الأربعة الرئیسیة عن قرب. فی کل واحد تحصل علی ماہیتہ، وبدائیاتہ الأساسیة، وکود تکاملہ مع SDK، وملاحظات قصیرة عن کیف تنشرہ الفرق وتشغلہ.

اقرأہا کأربع جولات عمیقة متوازیة. لکل بروتوکول الشکل نفسہ، لذلک تستطیع مقارنتہا جنبا إلی جنب.

کل بروتوکول فی المفاہیم 8 إلی 11 یربط ب SDK عبر أحد الأنماط فی ہذا المخطط. یلمّح مکدس حدود الإنفاق فی الأسفل إلی المفہوم 15 فی الجزء 6. أبقہ فی زاویة عینک أثناء القراءة: انضباط السلامة الذی یعرضہ ہو ما یحول ہذا الکود إلی شیء یمکن نشرہ فعلا.

🧰 Pydantic کطبقة عقد: اقرأ مرة واحدة، وینطبق علی کل بروتوکول أدناہ

تستخدم کل عینة کود فی الجزء 3 نماذج Pydantic، لا dicts عادیة فی Python، لحِمل البروتوکولات، وقیم إرجاع الأدوات، وأجسام طلبات واستجابات FastAPI، وحمولات أحداث Inngest. ہذا ہو الجزء الذی لا یمکنک تجاوزہ. إنہ ما یبقی النظام کلہ متماسکا.

تعبر أربعة حدود فی تدفق تجارة وکلاء نموذجی:

1. ترجع @function_tool فی SDK قیمة إلی مستدل الوکیل.
2. تعبر تلک القیمة الشبکة إلی نقطة نہایة بروتوکول (ACP أو AP2 أو x402 أو MPP).
3. یعید البروتوکول استجابة تعبر راجعة.
4. أحیانا یصل webhook لاحقا ویعبر إلی handler فی FastAPI.

عند کل حد، یفقد dict غیر المعرّف الحقول بصمت، ویسقط التحویلات، ویرسل الشکل الخطأ. تلتقط نماذج Pydantic أنواع الفشل الأربعة کلہا عند الحد نفسہ، بأخطاء تشیر إلی الحقل المحدد.

ہذا ہو النمط الذی یتکرر فی کل مفہوم أدناہ:

from pydantic import BaseModel, Field
from decimal import Decimal
from typing import Literal
from agents import function_tool, RunContextWrapper

class CartItem(BaseModel):
    sku: str
    quantity: int = Field(ge=1)
    unit_price_usd: Decimal

class CheckoutRequest(BaseModel):
    merchant_id: str
    items: list[CartItem]
    max_total_usd: Decimal = Field(gt=0)

class CheckoutResult(BaseModel):
    order_id: str
    status: Literal["confirmed", "failed", "pending_user_confirmation"]
    total_charged_usd: Decimal
    estimated_delivery: str | None = None

@function_tool
async def acp_checkout(ctx: RunContextWrapper, request: CheckoutRequest) -> CheckoutResult:
    # Pydantic has already validated the request shape before this line runs.
    # Returning a CheckoutResult means the agent's reasoner gets typed feedback.
    ...

ثلاثة أسباب ملموسة تجعلہ مہما بہذا الحجم:

1. یستخدم المستدل نوع الإرجاع کتغذیة راجعة. عندما ترجع acp_checkout قیمة CheckoutResult ذات نوع محدد، تصل خطوة الاستدلال التالیة لدی الوکیل إلی أسماء حقول وأنواع نظیفة، لا dict محولا إلی string. ترتفع دقة اختیار الأدوات بصورة قابلة للقیاس.
2. یستخدم FastAPI نماذج Pydantic أصلیا. کل webhooks من Stripe، وcallbacks تفویضات AP2، وأحداث جلسات MPP تفکک إلی نماذج Pydantic فی handler FastAPI: النماذج نفسہا التی ترجعہا أدوات الوکیل. عقد واحد، ونقطتا نہایة.
3. تحمل أحداث Inngest حمولات Pydantic. عندما یطلق handler webhook فی FastAPI حدث Inngest، تکون الحمولة نموذج Pydantic. یتلقی step.wait_for_event المعلق الحمولة ذات النوع مباشرة. لا parsing ل JSON داخل workflow.

استخدم Decimal للمال دائما. یستخدم کل مبلغ نقدی فی ہذہ الدورة Decimal، لا float. تفقد حسابات الفاصلة العائمة للمال الدقة بطرق تتراکم عبر آلاف المدفوعات الصغیرة. یقبل Stripe SDK النوعین لکنہ یعید التقاریر فی Decimal. وتصل مبالغ x402 کأعداد صحیحة علی السلسلة (ل USDC ست خانات عشریة) تغلفہا فی Decimal. یبقی المال Decimal فی کل موضع لا یرسل فیہ إلی صیغة سلکیة.

نماذج النتائج المشترکة. بدلا من إعادة تعریف أنواع النتائج فی کل مفہوم، تعرّف الدورة مجموعة صغیرة من نماذج النتائج مرة واحدة. تستورد کل کتل الکود أدناہ ہذہ النماذج بالاسم. ضعہا فی models.py:

from pydantic import BaseModel, Field
from decimal import Decimal
from typing import Literal
from datetime import datetime

# --- Tool-result models (returned by @function_tool functions) ---

class PaymentToolResult(BaseModel):
    """Generic envelope for any payment-related tool action."""
    status: Literal["success", "failed", "rejected", "pending"]
    error: str | None = None
    details: dict | None = None  # protocol-specific details

class MandateResult(BaseModel):
    """Result of creating an AP2 mandate (Intent / Cart / Payment)."""
    mandate_id: str | None = None
    status: Literal["signed", "declined", "pending", "failed"]
    expires_at: str | None = None  # ISO 8601
    error: str | None = None

class OrderStatusResult(BaseModel):
    """Result of fetching ACP order status."""
    order_id: str
    status: Literal["confirmed", "shipped", "delivered", "cancelled", "refunded", "pending"]
    tracking_url: str | None = None
    estimated_delivery: str | None = None

class RefundResult(BaseModel):
    """Result of initiating an ACP refund."""
    refund_id: str
    order_id: str
    status: Literal["initiated", "processing", "completed", "failed"]
    amount_refunded_usd: Decimal | None = None

class DiscoveryResult(BaseModel):
    """Result of an Agent.market or similar agent-directory search."""
    service_id: str
    name: str
    description: str
    price_per_call_usdc: Decimal
    endpoint_url: str

class X402PaymentResult(BaseModel):
    """Result of an x402-paid fetch."""
    content: str
    amount_paid_usdc: Decimal
    tx_hash: str | None = None

class MPPSessionResult(BaseModel):
    """Result of creating or closing an MPP session."""
    session_id: str
    status: Literal["active", "closed", "expired", "failed"]
    total_charged_usd: Decimal | None = None  # only populated on close
    expires_at: datetime | None = None
    rail_breakdown: dict[str, Decimal] | None = None  # only on close

class MPPMeteredCallResult(BaseModel):
    """Result of a metered call within an active MPP session."""
    session_id: str
    cost_usd: Decimal
    response_payload: dict
    accumulated_session_spend_usd: Decimal

# --- FastAPI handler models (request/response bodies for webhooks/callbacks) ---

class WebhookAck(BaseModel):
    """Generic webhook handler ack."""
    received: bool = True
    event_id: str | None = None

# --- Inngest workflow result models (return types of @inngest_client functions) ---

class WorkflowResult(BaseModel):
    """Generic workflow completion envelope."""
    status: Literal["completed", "abandoned", "failed", "partial"]
    reason: str | None = None
    output: dict | None = None

تتکرر ہذہ النماذج فی الجزء 3 والجزء 6. تستوردہا کتل الکود أدناہ بالاسم ولا تعید تعریفہا. لن یکرر ہذا الشریط الجانبی ذلک.

المفہوم 8: ACP (Agentic Commerce Protocol)، بروتوکول تسوق المستہلک

فی سطر واحد: ACP ہو الطریقة التی یکمل بہا وکیل checkout حقیقیا لدی تاجر حقیقی نیابة عن شخص، مع بقاء التاجر مسؤولا عن البیع.

ما ہو. ACP مواصفة مفتوحة بنتہا OpenAI وStripe، وأطلقت فی 29 سبتمبر 2025 مع Etsy وShopify کشریکی إطلاق. وبحلول أوائل 2026 أصبحت تشغل ChatGPT Instant Checkout عبر التجار المدمجین مع Shopify وعدة علامات تجزئة کبیرة. تختلف أعداد التجار وقوائم العلامات حسب المصدر، لذلک تحقق من دلیل تکامل ACP لمعرفة التبنی الحالی. البروتوکول Apache 2.0، ویحکم عبر عملیة Specification Enhancement Proposal فی github.com/agentic-commerce-protocol/agentic-commerce-protocol. یعلّم المستودع المواصفة ک beta، لذلک توقع انحرافا بین أمثلة الدورة والمواصفة الحیة.

أین یجلس. یعیش ACP غالبا فی الطبقة 3 (التجارة) ویمتد إلی الطبقة 2 (التفویض) عبر آلیة رموزہ. یغطی تکوین السلة، وcheckout، وإدارة الطلب، وحالة التنفیذ، وآلیات الاسترداد. یبقی التاجر merchant of record: تمر chargebacks والإرجاعات وخدمة العملاء کلہا عبر أنظمة التاجر القائمة. (merchant of record ہو النشاط التجاری المسؤول قانونیا عن المعاملة.)

البدائیتان المہمتان.

1. رمز Shared Payment Token (SPT). رمز لمرة واحدة من معالج الدفع (Stripe فی البناء المرجعی)، مقفل علی تاجر واحد، وسقف مبلغ واحد، ونافذة زمنیة قصیرة واحدة، وغالبا استخدام واحد. إذا حاول وکیل مسموح لہ بإنفاق 50 دولارا أن ینفق 1000 دولار، یفشل SPT علی مستوی البروتوکول. SPT ہو کیف یبقی ACP الوکیل داخل نطاق تفویض المستخدم.
2. تفویض Cart Mandate (عبر امتداد AP2). یستطیع ACP الترکیب مع AP2 لمزید من صرامة التدقیق: یوقّع المستخدم Cart Mandate قبل أن یرسل الوکیل SPT. ہذا اختیاری فی ACP لکنہ صار شائعا فی التدفقات المنظمة. (التفویض إثبات موقّع بأن إنسانا فوّض نوعا محددا من الإنفاق.)

تکامل OpenAI Agents SDK. ACP ہو البروتوکول الأکثر جاہزیة للإنتاج مع SDK، لأن OpenAI شارکت فی بنائہ. یعطیک Stripe Python SDK مع غلاف عمیل ACP رقیق التکامل الکامل.

استدعاءات acp_client وstripe.PaymentTokens.create(...) أدناہ توضیحیة: تبین شکل تکامل ACP. إصدار SPT الحقیقی یمر عبر نقاط نہایة Stripe ACP الحیة، لا عبر طریقة stripe.PaymentTokens. ربط الوکیل وحاجز الأمان ونماذج النتائج حقیقیة وتعمل الیوم. راجع الملاحظة بعد الکتلة.

from agents import Agent, Runner, function_tool, RunContextWrapper
from agents.tool_guardrails import (
    tool_input_guardrail,
    ToolInputGuardrailData,
    ToolGuardrailFunctionOutput,
)
from pydantic import BaseModel
from decimal import Decimal
from typing import Literal
import json
import stripe
import time
from .models import OrderStatusResult, RefundResult

class CartItem(BaseModel):
    sku: str
    name: str
    quantity: int
    unit_price_usd: Decimal

class CheckoutResult(BaseModel):
    order_id: str
    status: Literal["confirmed", "failed", "pending_user_confirmation"]
    total_charged_usd: Decimal
    estimated_delivery: str | None = None

# Tool input guardrail: refuse the checkout if the user can't authorize the spend
@tool_input_guardrail
def verify_user_can_spend(data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
    args = json.loads(data.context.tool_arguments or "{}")
    max_total = Decimal(str(args.get("max_total_usd", 0)))
    merchant_id = args.get("merchant_id", "")
    user_session = data.context.context["user_session"]
    if not user_session.can_spend(max_total, merchant_id):
        return ToolGuardrailFunctionOutput.reject_content(
            f"User cannot authorize ${max_total} at merchant {merchant_id}"
        )
    return ToolGuardrailFunctionOutput.allow()

@function_tool
async def acp_browse_merchant(merchant_id: str, query: str) -> list[dict]:
    """Search a merchant's catalog via their ACP catalog endpoint."""
    response = await acp_client.catalog.search(
        merchant_id=merchant_id,
        query=query,
        limit=20,
    )
    return [item.model_dump() for item in response.items]

@function_tool(tool_input_guardrails=[verify_user_can_spend])
async def acp_create_cart_and_checkout(
    ctx: RunContextWrapper,
    merchant_id: str,
    items: list[CartItem],
    max_total_usd: Decimal,
) -> CheckoutResult:
    """Create a cart at the merchant and complete checkout in one transaction.
    Mints an SPT scoped to max_total_usd; the merchant verifies and charges.
    The verify_user_can_spend guardrail above has already validated authorization."""

    user_session = ctx.context["user_session"]

    # Mint the Shared Payment Token via Stripe (Decimal to cents via quantize)
    cents = int((max_total_usd * 100).quantize(Decimal("1")))
    spt = stripe.PaymentTokens.create(
        amount=cents,
        currency="usd",
        merchant_id=merchant_id,
        user_session_id=user_session.id,
        max_uses=1,
        expires_at=int(time.time()) + 600,  # 10-minute window
    )

    # Submit the cart and SPT to the merchant's ACP endpoint
    result = await acp_client.checkout.complete(
        merchant_id=merchant_id,
        items=[i.model_dump() for i in items],
        spt_token=spt.token,
    )

    # Update the user's spend tracker (Decimal in, Decimal out)
    user_session.record_spend(
        amount_usd=Decimal(str(result.total_charged_usd)),
        merchant_id=merchant_id,
        order_id=result.order_id,
    )

    return CheckoutResult(**result.model_dump())

@function_tool
async def acp_check_order(order_id: str) -> OrderStatusResult:
    """Get the current status of an ACP order (fulfillment, shipping, delivery)."""
    raw = await acp_client.orders.get(order_id=order_id)
    return OrderStatusResult(
        order_id=raw.order_id,
        status=raw.status,
        tracking_url=raw.tracking_url,
        estimated_delivery=raw.estimated_delivery,
    )

@function_tool
async def acp_refund(
    order_id: str,
    reason: str,
    amount_usd: Decimal | None = None,
) -> RefundResult:
    """Start a refund for an ACP order. Returns refund_id for follow-up.
    If amount_usd is None, a full refund is requested."""
    raw = await acp_client.refunds.create(
        order_id=order_id,
        reason=reason,
        amount_usd=amount_usd,
    )
    return RefundResult(
        refund_id=raw.refund_id,
        order_id=order_id,
        status=raw.status,
        amount_refunded_usd=raw.amount_refunded_usd,
    )

shopping_agent = Agent(
    name="ShoppingAgent",
    instructions="""Help the user shop at ACP-enabled merchants. Workflow:
    1. Use acp_browse_merchant to find products matching the user's request
    2. Present the matched items to the user (via reasoning, not a tool)
    3. When the user confirms, use acp_create_cart_and_checkout to complete the purchase
    4. Use acp_check_order to report order status when the user asks
    5. Use acp_refund only when the user explicitly requests a return""",
    tools=[acp_browse_merchant, acp_create_cart_and_checkout, acp_check_order, acp_refund],
    model="gpt-5.5",
)

ما ہو حقیقی ہنا: طبقة Agent وRunner و@function_tool وtool_input_guardrail، إضافة إلی نماذج النتائج ذات الأنواع. ہذا ہو الجزء الذی تعید استخدامہ لکل بروتوکول. وما ہو بدیل: acp_client واستدعاء stripe.PaymentTokens.create، اللذان یمثلان خلفیة ACP-Stripe. فی الإنتاج تبدل تلک الخلفیة بنقاط نہایة Stripe ACP الحیة ویبقی الباقی فی مکانہ. وہذا ہو الشکل نفسہ مع mock قابل للتشغیل حتی تراہ یعمل:

class MockACPClient:
    """Illustrative backend. Real ACP uses live Stripe ACP endpoints, not stripe.PaymentTokens."""
    async def checkout(self, merchant_id: str, amount_usd) -> dict:
        return {"order_id": "ord_mock_1", "status": "confirmed", "total_charged_usd": str(amount_usd)}

acp_client = MockACPClient()   # stands in for the ACP/Stripe backend

الغلاف القیاسی (نذکرہ مرة ہنا وتشیر إلیہ المفاہیم الثلاثة التالیة). یعمل ACP علی غلاف السحابة العادی بلا أجزاء إضافیة. یعمل Stripe SDK داخل handler FastAPI؛ واستدعاءات ACP صادرة عبر HTTPS؛ وتعیش SPTs فی سیاق تشغیل الوکیل المحدد للتشغیل، وتمر عبر RunContextWrapper. القاعدة الوحیدة: ضع مفاتیح Stripe API فی مخزن أسرار (key vault)، لا فی متغیرات البیئة، ودوّرہا حسب جدول Stripe. لا حاجة إلی sandbox (ف ACP لا یشغل کودا)، ولا حاجة إلی تخزین خاص (تستمر الطلبات فی Stripe ونظام التاجر، مع سجلات ظل اختیاریة للتدقیق). خط الأساس ہذا للنشر ہو نفسہ فی AP2 وx402 وMPP. لا تقول المفاہیم الثلاثة التالیة إلا ما یضیفہ کل واحد. یغطی درس deploying-agents المکثف نشر السحابة (قید العمل).

تشغیلہ بمتانة (Inngest). معاملات ACP قصیرة، غالبا 5 إلی 30 ثانیة من البدایة إلی النہایة. تناسب کتل Inngest step.run بنظافة. وتظہر قیمة step.wait_for_event عندما یجب أن یتوقف الوکیل مؤقتا حتی یؤکد المستخدم السلة بین إنشاء السلة وcheckout (نمط الإنسان داخل الحلقة). تغطی الدورة المکثفة فی عامل الإنتاج طبقة المتانة ہذہ بعمق؛ وہذا ہو الشکل:

import inngest
from datetime import timedelta
from .models import WorkflowResult

@inngest_client.create_function(
    fn_id="shopping-workflow",
    trigger=inngest.TriggerEvent(event="shopping/checkout.requested"),
    concurrency=[inngest.Concurrency(limit=5, key="event.data.user_id")],
)
async def shopping_workflow(ctx: inngest.Context) -> dict:
    # Run the agent to produce the cart proposal
    cart = await ctx.step.run(
        "agent-builds-cart", build_cart_fn, ctx.event.data["user_query"],
    )

    # Wait for the user to confirm the proposed cart (human-in-the-loop)
    confirmation = await ctx.step.wait_for_event(
        "wait-for-user-confirm",
        event="shopping/cart.confirmed",
        if_exp=f"async.data.cart_id == '{cart['cart_id']}'",
        timeout=timedelta(minutes=15),
    )
    if confirmation is None:                 # timeout returns None
        return {"status": "abandoned", "reason": "user did not confirm in time"}

    # The user confirmed; complete checkout with the now-valid SPT
    result = await ctx.step.run("complete-checkout", complete_checkout_fn, cart["cart_id"])
    return {"status": "completed", "output": result}

تفصیلان یوقعان الناس فی الخطأ: یطابق wait_for_event الحمولة الواردة ب if_exp (تعبیر صغیر)، وتعیش الحقول المنتظرة تحت بادئة async.. ویرجع timeout قیمة None، لذلک افحصہا قبل المتابعة.

أین تخطئ الفرق. تتجاوز خطوة تأکید المستخدم. یدعم ACP کلا من "یؤکد المستخدم کل سلة" و"فوّض المستخدم ہذا النوع من الشراء مسبقا." تختار الفرق غالبا الثانی للسرعة، ثم تکتشف أن خطأ صغیرا فی ضبط SPT یسمح للوکیل بشراء عناصر مختلفة قلیلا بلا طریقة للتعافی. ابدأ بتأکید السلة خلال أول شہر فی الإنتاج. لا ترخہا إلا بعد قیاس معدل صحة سلال الوکیل.

خلاصة المفہوم 8: ACP ہو بروتوکول التجارة الجاہز للإنتاج لتسوق المستہلک مع OpenAI Agents SDK. یحدد SPT نطاق إنفاق الوکیل؛ ویبقی التاجر merchant of record. تدمجہ کأربع دوال @function_tool (تصفح، checkout، حالة، استرداد) فوق Stripe SDK وعمیل ACP رقیق. یبنی step.wait_for_event فی Inngest بوابة تأکید المستخدم، وغلاف السحابة العادی یکفی. ابدأ بتأکید السلال حتی تقیس دقة سلة الوکیل.

المفہوم 9: AP2 (Agent Payments Protocol)، طبقة التفویض

فی سطر واحد: ینتج AP2 إثباتات موقعة بأن إنسانا سمح بالإنفاق؛ لا ینقل المال بنفسہ، بل یثبت أن المال کان مسموحا لہ أن یتحرک.

ما ہو. AP2 مواصفة مفتوحة من Google مع أکثر من 60 شریکا، أطلقت فی سبتمبر 2025 (آخر نسخة v0.2.0، أبریل 2026). ترخیصہا Apache 2.0، وتحفظ فی github.com/google-agentic-commerce/AP2، مع تنفیذات مرجعیة فی Python وTypeScript وKotlin وGo. AP2 ہو طبقة التفویض، لا بروتوکول تجارة ولا تسویة. ینتج تفویضات موقعة تثبت أن الوکیل مخول بالإنفاق، ثم یترک التسویة الفعلیة لأی سکة مناسبة (بطاقات، بنک، أو x402 عبر امتداد a2a-x402).

أین یجلس. یعیش AP2 فی الطبقة 2 (الہویة والتفویض). ویبنی علی بروتوکولین تحتہ: A2A (Agent2Agent، للمراسلة بین الوکلاء) وMCP (لتعریض الأدوات). ینتقل تفویض AP2 کبیان اعتماد موقّع عبر A2A أو مرفقا باستدعاء أداة MCP.

البدائیات الثلاث المہمة، وہی أنواع التفویض الثلاثة.

التفویض	متی ینشأ	ما الذی یثبتہ
Intent Mandate	عند بدء المہمة، ویوقّعہ المستخدم فی واجہتہ	أن المستخدم سمح للوکیل بالعمل داخل قواعد محددة (حدود سعر، نوافذ زمنیة، تجار مسموحون)
Cart Mandate	بعد أن یبنی الوکیل سلة محددة، ویوقّعہ المستخدم قبل checkout (تدفقات الإنسان الحاضر)	أن المستخدم وافق علی ہذہ السلة بالضبط وبہذا السعر بالضبط
Payment Mandate	عند لحظة الدفع، یوقّعہ المستخدم أو یولد آلیا مقابل Intent Mandate	أن المستخدم فوّض ہذہ الدفعة بالضبط علی ہذہ السکة بالضبط

مسار التدقیق. تشکل التفویضات الثلاثة سلسلة لا یستطیع الموقّع إنکارہا لاحقا: Intent ("اشتر حذاء بأقل من 120 دولارا") یؤدی إلی Cart ("ہذا الحذاء بسعر 110 دولارات") یؤدی إلی Payment ("اخصم من ہذہ محفظة العملة المستقرة"). یشیر کل تفویض إلی ما قبلہ. إذا طعن أحد فی أی خطوة لاحقا فی نزاع أو مطالبة احتیال، تکون السلسلة کلہا قابلة للتدقیق. ہذہ الخاصیة غیر قابلة للإنکار: عبارة "لم أفوض ہذا" لا تصمد أمام توقیع المستخدم نفسہ. لہذا یناسب AP2 الصناعات المنظمة مثل الرعایة الصحیة والخدمات المالیة، حیث یحمل سؤال "ہل فوّض المستخدم ہذا فعلا؟" وزنا قانونیا.

ما الذی یتغیر فی SDK. لا یملک AP2 مکانا أصلیا فی OpenAI Agents SDK؛ تستخدم نسخہ المرجعیة Google Agent Development Kit. تربطہ کدوال @function_tool تنشئ التفویضات وتوقعہا وتتحقق منہا وترسلہا. الغلاف ہو نفسہ غلاف المفہوم 8. الشیء الوحید الذی یضیفہ AP2: واجہة توقیع یوقّع فیہا المستخدم کل تفویض فعلا.

استیرادات from ap2 import ... وMandateSigner واستدعاءات ap2_x402 أدناہ توضیحیة. حزمة Python الحقیقیة ل AP2 ہی ap2، مع نماذج التفویض تحت ap2.types.mandate، وحقولہا الحقیقیة تختلف عن principal_did / agent_did / rules المبسطة ہنا. لا توجد فئة MandateSigner؛ یستخدم التوقیع الحقیقی verifiable credentials عبر A2A. مفہوم سلسلة التفویضات حقیقی؛ ہذا الکود نفسہ بدیل تعلیمی. أما طبقة SDK ونماذج النتائج ذات الأنواع فحقیقیة.

from agents import Agent, function_tool, RunContextWrapper
from agents.tool_guardrails import (
    tool_input_guardrail,
    ToolInputGuardrailData,
    ToolGuardrailFunctionOutput,
)
from ap2 import IntentMandate, CartMandate, PaymentMandate, MandateSigner
from pydantic import BaseModel
from decimal import Decimal
from datetime import datetime
from .models import MandateResult, PaymentToolResult

class IntentRules(BaseModel):
    max_total_usd: Decimal
    allowed_merchants: list[str] | None = None
    allowed_categories: list[str] | None = None
    expires_at: str  # ISO 8601 datetime

# Guardrail: refuse any cart that has no preceding Intent Mandate
@tool_input_guardrail
def require_intent_mandate(data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
    intent = data.context.context.get("intent_mandate")
    if not intent:
        return ToolGuardrailFunctionOutput.reject_content(
            "No Intent Mandate found. Create one via ap2_create_intent_mandate first."
        )
    return ToolGuardrailFunctionOutput.allow()

@function_tool
async def ap2_create_intent_mandate(
    ctx: RunContextWrapper,
    task_description: str,
    rules: IntentRules,
) -> MandateResult:
    """Create an Intent Mandate at the start of a purchasing task.
    Needs the user's signature, so call this BEFORE the agent shops."""

    user_session = ctx.context["user_session"]
    mandate = IntentMandate(
        principal_did=user_session.did,  # decentralized identifier
        agent_did=ctx.context["agent_did"],
        task=task_description,
        rules=rules.model_dump(),
        issued_at=datetime.utcnow().isoformat(),
    )

    # Send to the user's signing UI; block until the user signs or rejects
    signed = await user_session.signer.request_signature(
        mandate,
        ui_prompt="Approve this shopping task?",
        timeout_seconds=300,
    )
    if not signed:
        return MandateResult(status="declined", error="User declined to sign Intent Mandate")

    # Store the mandate for later reference by Cart/Payment mandates
    ctx.context["intent_mandate"] = signed
    return MandateResult(mandate_id=signed.id, status="signed", expires_at=rules.expires_at)

@function_tool(tool_input_guardrails=[require_intent_mandate])
async def ap2_create_cart_mandate(
    ctx: RunContextWrapper,
    cart_items: list[dict],
    total_usd: Decimal,
    merchant_id: str,
) -> MandateResult:
    """Create a Cart Mandate that references the current Intent Mandate.
    Needs the user's signature in human-present flows.
    The require_intent_mandate guardrail above has verified an Intent Mandate exists."""

    intent = ctx.context["intent_mandate"]  # guaranteed present by the guardrail

    # Check that the cart fits inside the Intent Mandate's rules
    if total_usd > Decimal(str(intent.rules["max_total_usd"])):
        return MandateResult(
            status="failed",
            error=f"Cart total ${total_usd} exceeds Intent Mandate cap ${intent.rules['max_total_usd']}",
        )

    cart_mandate = CartMandate(
        parent_intent_id=intent.id,
        cart_items=cart_items,
        total_usd=str(total_usd),  # serialize Decimal as a string on the wire
        merchant_id=merchant_id,
        issued_at=datetime.utcnow().isoformat(),
    )

    user_session = ctx.context["user_session"]
    signed = await user_session.signer.request_signature(
        cart_mandate,
        ui_prompt=f"Approve this cart for ${total_usd}?",
        timeout_seconds=300,
    )
    if not signed:
        return MandateResult(status="declined", error="User declined to sign Cart Mandate")

    ctx.context["cart_mandate"] = signed
    return MandateResult(mandate_id=signed.id, status="signed")

@function_tool
async def ap2_settle_via_x402(
    ctx: RunContextWrapper,
    merchant_x402_url: str,
) -> PaymentToolResult:
    """Use the AP2 a2a-x402 extension to settle the current Cart Mandate via an x402 stablecoin payment."""
    cart = ctx.context.get("cart_mandate")
    if not cart:
        return PaymentToolResult(status="failed", error="No Cart Mandate to settle")

    # The a2a-x402 extension generates a Payment Mandate authorizing the x402 transfer
    payment_mandate = await ap2_x402.create_payment_mandate(
        cart_mandate=cart,
        rail="x402",
        chain="eip155:8453",  # Base
        asset="USDC",
    )

    # Dispatch the x402 payment with the Payment Mandate attached as proof
    result = await x402_client.pay(
        url=merchant_x402_url,
        amount_usdc=Decimal(str(cart.total_usd)),
        payment_mandate=payment_mandate,
    )
    return PaymentToolResult(status="success", details=result.model_dump())

procurement_agent = Agent(
    name="ProcurementAgent",
    instructions="""Enterprise procurement workflow:
    1. ALWAYS create an Intent Mandate first via ap2_create_intent_mandate
    2. Search merchants for matching items
    3. Build a cart and create a Cart Mandate via ap2_create_cart_mandate
    4. Settle via x402 (stablecoin) using ap2_settle_via_x402, or via card rails
    5. Record every mandate ID in the procurement system for audit""",
    tools=[ap2_create_intent_mandate, ap2_create_cart_mandate, ap2_settle_via_x402],
    model="gpt-5.5",
)

ما ہو حقیقی: طبقة SDK ونماذج النتائج ذات الأنواع نفسہا مثل المفہوم 8. وما ہو بدیل: فئات تفویض ap2، وMandateSigner، وامتداد ap2_x402. سلسلة التفویض نفسہا فکرة حقیقیة تستطیع بناءہا؛ أما API الدقیق ہنا فمبسط للتعلیم. وہذا mock قابل للتشغیل حتی یعمل النمط:

class MockSignedMandate:
    def __init__(self, mid, rules=None): self.id, self.rules = mid, (rules or {})
class MockSigner:
    """Illustrative. Real AP2 signing uses verifiable credentials over A2A; no MandateSigner class exists."""
    async def request_signature(self, mandate, ui_prompt="", timeout_seconds=300):
        return MockSignedMandate(getattr(mandate, "id", "mandate_mock_1"))
ap2_x402 = type("Mock", (), {"create_payment_mandate": staticmethod(lambda **k: MockSignedMandate("pm_mock_1"))})()

ما یضیفہ إلی الغلاف. شیئان فوق خط أساس المفہوم 8: واجہة توقیع لیوقّع المستخدم التفویضات (تطبیق ویب، أو تطبیق ہاتف، أو أداة توقیع قائمة علی الإشعارات)، وتخزین متین للتفویضات الموقعة یستمر مدة نوافذ النزاع (احتفاظ 7 سنوات معیار شائع للتفویضات المالیة). واجہة التوقیع ہی الفارق الحقیقی عن ACP: یستطیع ACP إعادة استخدام جلسات login القائمة، أما AP2 فیحتاج إلی تدفق توقیع مخصص.

تشغیلہ بمتانة (Inngest). توقیع التفویض ہو المثال المدرسی لاستخدام step.wait_for_event. تطلق دالة الوکیل حدث "طلب توقیع"، وتتعلق الدالة، ویوقّع المستخدم فی الواجہة فیطلق حدث "تم التوقیع"، ثم تستأنف الدالة. لا یحترق compute أثناء الانتظار، وہذا مہم لأن توقیع مؤسسة قد یستغرق ساعات. تتعمق دورة Production Worker فی نمط الاستئناف ہذا.

أین تخطئ الفرق. تعامل إنشاء التفویض کہم عند checkout وتوقّع التفویض بعد أن یکون الوکیل قد أنجز کثیرا من العمل. أنشئ Intent Mandate أولا، قبل أن یتسوق الوکیل أصلا. یلتقط ذلک عدم تطابق النطاق مبکرا (أراد المستخدم أحذیة لکن Intent Mandate لا یسمح إلا بمستلزمات مکتبیة) بدلا من أن یحدث بعد أن یحرق الوکیل compute فی بناء سلة لن یستطیع تمویلہا أبدا.

خلاصة المفہوم 9: AP2 ہو طبقة التفویض لتجارة الوکلاء کثیفة التدقیق. تشکل أنواع التفویض الثلاثة (Intent وCart وPayment) سلسلة لا یستطیع المستخدم إنکارہا لاحقا، وتثبت الموافقة فی کل خطوة. تأتی التنفیذات المرجعیة فی Python وTypeScript وKotlin وGo عبر Google Agent Development Kit؛ وتدمجہا مع OpenAI Agents SDK کدوال @function_tool تنشئ التفویضات وتوقعہا وتتحقق منہا. یناسب step.wait_for_event فی Inngest انتظار التوقیع بطبیعتہ. أنشئ Intent Mandates أولا، قبل بدء التسوق، ولا تجعلہا فکرة لاحقة عند checkout.

المفہوم 10: x402، بروتوکول التسویة الأصیل فی HTTP

فی سطر واحد: یتیح x402 للوکیل دفع تکلفة استدعاء API خلال ثانیة إلی ثانیتین بعملة مستقرة، بإحیاء رمز HTTP 402 القدیم "Payment Required".

ما ہو. یحول x402 رمز الحالة HTTP 402 الخامل إلی طبقة دفع عاملة لواجہات API وتجارة الآلة إلی الآلة. أنشأتہ Coinbase (مایو 2025)، وأطلقت V2 فی دیسمبر 2025، وہو الآن تحت رعایة x402 Foundation التابعة ل Linux Foundation (أبریل 2026)، مع Cloudflare وStripe وAWS وGoogle وغیرہم کأعضاء. ترخیصہ Apache 2.0. بحلول أوائل 2026، یذکر x402 أکثر من 100 ملیون دفعة حتی الآن عبر Base وSolana، مع منظومة facilitators متنامیة؛ تتحرک الأرقام بسرعة، لذلک تحقق من الأرقام الحالیة فی x402.org وصفحات إطلاق x402 من Coinbase.

أین یجلس. یعیش x402 غالبا فی الطبقة 4 (التسویة) لتدفقات الآلة إلی الآلة، لکنہ یمتد إلی الطبقة 1 (عبر Agent.market وأدلة مشابہة) وإلی الطبقة 3 (یعمل کطبقة تجارة کاملة للوصول إلی API بسیط حیث لا توجد دورة شراء حقیقیة). فی التدفقات الخالصة بین الآلات، یکون x402 غالبا البروتوکول الوحید الذی تحتاجہ.

البدائیات الأربع المہمة.

1. رمز الحالة HTTP 402. عندما یطلب عمیل غیر مدفوع موردا مدفوعا، یعید الخادم 402 Payment Required مع ترویسة تحمل متطلبات الدفع: المخطط (exact لمبلغ ثابت)، والشبکة (بصیغة CAIP-2 مثل eip155:8453، ومعناہا فقط "Base")، والأصل (USDC)، وعنوان المستلم، والحد الأقصی، وانتہاء الصلاحیة. (CAIP-2 طریقة قیاسیة لتسمیة blockchain حتی یبقی البروتوکول محایدا تجاہ السلسلة.)
2. ترویسة تفویض الدفع. یعید العمیل المحاولة ومعہ ترویسة تحمل تفویض دفع موقّعا. یوقّع التفویض خارج السلسلة، لذلک لا یدفع المشتری gas.
3. معیار EIP-3009 (transferWithAuthorization). معیار Ethereum الذی یبنی علیہ x402. یسمح للمشتری بتوقیع دفعة خارج السلسلة یرسلہا شخص آخر إلی السلسلة، حتی لا یلمس المشتری blockchain مباشرة ولا یدفع gas.
4. دور Facilitator. طرف ثالث اختیاری یتحقق من التوقیع ویرسل الدفع علی السلسلة للتاجر، فلا یشغل التاجر أی سباکة blockchain. تشغل Coinbase وCloudflare facilitators.

ملاحظة عن أسماء الترویسات: تحقق من الوثائق الحالیة

مر x402 بإصداری V1 وV2، وتختلف أسماء الترویسات عبر نسخ المواصفة وال facilitators وSDKs. تستخدم وثائق Cloudflare الحالیة PAYMENT-REQUIRED فی استجابة 402، وPAYMENT-SIGNATURE فی إعادة المحاولة من العمیل، وPAYMENT-RESPONSE فی رد النجاح. تستخدم بعض الأمثلة الأقدم X-PAYMENT وX-PAYMENT-PROOF. التدفق واحد؛ تختلف أسماء السلک فقط. تحقق من الأسماء الدقیقة مقابل x402.gitbook.io ووثائق facilitator الذی تدمج معہ قبل کتابة الکود. یستخدم الأثر أدناہ الأدوار (طلب، 402 مع المتطلبات، إعادة محاولة موقعة، نجاح مع إثبات) من دون اختیار تقلید تسمیة واحد.

التدفق فی أثر واحد.

1. Agent: GET https://api.example.com/data
2. Server: 402 Payment Required
   <payment-required header>: { network: "eip155:8453", asset: USDC,
                                recipient: 0xMerchant..., max_amount: 100000,
                                expiry: 1716304800 }
3. Agent (signs an EIP-3009 authorization off-chain):
   GET https://api.example.com/data
   <payment-signature header>: <base64-encoded signed authorization>
4. Server: 200 OK
   <payment-response header>: <transaction hash>
   { data: ... }

تستغرق المعاملة کلہا ثانیة إلی ثانیتین. لا إنشاء حساب، ولا مفتاح API، ولا جلسة، ولا إنسان داخل الحلقة.

ما الذی یتغیر فی SDK. لدی x402 أبسط قصة بین الأربعة. توفر Cloudflare مساعدا یغلّف عمیل MCP بقدرة دفع x402؛ وللاستخدام غیر MCP، تغطیہ مکتبة Python من جہة المشتری مع النمط القانونی أدناہ. الغلاف ہو خط أساس المفہوم 8 نفسہ.

البانی from x402_client import ... المعروض ہنا، واستیراد from cloudflare_agents import withX402Client، والحقل response.amount_paid_usdc توضیحیة. الحزمة الحقیقیة من جہة المشتری ہی x402-client (from x402_client import X402Client، والبانی الحقیقی X402Client(account=...)، و.get(url) یعید httpx.Response). بانی المحفظة الأغنی ہنا بدیل تعلیمی، والاستدعاء الحی یحتاج إلی حساب ممول ونقطة نہایة 402 حقیقیة، وہو ما لا تفعلہ ہذہ الدورة. withX402Client لدی Cloudflare مساعد JavaScript؛ لا توجد حزمة Python اسمہا cloudflare_agents. خادم MCP (MCPServerStreamableHttp) Python حقیقی؛ وتغلیفہ بالدفع توضیحی ہنا. لا تتحرک أموال حقیقیة.

from agents import Agent, function_tool, RunContextWrapper
from agents.mcp import MCPServerStreamableHttp
from agents.tool_guardrails import (
    tool_input_guardrail,
    ToolInputGuardrailData,
    ToolGuardrailFunctionOutput,
)
from x402_client import X402Client, X402Wallet
from cloudflare_agents import withX402Client
from decimal import Decimal
import json
from .models import DiscoveryResult, X402PaymentResult, PaymentToolResult

# Pattern 1: wrap an MCP server's tools with x402 payment ability
research_mcp = MCPServerStreamableHttp(
    name="research-services",
    params={"url": "https://research-services.example.com/mcp"},
)
research_mcp_with_payments = withX402Client(
    research_mcp,
    wallet=agent_wallet,  # smart-contract wallet the agent controls
    max_per_call_usdc=Decimal("0.10"),
    max_per_session_usdc=Decimal("10.00"),
)

# Pattern 2: direct x402 calls as @function_tool
x402_client = X402Client(wallet=agent_wallet)

# Guardrail: refuse any x402 call that would exceed the session cap
@tool_input_guardrail
def enforce_x402_session_cap(data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
    args = json.loads(data.context.tool_arguments or "{}")
    max_payment = Decimal(str(args.get("max_payment_usdc", 0)))
    ctx = data.context.context
    spent = Decimal(str(ctx.get("session_x402_spend_usdc", 0)))
    cap = Decimal(str(ctx["user_session"].x402_session_cap_usdc))
    if spent + max_payment > cap:
        return ToolGuardrailFunctionOutput.reject_content(
            f"x402 session cap would be exceeded: ${spent} spent + ${max_payment} requested > ${cap}"
        )
    return ToolGuardrailFunctionOutput.allow()

@function_tool(tool_input_guardrails=[enforce_x402_session_cap])
async def x402_fetch(
    ctx: RunContextWrapper,
    url: str,
    max_payment_usdc: Decimal = Decimal("0.10"),
) -> X402PaymentResult | PaymentToolResult:
    """Fetch a URL that may require an x402 payment up to max_payment_usdc.
    Signs the EIP-3009 authorization and retries with the payment-signature header.
    The enforce_x402_session_cap guardrail above has already checked the session bound."""

    try:
        response = await x402_client.get(url, max_payment_usdc=max_payment_usdc)
        # Update the spend tracker for later guardrail checks
        current = Decimal(str(ctx.context.get("session_x402_spend_usdc", 0)))
        ctx.context["session_x402_spend_usdc"] = current + Decimal(str(response.amount_paid_usdc))
        return X402PaymentResult(
            content=response.content,
            amount_paid_usdc=Decimal(str(response.amount_paid_usdc)),
            tx_hash=response.tx_hash,
        )
    except X402PaymentRequired as e:
        return PaymentToolResult(
            status="rejected",
            error=f"Resource requires ${e.required_usdc}, exceeds max ${max_payment_usdc}",
        )

@function_tool
async def x402_search_agent_market(
    query: str,
    max_price_per_call_usdc: Decimal = Decimal("0.05"),
) -> list[DiscoveryResult]:
    """Search Agent.market for x402-paywalled services matching the query."""
    results = await agent_market_client.search(
        query=query,
        max_price_per_call_usdc=max_price_per_call_usdc,
    )
    return [
        DiscoveryResult(
            service_id=r.service_id,
            name=r.name,
            description=r.description,
            price_per_call_usdc=Decimal(str(r.price_per_call_usdc)),
            endpoint_url=r.endpoint_url,
        )
        for r in results
    ]

research_agent = Agent(
    name="ResearchAgent",
    instructions="""Research user queries by paying for data sources via x402.
    Workflow:
    1. Use x402_search_agent_market to find relevant paid services
    2. Use x402_fetch to pull data from selected services (max $0.10 per call)
    3. Synthesize the findings into a final report
    Stay under $10 per research session.""",
    tools=[x402_fetch, x402_search_agent_market],
    mcp_servers=[research_mcp_with_payments],
)

ما ہو حقیقی: طبقة SDK، ونماذج النتائج ذات الأنواع، وMCPServerStreamableHttp (خادم MCP Python حقیقی). وما ہو بدیل: عمیل x402 من جہة المشتری کما کتب ہنا، وغلاف withX402Client (JavaScript فقط فی الواقع)، وagent_market_client. ہذہ mocks قابلة للتشغیل حتی یعمل نمط الغلاف من دون أموال حقیقیة:

from decimal import Decimal

class MockX402Response:
    def __init__(self, content, amount, tx):
        self.content, self.amount_paid_usdc, self.tx_hash = content, amount, tx
class MockX402Client:
    """Illustrative. Real buyer-side package: x402-client (X402Client(account=...), .get() -> httpx.Response)."""
    async def get(self, url: str, max_payment_usdc: Decimal = Decimal("0.10")):
        return MockX402Response(content="<paid data>", amount=Decimal("0.02"), tx="0xmocktx")
x402_client = MockX402Client()
agent_wallet = object()   # stands in for the wallet handle

def withX402Client(mcp_server, **kwargs):
    """Illustrative: JavaScript-only in reality. Returns the server unchanged for the Python demo."""
    return mcp_server

ما یضیفہ إلی الغلاف. تقریبا لا شیء. لا یحتاج x402 إلی بنیة إضافیة فوق خط أساس المفہوم 8. تعیش محفظة العقد الذکی للوکیل علی عنوان فی السلسلة التی یتعامل علیہا (Base فی معظم الحالات)، ویجلس مفتاح توقیع المحفظة فی key vault، وتتولی مکتبة جہة المشتری التوقیع وإعادة محاولة HTTP. (محفظة العقد الذکی ہی محفظة crypto تفرض حدود إنفاقہا بکود علی blockchain نفسہا، لذلک تصمد حتی إذا اختل کود الوکیل.)

تشغیلہ بمتانة (Inngest). استدعاءات x402 قصیرة (ثانیة إلی ثانیتین) وidempotent: ینتج الطلب والتوقیع نفسیہما النتیجة نفسہا دائما. تناسب step.run بنظافة، وتفید memoization ہنا. إذا تعطل التشغیل بعد الدفع مقابل 5 من 10 استدعاءات API، تحفظ الاستدعاءات الخمسة المدفوعة وتدفع إعادة المحاولة فقط للخمسة الباقیة. ومن دون ذلک، کانت إعادة المحاولة ستدفع لکل العشرة مرة أخری.

سقف المحفظة ہو السلامة التی تحمیک

الفخ ہو معاملة x402 کأنک تسلم الوکیل بطاقة ائتمان. السلامة التی تحمیک فعلا ہی حد الإنفاق علی السلسلة فی المحفظة، لا max_payment_usdc لکل طلب. إذا تجاوزت حد السلسلة واستخدمت محفظة ساخنة بلا سقف، فقد تفرغہا حلقة وکیل عالقة واحدة. اضبط حدود إنفاق علی السلسلة لکل ہویة وکیل، ولکل جلسة، ولکل تاجر، بثلاث طبقات مستقلة، حتی لا یفرغ خطأ فی واحدة منہا المحفظة.

خلاصة المفہوم 10: x402 ہو بروتوکول التسویة الأصیل فی HTTP والجاہز للإنتاج للمدفوعات الصغیرة بین الآلات. ینجز رمز 402، وترویسة تفویض دفع موقعة، وتدفق توقیع EIP-3009 التسویة خلال ثانیة إلی ثانیتین بلا إنشاء حساب. یغلّف مساعد Cloudflare خوادم MCP بقدرة دفع؛ وتعمل الاستدعاءات المباشرة عبر مکتبة Python من جہة المشتری. تحفظ memoization فی step.run داخل Inngest المدفوعات المکررة عند retry. حد الإنفاق علی السلسلة فی المحفظة ہو السلامة التی تحمیک، لا سقف کل طلب. تحقق من أسماء الترویسات مقابل نسخة المواصفة وال facilitator الذی تدمج معہ.

المفہوم 11: MPP (Machine Payments Protocol)، بروتوکول التسویة القائم علی الجلسات

فی سطر واحد: یتیح MPP للوکیل فتح حساب مسبق الدفع بسقف إنفاق، ثم بث مدفوعات صغیرة کثیرة مقابلہ عبر عدة سکک حتی یغلق الحساب.

ما ہو. تبنی Stripe وTempo بروتوکول MPP، مع إعلانات إطلاق عامة فی مارس 2026. Tempo ہی blockchain من الطبقة 1 حضنتہا Stripe وParadigm لمدفوعات الآلة عالیة التکرار. أطلق MPP مع شرکاء عبر Stripe وVisa وLightspark (شبکة Lightning) وغیرہم من لاعبی المنظومة؛ تنمو قائمة الشرکاء، لذلک تحقق من mpp.dev ووثائق MPP لدی Cloudflare للمشارکین الحالیین. ترخیصہ Apache 2.0. MPP ہو جواب Stripe فی طبقة التسویة علی x402: حالة استخدام متداخلة، وفلسفة مختلفة.

أین یجلس. یعیش MPP فی الطبقة 4 (التسویة) ویتنافس مباشرة مع x402 علی مدفوعات الآلة إلی الآلة. الفرق الأساسی: MPP متعدد السکک ویدعم المصادقة لکل charge ولکل session، بینما x402 قائم علی العملة المستقرة فقط ولکل طلب.

شکل HTTP. حیث یستخدم x402 رمز 402 وترویسات مخصصة، یرکب MPP الدفع فوق مصادقة HTTP القیاسیة. یعید الخادم WWW-Authenticate: Payment مع المتطلبات، ویعید العمیل المحاولة مع Authorization: Payment <signed-payload>، ویرد الخادم ب Payment-Receipt الذی یحمل إثبات التسویة. یجعل ذلک MPP یبدو کتدفق HTTP auth مألوف بدلا من بروتوکول مخصص.

نوعا intent.

Intent	دورة الحیاة	الأنسب لہ
charge	تحویل لمرة واحدة، یفوّض ویسوی فی round-trip واحد	مشتریات مفردة، وصول API لمرة واحدة، استبدال استدعاءات x402 الفردیة عندما تحتاج إلی عدة سکک
session	یفوّض الوکیل سقفا ومدة مسبقا، ثم یبث مدفوعات صغیرة مقاسة حتی یغلق	مدفوعات صغیرة عالیة التکرار حیث یکون توقیع کل طلب مکلفا؛ اشتراکات متکررة؛ نموذج "Stripe Subscription للوکلاء"

المقایضة مقابل x402.

البعد	x402	MPP
تکرار التفویض	لکل طلب (توقیع EIP-3009 فی کل مرة)	لکل charge أو لکل session (تفویض واحد، عدة استدعاءات مقاسة)
شکل HTTP	402 مخصص مع ترویسات دفع	WWW-Authenticate / Authorization / Payment-Receipt القیاسیة
السکک	عملة مستقرة فقط (USDC علی Base/Solana/EVM)	متعددة السکک (عملة Tempo المستقرة، Lightning، بطاقات، ACH)
الرسوم	بلا رسوم بروتوکول مع gas أقل من سنت	رسوم معالجة Stripe علی سکک البطاقات؛ شبہ صفر علی عملة Tempo المستقرة
دعم التکرار	محدود (یحتاج توقیعا لکل فترة)	أصلی عبر intent من نوع session
أفضل ملاءمة	استدعاءات API لمرة واحدة، وبنیة عامة	اشتراکات متکررة، وتجار مؤسسات مدمجون مع Stripe، وتدفقات تحتاج إلی fallback نقدی

ما الذی یتغیر فی SDK. یندمج MPP عبر Stripe Python SDK وسطح MPP فی Stripe. یمیل التکامل إلی إدارة الجلسات. الغلاف ہو خط أساس المفہوم 8 نفسہ.

استیراد from stripe.mpp import MPPSession واستدعاءات stripe.MPPSession أدناہ توضیحیة. لا توجد stripe.MPPSession ولا stripe.mpp فی Stripe Python SDK؛ MPP معیار Stripe وTempo (mainnet فی 18 مارس 2026)، ویدمج عبر سطح MPP لدی Stripe. مفہوم الجلسة (تفویض سقف مسبق، وبث استدعاءات مقاسة) حقیقی؛ أما API الدقیق ہنا فبدیل تعلیمی. طبقة SDK ونماذج النتائج ذات الأنواع حقیقیة.

from agents import Agent, function_tool, RunContextWrapper
from agents.tool_guardrails import (
    tool_input_guardrail,
    ToolInputGuardrailData,
    ToolGuardrailFunctionOutput,
)
from decimal import Decimal
import json
import stripe
from stripe.mpp import MPPSession
from .models import MPPSessionResult, MPPMeteredCallResult, PaymentToolResult

@tool_input_guardrail
def verify_mpp_session_authorized(data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
    """Refuse session creation if the user has not pre-authorized this service."""
    args = json.loads(data.context.tool_arguments or "{}")
    service_id = args.get("service_id", "")
    max_total = Decimal(str(args.get("max_total_usd", 0)))
    user_session = data.context.context["user_session"]
    if not user_session.can_authorize_mpp_session(max_total, service_id):
        return ToolGuardrailFunctionOutput.reject_content(
            f"User has not authorized MPP sessions of ${max_total} for service {service_id}"
        )
    return ToolGuardrailFunctionOutput.allow()

@function_tool(tool_input_guardrails=[verify_mpp_session_authorized])
async def mpp_create_session(
    ctx: RunContextWrapper,
    service_id: str,
    max_total_usd: Decimal,
    duration_seconds: int = 3600,
) -> MPPSessionResult:
    """Create an MPP session for one service with a spending cap and duration.
    Returns session_id for the metered calls that follow.
    The verify_mpp_session_authorized guardrail above has already validated consent."""

    user_session = ctx.context["user_session"]
    cents = int((max_total_usd * 100).quantize(Decimal("1")))
    session = stripe.MPPSession.create(
        service_id=service_id,
        max_total_usd=cents,
        duration_seconds=duration_seconds,
        user_session_id=user_session.id,
        # The MPP server picks the rail (stablecoin/Lightning/card) by service preference
    )

    ctx.context.setdefault("mpp_sessions", {})[service_id] = session.id
    return MPPSessionResult(
        session_id=session.id,
        status="active",
        expires_at=session.expires_at,
    )

@function_tool
async def mpp_metered_call(
    ctx: RunContextWrapper,
    service_url: str,
    payload: dict,
    cost_estimate_usd: Decimal,
) -> MPPMeteredCallResult | PaymentToolResult:
    """Make a metered call inside an active MPP session.
    The session's running spend updates automatically; the cap is enforced server-side."""

    service_id = extract_service_id(service_url)
    sessions = ctx.context.get("mpp_sessions", {})
    session_id = sessions.get(service_id)
    if not session_id:
        return PaymentToolResult(
            status="failed",
            error=f"No active MPP session for service {service_id}. Create one first.",
        )

    response = await mpp_client.metered_call(
        url=service_url,
        payload=payload,
        session_id=session_id,
        cost_estimate_usd=cost_estimate_usd,
    )
    return MPPMeteredCallResult(
        session_id=session_id,
        cost_usd=Decimal(str(response.cost_usd)),
        response_payload=response.payload,
        accumulated_session_spend_usd=Decimal(str(response.accumulated_session_spend_usd)),
    )

@function_tool
async def mpp_close_session(ctx: RunContextWrapper, session_id: str) -> MPPSessionResult:
    """Close an MPP session and finalize payment. Returns the total charged and the breakdown by rail."""
    closed = await stripe.MPPSession.close(session_id)
    return MPPSessionResult(
        session_id=session_id,
        status="closed",
        total_charged_usd=Decimal(str(closed.total_charged_usd)),
        rail_breakdown={
            rail: Decimal(str(amount))
            for rail, amount in closed.rail_breakdown.items()
        },
    )

api_consumer_agent = Agent(
    name="APIConsumerAgent",
    instructions="""Consume third-party APIs efficiently using MPP sessions.
    Workflow:
    1. Identify the service to consume
    2. Create an MPP session with mpp_create_session ($X cap, Y seconds duration)
    3. Make metered calls via mpp_metered_call
    4. Close the session with mpp_close_session when done
    Sessions are cheaper than per-request payment for high-frequency calls.""",
    tools=[mpp_create_session, mpp_metered_call, mpp_close_session],
    model="gpt-5.5",
)

ما ہو حقیقی: طبقة SDK ونماذج النتائج ذات الأنواع. وما ہو بدیل: stripe.MPPSession وmpp_client. دورة حیاة الجلسة نمط حقیقی؛ وAPI الدقیق فی Stripe ہنا مبسط للتعلیم. وہذا mock قابل للتشغیل:

from decimal import Decimal

class MockMPPSession:
    @staticmethod
    def create(**kw):
        return type("S", (), {"id": "mpp_sess_1", "expires_at": None})()
    @staticmethod
    async def close(session_id):
        return type("S", (), {"total_charged_usd": Decimal("4.20"),
                              "rail_breakdown": {"stablecoin": Decimal("4.20")}})()
mpp_client = type("Mock", (), {"metered_call": staticmethod(
    lambda **k: type("R", (), {"cost_usd": Decimal("0.05"), "payload": {},
                               "accumulated_session_spend_usd": Decimal("0.05")})())})()

ما یضیفہ إلی الغلاف. خطوة إعداد واحدة: یجب أن یکون MPP مفعلا فی حساب Stripe. یتولی خادم MPP لدی Stripe تکامل Tempo blockchain، لذلک لا یلمس الوکیل Tempo مباشرة. وبعد Stripe SDK وإدارة المفاتیح (کما فی ACP)، لا یوجد شیء إضافی.

تشغیلہ بمتانة (Inngest). تطابق جلسات MPP نمط الدوال طویلة التشغیل فی Inngest بنظافة. تصبح دورة حیاة الجلسة (أنشئ، استخدم، أغلق) تسلسلا من کتل step.run، مع إمکانیة step.sleep لانتہاء زمنی. نموذج الجلسة والتنفیذ المتین یترکبان جیدا: کلاہما مبنی لعمل متعدد الخطوات ذی حالة.

أین تخطئ الفرق. تنشئ جلسات کبیرة جدا أو طویلة جدا. سقف الجلسة ہو حد خسارتک إذا حدث خطأ. جلسة 1,000 دولار وضعت "للراحة" تعرضک لخسارة 1,000 دولار من حلقة وکیل تسوء. اضبط الجلسات علی حجم العمل المتوقع فعلا: لمہمة من 30 استدعاء، جلسة 5 دولارات مدتہا 5 دقائق أکثر أمانا من جلسة 50 دولارا مدتہا ساعة.

خلاصة المفہوم 11: MPP ہو جواب Stripe فی طبقة التسویة علی x402، مضبوط للقیاس القائم علی الجلسات والتوجیہ متعدد السکک. یغطی intentان، charge للدفعات المفردة وsession للبث المفوض مسبقا، المشتریات المفردة والقیاس المتکرر. بدائیة الجلسة أرخص من x402 للاستدعاءات عالیة التکرار، والتوجیہ متعدد السکک یتعامل مع العملة المستقرة وLightning والبطاقات فی غلاف واحد. یستخدم شکل HTTP ترویسات قیاسیة WWW-Authenticate: Payment وAuthorization: Payment بدلا من ترویسات x402 المخصصة، لذلک یبدو ک auth مألوف. تدمجہ عبر Stripe SDK وسطح MPP لدی Stripe، وینسجم التنفیذ المتین فی Inngest مع دورة حیاة الجلسة. اضبط سقوف الجلسات علی العمل المتوقع، لا علی "الراحة."

---

الجزء 4: قواعد الترکیب، متی تستخدم أی بروتوکولات معا

مشی الجزء 3 عبر البروتوکولات الأربعة واحدا تلو الآخر. الآن نعید ترکیبہا. قابلت الفکرة فی الجزء 1: یستخدم النظام الحقیقی عدة بروتوکولات فی الوقت نفسہ، واحدا لکل طبقة. یعطیک الجزء 4 قواعد الترکیبات التی تعمل، والتی تفشل، وکیف تبقی المکدس صغیرا بقدر ما تسمح بہ المہمة.

المفہوم 12: أصغر مکدس صالح لمدفوعات الوکلاء

فی سطر واحد: المکدس الصحیح ہو أصغر مجموعة بروتوکولات تطلق قیمة لحالة استخدام واحدة، لا البروتوکولات الأربعة فی کل طبقة.

قبل أن ترکب أی شیء، اسأل سؤالا واحدا: ما أصغر مکدس یطلق قیمة ہنا؟ الإجابة نادرا ما تکون "کل البروتوکولات الأربعة، کل طبقة." تبدأ معظم أنظمة الإنتاج بطبقة واحدة موصولة بالکامل، ولا تضیف الباقی إلا عندما تجبرہا حالة الاستخدام.

ہذا ہو أصغر مکدس لکل حالة استخدام شائعة. وہو یلمّح أیضا إلی القرارات الخمسة فی الجزء 5.

حالة الاستخدام	الطبقة 1 (الاکتشاف)	الطبقة 2 (Auth)	الطبقة 3 (التجارة)	الطبقة 4 (التسویة)	لماذا ہذا ہو MVP
تسوق المستہلک (وکیل یشتری سلع تجزئة لشخص)	واجہة تسوق بالذکاء الاصطناعی، أو خادم MCP مع فہرس تاجر	ACP SPT (أو تفویض AP2 فی المجالات المنظمة)	ACP	سکک البطاقات عبر Stripe	یرید معظم المشترین حمایة chargeback. ACP مع Stripe ہو المسار الذی یطلق الیوم.
وکیل یدفع ل API (وکیل یستدعی APIs طرف ثالث مدفوعة)	خادم MCP یدعم x402، أو دلیل Agent.market	توقیع EIP-3009 (افتراضی x402)	لا شیء: استدعاء API مباشر	x402 علی Base أو Solana	فی الآلة إلی الآلة، تنطبق الطبقتان 2 و4 معا. لا توجد دورة حیاة شراء.
مشتریات مؤسسة (وکیل یشتری من موردین معتمدین تحت قواعد)	اکتشاف A2A داخل شبکة الشرکاء	AP2 Intent Mandate (مطلوب للتدقیق)	ACP أو UCP لموردی الفہارس؛ API مباشر لمشتریات الخدمات	جلسات MPP للتکرار؛ ACP SPT عبر سکک البطاقات للشراء المفرد	مسار التدقیق ہو الجزء الذی لا یمکنک تجاوزہ. تفویضات AP2 مطلوبة.
سوق متعدد الوکلاء (وکیل یستأجر وکلاء آخرین)	A2A أو دلیل وکلاء	تفویض AP2 مع فحص سمعة ERC-8004	لا شیء: مباشر من وکیل إلی وکیل	x402 (الأکثر شیوعا)، أو MPP إذا کان Stripe موصولا بالفعل	الثقة تعمل فی الاتجاہین. یحتاج کل طرف إلی ہویة قابلة للتحقق وإثبات دفع.

قاعدة الترکیب. اختر البروتوکول فی کل طبقة التی تطلبہا حالة الاستخدام. لا تضف بروتوکولات إلی طبقات لا تلمسہا حالة الاستخدام أبدا. لا یحتاج وکیل یدفع ل API خالص إلی ACP. ولا ینبغی لوکیل تسوق مستہلک أن یتجہ إلی x402 لقمیص بقیمة 50 دولارا، لأن حمایة chargeback فی البطاقات تستحق رسوم 2.9%.

الفخ. تحاول بعض الفرق ربط ACP وAP2 وx402 وMPP کلہا معا "للمرونة." تحصل علی مساحة تکامل أکبر أربع مرات ولا جواب واضحا عن "أی بروتوکول یعمل متی." اختر مکدسا واحدا. أطلقہ. أضف مکدسا ثانیا فقط عندما تطلب حالة استخدام ثانیة ذلک.

خلاصة المفہوم 12: أصغر مکدس صالح ہو أصغر مجموعة بروتوکولات تطلق قیمة لحالة استخدام واحدة. تغطی أربعة مکدسات شائعة معظم الحالات. تسوق المستہلک ہو ACP مع سکک البطاقات. ووکیل API ہو x402 وحدہ. ومشتریات المؤسسة ہی AP2 مع ACP أو UCP ومع MPP أو البطاقات. وسوق متعدد الوکلاء ہو AP2 مع ERC-8004 ومع x402. لا تبن مکدسا عاما؛ اختر ترکیبا واحدا لکل حالة استخدام وأطلقہ.

المفہوم 13: متی تترکب البروتوکولات عبر الطبقات وتتنافس داخل طبقة واحدة

فی سطر واحد: البروتوکولات فی طبقات مختلفة مصممة لتتراکم معا؛ أما البروتوکولات فی الطبقة نفسہا فمصممة لتحل محل بعضہا، لذلک السؤال الوحید ہو ہل یقع بروتوکولان فی الطبقة نفسہا.

ترتبط البروتوکولات بطریقتین. إما أن تترکب لأنہا تقع فی طبقات مختلفة وبنیت لتتراکم، أو تتنافس لأنہا تقع فی الطبقة نفسہا وبنیت للاستبدال. یأتی معظم الالتباس المعماری من قراءة الحالة الثانیة کأنہا الأولی.

عبر الطبقات، بنیت للترکیب:

الترکیب	خریطة الطبقات	أین یطلق
AP2 + ACP	AP2 فی الطبقة 2 (auth بدرجة تدقیق)، وACP فی الطبقة 3 (التجارة)	مجالات منظمة حیث یحتاج تدفق ACP العادی إلی تدقیق إضافی
AP2 + x402	AP2 فی الطبقة 2 (تفویض mandate)، وx402 فی الطبقة 4 (تسویة عملة مستقرة)	تدفقات crypto-native تحتاج إلی تدقیق، عبر امتداد a2a-x402
ACP + x402	ACP فی الطبقة 3 (التجارة)، وx402 فی الطبقة 4 لتدفقات فرعیة بین الآلات داخل شراء مستہلک	منصات ہجینة حیث یتضمن شراء المستہلک بعض إنفاق API
MCP + x402 (via withX402Client)	MCP فی الطبقة 1 (الاکتشاف)، وx402 فی الطبقة 4 (التسویة)	نمط Cloudflare القیاسی لأدوات MCP المدفوعة

داخل طبقة واحدة، بنیت للتنافس:

المنافسة	الطبقة	متی یفوز کل واحد
AP2 vs. ACP SPT vs. TAP	الطبقة 2	AP2 لتدفقات درجة التدقیق؛ وACP SPT لتدفقات المستہلک الموصولة ب Stripe؛ وTAP لفحوص الہویة فقط
ACP vs. UCP	الطبقة 3	ACP للوصول إلی ChatGPT؛ وUCP للوصول إلی Gemini؛ والاثنان للبائعین عبر الواجہات
x402 vs. MPP	الطبقة 4	x402 للمدفوعات الصغیرة لمرة واحدة وتدفقات العملة المستقرة الخالصة؛ وMPP للجلسات والاشتراکات والتدفقات متعددة السکک

الاختبار. عندما تحتار بین بروتوکولین، اسأل شیئا واحدا: ہل ہما فی الطبقة نفسہا؟ إذا کان الجواب نعم، فاختر واحدا، أو ادفع تکلفة دعم الاثنین لتدفقات فرعیة مختلفة. وإذا کان الجواب لا، فہما غالبا یترکبان، والتصمیم الصحیح یستخدم الاثنین کثیرا.

ترکیب عملی: مکدس AP2 + x402. ہذا ہو النمط crypto-native، وشائع الآن فی B2B وتدفقات وکیل إلی وکیل:

Layer 1 (Discovery): A2A directory inside the partner network
Layer 2 (Auth):      AP2 Intent + Cart + Payment Mandates
Layer 3 (Commerce):  Often none (direct service request), or ACP for a catalog
Layer 4 (Settlement): x402 via the a2a-x402 extension

یرکب تجمیع SDK أدوات البروتوکولات من الجزء 3. ہذہ الأدوات (a2a_discover_partners وap2_create_intent_mandate والباقی) عرّفت فی المفاہیم 8 إلی 11؛ وہنا لا تفعل إلا ربطہا بوکیل واحد.

agent = Agent(
    name="EnterpriseB2BAgent",
    instructions="...",
    tools=[
        # Layer 1: Discovery
        a2a_discover_partners,
        # Layer 2: Authorization
        ap2_create_intent_mandate,
        ap2_create_cart_mandate,
        # Layer 4: Settlement (a2a-x402 composes Layers 2 and 4)
        ap2_settle_via_x402,
    ],
    model="gpt-5.5",
    # No commerce tools: direct B2B procurement.
)

خلاصة المفہوم 13: تترکب البروتوکولات فی طبقات مختلفة: AP2 مع x402، وACP مع x402، وMCP مع x402. وتتنافس البروتوکولات فی الطبقة نفسہا: AP2 ضد ACP SPT، وACP ضد UCP، وx402 ضد MPP. الاختبار ہو "ہل ہذہ فی الطبقة نفسہا؟" إذا نعم، اختر واحدا. وإذا لا، فہی غالبا تترکب. مکدس AP2 مع x402 ہو الترکیب القیاسی ل B2B crypto-native.

المفہوم 14: الکلفة والکمون، ما الذی یفرض الاختیار

فی سطر واحد: یحدد حجم المعاملة والزمن الذی یمکنک انتظارہ بروتوکول التسویة، لأن رسوم البطاقات تسحق المدفوعات الصغیرة وcheckout البطیء یکسر الحلقات الضیقة.

لکل ترکیب سعر وسرعة. یکلف تدفق تسوق مستہلک علی ACP مع سکک بطاقات نحو 2.9% + 0.30 دولار لکل معاملة ویستغرق 5 إلی 30 ثانیة من البدایة إلی النہایة. ویکلف وکیل API علی x402 أقل من سنت ویستغرق 1 إلی 2 ثانیة. یحدد الترکیب الصحیح جزئیا مقدار الکلفة والانتظار الذی تستطیع حالة الاستخدام تحملہ.

الکلفة لکل معاملة حسب الترکیب.

الترکیب	الکلفة النموذجیة لکل معاملة	الکمون النموذجی
ACP + card rails (تسوق المستہلک)	2.9% + 0.30 دولار (سعر Stripe)	5 إلی 30 ثانیة
ACP + MPP sessions (اشتراکات)	2.9% علی البطاقات، أو نحو 0.5% علی عملة Tempo المستقرة، لکل جلسة	1 إلی 3 ثوان لکل استدعاء مقاس
AP2 + x402 (B2B stablecoin)	gas أقل من سنت، بلا رسوم بروتوکول	2 إلی 5 ثوان (توقیع التفویض یضیف 1 إلی 3)
x402 only (API-paying)	gas أقل من سنت، بلا رسوم بروتوکول	1 إلی 2 ثانیة
MPP sessions only (recurring API)	شبہ صفر علی عملة Tempo المستقرة؛ سعر Stripe علی البطاقات	50 إلی 500 ms لکل استدعاء مقاس داخل جلسة نشطة

ما یفرضہ المال. الرسوم التی تتجاوز نحو 5% من المعاملة مشکلة. استدعاء API بقیمة 0.05 دولار یدفع 2.9% + 0.30 دولار فی رسوم بطاقة یکلف رسوما أکثر من قیمة الاستدعاء نفسہ، وہذہ إشارة واضحة لاستخدام x402 أو MPP بعملة مستقرة بدلا من ذلک. أما قمیص بقیمة 50 دولارا یدفع النسبة نفسہا ومعہا 0.30 دولار فلا مشکلة. الخط بالدولار حیث تتوقف سکک البطاقات عن المنطقیة یقع حول 5 إلی 10 دولارات. تحت ذلک تفوز سکک مدفوعات الآلة؛ وفوق ذلک تکون حمایة chargeback فی البطاقات عادة مستحقة للرسوم.

ما یفرضہ الکمون. الانتظار فوق 5 ثوان لکل خطوة تواجہ المستخدم مشکلة. یمکن لتوقیع تفویض AP2 أن یضیف 1 إلی 3 ثوان، وأکثر بکثیر إذا انتظر توقیع إنسان؛ ویضیف checkout عبر ACP 5 إلی 30 ثانیة. فی تدفقات وکیل إلی وکیل بلا إنسان فی الحلقة، تکون المیزانیة أضیق غالبا، أحیانا دون الثانیة، مما یجعل x402 علی Base وMPP علی Tempo الخیارین الافتراضیین.

شجرة القرار مضغوطة.

What is the transaction value?
├── Sub-dollar (per-call API, per-token billing)
│   → x402 only, or MPP sessions
├── $1 to $10 (small, low-stakes buys)
│   → x402 or MPP, with AP2 audit if you need it
├── $10 to $1,000 (consumer purchases)
│   → ACP + card rails (chargeback cover is worth the fee)
└── $1,000+ (B2B, enterprise procurement)
    → AP2 + ACP/UCP + MPP sessions, or bank rails

What is the latency budget?
├── Sub-second (multi-agent loops)
│   → MPP sessions on Tempo, or x402 on Base
├── 1 to 5 seconds (interactive)
│   → x402 or MPP; AP2 only if mandates are pre-signed
└── 5+ seconds (an acceptable user wait)
    → Full ACP checkout works

خلاصة المفہوم 14: لاختیارات الترکیب کلفة وکمون حقیقیان. تکلف سکک البطاقات 2.9% + 0.30 دولار لکنہا تمنحک حمایة chargeback؛ وتکلف سکک العملة المستقرة أقل من سنت لکنہا تحتاج إلی سباکة crypto-native. تتوقف سکک البطاقات عن المنطقیة حول 5 إلی 10 دولارات لکل معاملة. ویصبح checkout عبر ACP بطیئا جدا حول 5 ثوان للتدفقات التی تواجہ المستخدم. دع الکلفة والکمون یفرضان الترکیب، لا الذوق.

---

الجزء 5: مختبر القرار، خمسة أمثلة عملیة

أعطتک الأجزاء 2 إلی 4 الإطار: أربع طبقات، وبضعة بروتوکولات لکل طبقة، وترکیب عبر الطبقات. یمشی الجزء 5 عبر خمسة قرارات حقیقیة. یوضح کل واحد المنطق الکامل: ما الطبقات التی تلمسہا حالة الاستخدام، وأی بروتوکول فی کل طبقة، ولماذا، وکیف یبدو کود الوکیل.

اقرأ عبر الصف لتری مکدس حالة استخدام کامل. واقرأ أسفل العمود لتری ما یتغیر فی طبقة واحدة مع تغیر حالة الاستخدام. تمشی القرارات الخمسة أدناہ عبر الصفوف بالتفصیل. تغطی الأربعة الأولی المصفوفة؛ ویعید الخامس بناء واحد منہا فی toolchain مختلفة تماما لیثبت أن الإطار غیر مربوط بأی مورد.

القرار 1: وکیل تسوق للمستہلک (نمط ChatGPT Instant Checkout)

حالة الاستخدام. تبنی وکیلا یساعد الناس علی التسوق لدی تجار یدعمون ACP مثل Walmart وEtsy وبائعی Shopify. یقول المستخدم ما یرید؛ یبحث الوکیل فی الفہارس، ویعرض الخیارات، وینفذ checkout عند التأکید. مشتری واحد إلی تاجر واحد، 5 إلی 500 دولار لکل طلب، مع ضرورة الاستردادات وchargebacks.

المشی عبر الطبقات الأربع.

• الطبقة 1 (الاکتشاف). یجب أن یعثر الوکیل علی منتجات عبر تجار کثیرین. یمکنک دمج فہرس MCP لکل تاجر، أو استخدام واجہة ChatGPT Shopping التی تجمع تجار ACP بالفعل. الاختیار: واجہة التسوق بالذکاء الاصطناعی، لأن عمل الاکتشاف منجز بالفعل وربط ملیون فہرس بنفسک غیر قابل للحیاة.
• الطبقة 2 (التفویض). المستخدم مسجل فی الواجہة ویؤکد کل عملیة شراء، لذلک التفویض بسیط. الاختیار: ACP SPT، تصدرہ Stripe لکل شراء، ومحدد لتاجر واحد ومبلغ واحد ونافذة 10 دقائق.
• الطبقة 3 (التجارة). دورة الحیاة الکاملة مہمة: السلة، وcheckout، والتنفیذ، والنزاعات، والاستردادات. الاختیار: ACP، البروتوکول المبنی لہذا بالضبط.
• الطبقة 4 (التسویة). تقع قیم 5 إلی 500 دولار فی منطقة سکک البطاقات المناسبة، وتستحق حمایة chargeback الرسوم. الاختیار: سکک البطاقات عبر Stripe، وہی السکة التی یفترضہا ACP افتراضیا.

التنفیذ. ہذا ہو کود المفہوم 8؛ الأدوات تأتی من المفہوم 8.

shopping_agent = Agent(
    name="ShoppingAgent",
    instructions="""Help the user shop. Workflow:
    1. Use acp_browse_merchant to find products matching the request
    2. Show matched items; wait for the user to confirm
    3. On confirm, use acp_create_cart_and_checkout to buy
    4. Use acp_check_order for status
    5. Use acp_refund only when the user asks""",
    tools=[acp_browse_merchant, acp_create_cart_and_checkout, acp_check_order, acp_refund],
    model="gpt-5.5",
)

أکثر فشل محتمل فی الإنتاج. عدم تطابق السلة: یبنی الوکیل سلة لا تطابق الطلب ("طلبت الأحمر، فوصل الوردی"). الإصلاح: اطلب من المستخدم تأکید السلة قبل إصدار SPT، وسجل دقة السلة، واضبط التعلیمات عندما تہبط الدقة تحت 95%.

تشغیلہ بمتانة (Inngest). استخدم نمط step.wait_for_event من المفہوم 8 لبوابة تأکید السلة، مع سقف concurrency لکل مستخدم.

اختر ہذا أولا. ہذہ ہی حالة الاستخدام الحیة الیوم: ChatGPT Instant Checkout، ومنظومة ACP، وکل تاجر Shopify لدیہ ACP مفعلا. إذا کنت تستطیع إطلاق ترکیب واحد فقط، فأطلق ہذا.

القرار 2: وکیل بحث یدفع لواجہات API (نمط x402 فقط)

حالة الاستخدام. تبنی وکیل بحث یدفع لواجہات API طرف ثالث مقابل بیانات: تغذیات مالیة، وأخبار، وبحث متخصص. یکتشف APIs المدفوعة فی وقت التشغیل عبر دلیل مثل Agent.market، ویوازن الکلفة مقابل القیمة، ویدفع لکل استدعاء. مدفوعات صغیرة عالیة التکرار من 0.001 إلی 0.50 دولار، بلا إنسان فی الحلقة بعد بدء المہمة، ولا دورة حیاة تجارة.

المشی عبر الطبقات الأربع.

• الطبقة 1 (الاکتشاف). تتیح Agent.market وأدلة مشابہة محجوبة ب x402 للوکیل العثور علی خدمات فی وقت التشغیل؛ وتعالج خوادم MCP التی تدعم x402 الخدمات المدمجة مسبقا. الاختیار: Agent.market مع MCP عبر Cloudflare، اکتشاف وقت تشغیل مع مجموعة fallback موصلة مسبقا.
• الطبقتان 2 و4 (التفویض والتسویة، منطبقتان). لا إنسان بعد بدء المہمة. تحد حدود المحفظة علی السلسلة من إنفاق کل معاملة؛ وتعمل حدود المستخدم عبر tool_input_guardrail فی SDK علی کل أداة دفع. توقیع EIP-3009 ہو التفویض والتسویة معا. الاختیار: x402 علی Base (USDC)، بلا بروتوکول تفویض منفصل.
• الطبقة 3 (التجارة). "الشراء" مجرد استدعاء API. الاختیار: لا شیء، وصول API مباشر عبر x402.

التنفیذ. ہذا ہو کود المفہوم 10؛ الأدوات تأتی من المفہوم 10.

research_agent = Agent(
    name="ResearchAgent",
    instructions="""Research the user's query by paying for data via x402.
    1. Use x402_search_agent_market to find relevant paid services
    2. Use x402_fetch to pull data (max $0.10 per call)
    3. Write up the findings
    Stay under $10 per session.""",
    tools=[x402_fetch, x402_search_agent_market],
    mcp_servers=[research_mcp_with_payments],
    model="gpt-5.5",
    # Spend caps live on x402_fetch via tool_input_guardrails
    # (Concept 10's enforce_x402_session_cap), not on the agent.
)

أکثر فشل محتمل فی الإنتاج. إنفاق منفلت من حلقة عالقة: یعید الوکیل جلب البیانات نفسہا ویحرق المیزانیة. الإصلاح: حدود المحفظة علی السلسلة (السلامة التی تحمیک فعلا)، وحواجز إنفاق الجلسة فی SDK، وذاکرة dedup حتی لا تدفع عملیات الجلب المتطابقة مرة أخری.

تشغیلہ بمتانة (Inngest). تفید memoization فی step.run ہنا. إذا وقع crash وسط الجلسة، تستأنف إعادة المحاولة مع البیانات المدفوعة بالفعل محفوظة. ویمنع سقف concurrency لکل مستخدم دفعة واحدة من السیطرة.

آلة إلی آلة خالصة. تنطبق الطبقتان 2 و4 فی توقیع واحد، والطبقة 3 فارغة. ہذا المکدس أبسط بنیویا من القرار 1: بروتوکولات أقل، ونقاط تکامل أقل، وکلفة أقل لکل استدعاء. المقابل ہو غیاب حمایة chargeback ودلالات التجارة، وہذا مناسب لأن حالة الاستخدام لا تحتاج أیہما.

القرار 3: وکیل مشتریات مؤسسة (نمط AP2 مع مکدس مرکب)

حالة الاستخدام. تبنی وکیل مشتریات لمؤسسة منظمة فی الخدمات المالیة. یفوّض المشترون مہاما: "اشتر 50 لوحة مفاتیح مریحة من موردینا المعتمدین، بأقل من 5,000 دولار، قبل الجمعة." مسار التدقیق مطلوب قانونیا، وحدود الإنفاق تعمل علی عدة مستویات، والموردون معتمدون مسبقا، لذلک لا یوجد اکتشاف وقت تشغیل.

المشی عبر الطبقات الأربع.

• الطبقة 1 (الاکتشاف). قائمة الموردین معروفة مسبقا. الاختیار: خادم MCP داخلی مع فہارس الموردین، لأن نطاق الاکتشاف محدود.
• الطبقة 2 (التفویض). مسار تدقیق غیر قابل للإنکار ہو الجزء الذی لا یمکنک تجاوزہ؛ والسجل غیر القابل للإنکار ہو سجل لا یستطیع الموقّع إنکارہ لاحقا. تعطی تفویضات AP2 ذلک بالضبط. الاختیار: AP2، مع Intent Mandate عند إنشاء المہمة، وCart Mandate قبل checkout، وPayment Mandate عند التسویة، وکل واحد یوقّعہ مسؤول المشتریات.
• الطبقة 3 (التجارة). یعرّض الموردون الکبار ACP أو UCP؛ ویعرض الأصغر APIs B2B مباشرة. الاختیار: ACP للموردین الداعمین ل ACP، وAPI مباشر للباقی؛ ویتعامل الوکیل مع الاثنین.
• الطبقة 4 (التسویة). یفضل الموردون المتکررون جلسات MPP؛ وتفضل المشتریات المفردة سکک البطاقات لحمایة chargeback عند القیم الأعلی. الاختیار: جلسات MPP للتکرار، وACP SPT مع سکک البطاقات للمشتریات المفردة، ویختار ذلک حسب تاریخ المورد.

التنفیذ. یرکب ہذا أدوات المفاہیم 8 و9 و11.

procurement_agent = Agent(
    name="ProcurementAgent",
    instructions="""Run procurement under audit-grade compliance:
    1. ALWAYS create an Intent Mandate first via ap2_create_intent_mandate
    2. Search approved suppliers via the internal MCP server
    3. Build the cart and create a Cart Mandate via ap2_create_cart_mandate
    4. Recurring suppliers: use an MPP session.
       One-off buys: use ACP plus card rails via ap2_settle_via_acp
    5. Record every mandate ID in the procurement audit log""",
    mcp_servers=[approved_suppliers_mcp],
    tools=[
        ap2_create_intent_mandate,
        ap2_create_cart_mandate,
        ap2_settle_via_acp,
        mpp_create_session,
        mpp_metered_call,
        mpp_close_session,
    ],
    model="gpt-5.5",
    # Caps and mandate rules run via tool_input_guardrails on the paying tools
    # (Concepts 9, 11, 15). require_intent_mandate on ap2_create_cart_mandate blocks
    # any cart with no prior Intent Mandate; enforce_per_run_spend_cap blocks any
    # payment over the user's run cap.
)

أکثر فشل محتمل فی الإنتاج. عدم تطابق نطاق Intent Mandate: یوقّع المسؤول تفویضا، یعمل الوکیل، ثم لا تناسب السلة التفویض. الإصلاح: تحقق من نطاق التفویض قبل أن یبدأ الوکیل التسوق (قاعدة المفہوم 9 "أنشئ Intent Mandates أولا")، وارفض المہام التی یتجاوز نطاقہا ما یستطیع المستخدم تفویضہ.

تشغیلہ بمتانة (Inngest). توقیع تفویضات AP2 یناسب step.wait_for_event بطبیعتہ. تستخدم المہام متعددة المراحل step.run لکل مرحلة، مع سقف concurrency لکل مستخدم.

صناعة منظمة. تفرض قواعد التدقیق AP2 فی الطبقة 2؛ ویفرض الموردون المتنوعون ACP وAPIs مباشرة معا فی الطبقة 3؛ ویفرض التکرار مقابل الشراء المفرد MPP والبطاقات معا فی الطبقة 4. ہذا الترکیب أثقل من القرارین 1 و2، ومطلب التدقیق ہو ما یبرر الوزن.

القرار 4: سوق متعدد الوکلاء (نمط AP2 مع x402 ومع ERC-8004)

حالة الاستخدام. تبنی منصة تستأجر فیہا الوکلاء وکلاء آخرین. یحتاج Agent A إلی بحث؛ ویبیع Agent B البحث کخدمة x402. لا یثق أحدہما بالآخر بعد، ویجب أن تکون المعاملات قابلة للتحقق، والدفع crypto-native خالص بلا بطاقات. وکیل إلی وکیل، 0.10 إلی 100 دولار لکل معاملة، وکل طرف یحتاج إلی ہویة قابلة للتحقق.

المشی عبر الطبقات الأربع.

• الطبقة 1 (الاکتشاف). ینشر Agent B قدرتہ عبر A2A؛ ویعثر علیہ Agent A. الاختیار: A2A، البروتوکول المبنی لہذا.
• الطبقة 2 (التفویض). لا إنسان عند وقت المعاملة، لکن یجب أن تکون الثقة قابلة للتحقق فی الاتجاہین. تثبت تفویضات AP2 موافقة المستخدم؛ ویمنح ERC-8004 ل Agent B سمعة علی السلسلة یستطیع Agent A فحصہا أولا. الاختیار: AP2 مع ERC-8004، مرکبان للتحقق الثنائی الکامل.
• الطبقة 3 (التجارة). لا سلال، ولا استردادات، فقط "نفذ ہذہ المہمة وسلم التقریر." الاختیار: لا شیء، طلب واستجابة مباشران عبر A2A.
• الطبقة 4 (التسویة). Crypto-native، دون ثانیة، ولا حاجة إلی حمایة chargeback. الاختیار: x402 عبر امتداد a2a-x402 إلی AP2.

التنفیذ. یرکب ہذا أدوات المفاہیم 9 و10 مع اکتشاف A2A.

researcher_hiring_agent = Agent(
    name="ResearcherHiringAgent",
    instructions="""Hire research-specialist agents to work for you:
    1. Use a2a_discover_researchers to find available agents
    2. Check ERC-8004 reputation (>50 successful jobs, no flagged disputes)
    3. Create an Intent Mandate scoped by amount and recipient
    4. Submit the task via A2A with the mandate attached
    5. Receive the result; settle via ap2_settle_via_x402""",
    tools=[
        a2a_discover_researchers,
        erc8004_check_reputation,
        ap2_create_intent_mandate,
        a2a_submit_task_with_mandate,
        ap2_settle_via_x402,
    ],
    model="gpt-5.5",
)

أکثر فشل محتمل فی الإنتاج. الثقة فی سمعة تم التلاعب بہا: درجات ERC-8004 قابلة للتدقیق، لکن یستطیع مشغل تضخیم واحدة بوظائف صغیرة ناجحة. الإصلاح: اجمع السمعة مع إشارات أخری (ہویة المشغل، عتبات حجم المعاملة، تاریخ النزاعات)، وأضف مراجعة بشریة فوق مبلغ محدد للأطراف المقابلة لأول مرة.

تشغیلہ بمتانة (Inngest). استخدم fan out عند استئجار عدة متخصصین معا؛ واستخدم step.wait_for_event لکل نتیجة وstep.run لکل مرحلة. یلمس ہذا القرار کل بدائیات Inngest.

اقتصاد متعدد الوکلاء خالص. لا إنسان داخل الحلقة عند وقت المعاملة؛ یعمل الوکیلان داخل نطاقات مفوضة مسبقا. ہذا ہو الشکل الذی یبنی حولہ اقتصاد الوکلاء، ولدیہ أکثر أنماط الفشل، لأن الثقة الثنائیة بلا علاقة سابقة صعبة، ومکدس البروتوکولات لا یحل إلا جزءا منہا.

القرار 5: مکدس بلا Stripe ولا OpenAI (إثبات أن الإطار ینتقل)

استخدمت کل عینة کود حتی الآن stripe.PaymentTokens.create(...) وOpenAI Agents SDK. ہذہ ہی أکثر التکاملات نضجا ل ACP، وSDK ہو وقت تشغیل ہذہ الدورة، لکن المعماریة ذات الطبقات الأربع محایدة تجاہ المکدس بالتصمیم، والدورة التی تعرض مکدسا واحدا فقط لم تثبت ذلک. لذلک یعید ہذا القرار بناء القرار 2، وکیل البحث الذی یدفع ل API، علی toolchain مختلفة تماما: Google Agent Development Kit (ADK) لوقت التشغیل، ومحفظة عقد ذکی من Coinbase للہویة علی السلسلة، وتفویضات AP2 للتفویض، وx402 مباشر للتسویة. صفر Stripe، صفر OpenAI.

تبقی حالة الاستخدام ہی حالة القرار 2. وکیل بحث یدفع 0.001 إلی 0.10 دولار لکل استدعاء، بسقف 10 دولارات لکل جلسة. دون الدولار، بلا إنسان بعد التفویض، وتسویة آلة إلی آلة. وتبقی المعماریة أیضا معماریة القرار 2: یطبق x402 الطبقتین 2 و4 معا، ولا طبقة تجارة، وMCP للاکتشاف. تتغیر المکتبة فقط.

الکتلة أدناہ توضیحیة. بنیة Google ADK (Agent ومزخرف الأداة) حقیقیة وgoogle-adk حزمة حقیقیة. قطع الدفع بدائل: حزمة AP2 الحقیقیة ہی ap2 بحقوق تفویض مختلفة جدا وبلا فئة MandateSigner، وتضبط محفظة Coinbase عبر coinbase_agentkit وفئتہ SmartWalletProvider، والاستدعاء الحی ل x402 یحتاج إلی حساب ممول ونقطة نہایة 402 حقیقیة. لا یتحرک مال حقیقی ہنا. المہم ہو الشکل، لا مشتری قابل للتشغیل.

from google.adk import Agent
from google.adk.tools import function_tool  # ADK's tool decorator
from coinbase_agentkit import AgentKit, SmartWalletProvider
from decimal import Decimal
from datetime import datetime, timedelta

# Shared result models come from the Pydantic sidebar in Part 3.
from .models import X402PaymentResult, PaymentToolResult, DiscoveryResult

# --- Illustrative stand-ins for the payment rails (real APIs differ) ---
class MockMandate:
    def __init__(self, mid, rules=None): self.id, self.rules = mid, (rules or {})
class MockSigner:
    async def sign(self, mandate): return mandate          # real AP2 signs over A2A
agent_market_client = type("Mock", (), {"search": staticmethod(lambda **k: [])})()
x402_client = type("Mock", (), {})()                       # real client: x402-client
# -----------------------------------------------------------------------

# Layer 2 (Authorization): a Coinbase smart-contract wallet gives the agent its
# on-chain identity and its spend caps. This is the analog of a Stripe customer
# plus per-customer caps, but enforced by the chain.
wallet_provider = SmartWalletProvider(
    config={
        "chain": "base-mainnet",
        "spend_limits": {
            "per_transaction_usdc": Decimal("0.50"),
            "per_session_usdc": Decimal("10.00"),
            "per_day_usdc": Decimal("100.00"),
        },
    },
)
agent_kit = AgentKit(wallet_provider=wallet_provider)

# Layer 2 (Authorization): an AP2 Intent Mandate, signed by the user at session start.
# The analog of a signed, revocable Stripe authorization, but declarative.
async def create_research_intent_mandate(user_did, user_signer, session_cap_usdc):
    mandate = MockMandate(
        "intent_mock_1",
        rules={
            "max_total_usd": str(session_cap_usdc),
            "allowed_categories": ["data-api", "research-service"],
            "expires_at": (datetime.utcnow() + timedelta(hours=1)).isoformat(),
        },
    )
    return await user_signer.sign(mandate)

# Layer 1 (Discovery) + Layer 4 (Settlement) as one tool.
# ADK's @function_tool is the analog of the SDK's @function_tool.
@function_tool
async def x402_paid_fetch(url: str, max_payment_usdc: Decimal) -> X402PaymentResult | PaymentToolResult:
    """Fetch a URL that may need x402 payment up to max_payment_usdc.
    The wallet handles the signature; the on-chain cap is the safety that protects you."""
    # ADK has no tool_input_guardrail, so the check runs in-tool,
    # backed by the wallet's on-chain cap (the layer nothing can bypass).
    resp = await x402_client.get(url, max_payment_usdc=max_payment_usdc)
    return X402PaymentResult(
        content=resp.content,
        amount_paid_usdc=Decimal(str(resp.amount_paid_usdc)),
        tx_hash=resp.tx_hash,
    )

@function_tool
async def search_agent_directory(query: str, max_price_per_call_usdc: Decimal) -> list[DiscoveryResult]:
    """Search Agent.market for x402-paywalled services."""
    results = await agent_market_client.search(query=query, max_price_per_call_usdc=max_price_per_call_usdc)
    return [
        DiscoveryResult(
            service_id=r.service_id,
            name=r.name,
            description=r.description,
            price_per_call_usdc=Decimal(str(r.price_per_call_usdc)),
            endpoint_url=r.endpoint_url,
        )
        for r in results
    ]

# The agent itself: a Google ADK Agent, the direct analog of the SDK's Agent.
research_agent = Agent(
    name="research-agent",
    description="Research the user's query by paying for data via x402.",
    instructions="""Research the query.
    1. Use search_agent_directory to find relevant paid services
    2. Use x402_paid_fetch to pull data ($0.50 max per call)
    3. Write up the findings
    Stay under $10 per session.""",
    model="deepseek-v4-flash",  # illustrative; any ADK-compatible model id works
    tools=[search_agent_directory, x402_paid_fetch],
)

# Driver: the user signs the Intent Mandate once at session start;
# the agent then runs on its own inside the mandate's scope until the session ends.
async def run_research_session(user_did, user_signer, query):
    intent = await create_research_intent_mandate(
        user_did=user_did,
        user_signer=user_signer,
        session_cap_usdc=Decimal("10.00"),
    )
    return await research_agent.run_async(
        query,
        context={"intent_mandate": intent, "wallet": agent_kit},
    )

الترجمة سطرا بسطر. کود القرار 2 باستخدام OpenAI مع Stripe علی الیسار، وکود القرار 5 باستخدام Google ADK مع Coinbase علی الیمین. ہذا الجدول ہو الخلاصة: کل صف ہو المفہوم نفسہ باسم مختلف.

القرار 2 (OpenAI + Stripe)	القرار 5 (Google ADK + Coinbase)	المفہوم نفسہ، مکتبة مختلفة
from agents import Agent, function_tool	from google.adk import Agent + from google.adk.tools import function_tool	وقت تشغیل الوکیل
@function_tool (OpenAI Agents SDK)	@function_tool (Google ADK)	مزخرف الأداة
RunContextWrapper	وسیط context={...} إلی run_async	حالة کل تشغیل
stripe.Customer.modify(...) for caps	SmartWalletProvider(spend_limits={...})	حدود الإنفاق، أصلیة للسلسلة
tool_input_guardrail decorator	فحص داخل الأداة + حدود المحفظة	تحقق قبل التنفیذ
Runner.run(agent, ...)	agent.run_async(...)	تنفیذ الوکیل

ما یبقی متطابقا. المعماریة: الطبقة 1 ہی MCP أو دلیل، والطبقة 2 تفویض مع حدود محفظة، والطبقة 3 لا شیء (تطبق الآلة إلی الآلة التجارة معا)، والطبقة 4 x402. البدائیات: Intent Mandate، وتوقیعات EIP-3009، واستجابات 402، وترویسات payment-signature، وحدود الإنفاق علی السلسلة. الإطار ہو ما یبقی بعد تبدیل المکتبة.

فرقان تشغیلیان حقیقیان.

1. لا یملک Google ADK حاجز إدخال أداة أصلیا من الدرجة الأولی (حتی منتصف 2026). إن tool_input_guardrail فی SDK مفید فعلا للفحوص قبل التنفیذ؛ ولا یملک مزخرف الأداة فی ADK مقابلا مباشرا بعد. workaround ہو تحقق داخل الأداة مدعوم بحدود المحفظة علی السلسلة. ما زالت الحدود تحمیک؛ الفحص داخل الأداة یفشل أسرع فقط. إذا اخترت ADK، فأنت تقایض راحة حاجز الأمان بقصة مختلفة متعددة الوکلاء.
2. توقیع تفویضات AP2 أکثر أصلیة ہنا. بنت Google AP2، لذلک تدمج منظومة ADK تدفقات واجہة توقیع التفویض بسلاسة أکبر. إذا کانت حالة استخدامک تعتمد بقوة علی تفویض صارم بال mandating (القرارات 3 و4)، فإن ADK مع AP2 ملاءمة حقیقیة، لا مجرد بدیل.

خلاصة القرار 5: معماریة الطبقات الأربع لیست قصة Stripe وOpenAI متنکرة. الاکتشاف، والتفویض، والتجارة، والتسویة؛ اختر بروتوکولا واحدا لکل طبقة، وبررہ مقابل حالة الاستخدام: ہذا یبقی بعد أی تبدیل مکتبة. استخدم القرار 5 Google ADK ومحفظة Coinbase لبناء الترکیب نفسہ تماما مثل القرار 2؛ تغیرت الاستیرادات فقط. إذا لم یمکن التعبیر عن إطار فی مکدس مختلف، فہو درس مکتبة یرتدی زیا تنکریا. ہذا الإطار لیس کذلک.

---

الجزء 6: مخاوف الإنتاج، ما الذی یقتلک عندما یعمل النظام فعلا

بنت الأجزاء 1 إلی 5 الإطار ومشت عبر قرارات حقیقیة. یغطی الجزء 6 الأشیاء التی تحدد ہل یصمد مکدسک أمام مستخدمین حقیقیین. ہذہ ہی الإخفاقات التی لا تظہر فی demo وتظہر فی الساعة 2 صباحا.

مسار القارئ

إذا کنت تقرأ للفہم لا للإطلاق، یمکنک قراءة الجزء 6 بسرعة. وإذا کنت تبنی أیا من ہذا بجدیة، فہنا یصبح الأمر حقیقیا. المفاہیم الأربعة ہنا ہی الفرق بین نظام یعمل ونظام یستنزف محفظة.

المفہوم 15: فرض حدود الإنفاق علی ثلاثة مستویات معماریة

فی سطر واحد: أوقف الوکیل عن تجاوز الإنفاق بفرض الحد فی ثلاثة أماکن مستقلة، حتی یلتقط المکانان الآخران خطأ أحدہا.

أکبر طریقة یفشل بہا نظام تجارة وکلاء فشلا سیئا بسیطة: ینفق الوکیل أکثر مما سمح لہ. یمکن لحلقة وکیل عالقة أن تستنزف محفظة فی ثوان. لکل بروتوکول سقفہ الخاص (مبلغ SPT فی ACP، وسقف جلسة MPP، وحد x402 لکل طلب)، لکن لا یکفی أی واحد منہا وحدہ. تفرض أنظمة الإنتاج حدود الإنفاق علی ثلاثة مستویات منفصلة.

المستوی 1: حدود المحفظة وطریقة الدفع. ہذا ہو السقف الذی یحمیک فعلا. تحمل محفظة العقد الذکی للوکیل (ل x402) أو حساب Stripe الخاص بہ (ل ACP وMPP) حدود إنفاق مضبوطة علی مستوی البنیة التحتیة. تفرض السلسلة أو Stripe ہذہ الحدود مہما فعل کود الوکیل. ہذا ہو المستوی الوحید الذی یصمد عندما تفشل حلقة الوکیل تماما.

ل x402 مع محفظة عقد ذکی:

استدعاء SmartContractWallet.deploy(...) أدناہ توضیحی. یبین أین تعیش حدود المستوی 1، ولا یمثل حزمة pip حقیقیة. عملیا تضبط ہذہ الحدود علی محفظة عقد ذکی حقیقیة (مثلا عبر SmartWalletProvider فی Coinbase AgentKit). الدرس الحقیقی ہو انضباط المستویات الثلاثة.

from decimal import Decimal

# Set ONCE when the wallet is deployed. The agent cannot change this.
wallet_spend_limits = {
    "max_per_transaction_usdc": Decimal("10.00"),    # cap per single transfer
    "max_per_day_usdc": Decimal("100.00"),           # rolling 24-hour cap
    "max_per_merchant_usdc": Decimal("50.00"),       # cap to any single recipient
}
agent_wallet = SmartContractWallet.deploy(
    owner=user_did,
    spend_limits=wallet_spend_limits,
    chain="eip155:8453",  # Base
)

فی ACP أو MPP مع Stripe، یعیش السقف علی عمیل Stripe:

stripe.Customer.modify(...) استدعاء Stripe API حقیقی. یعمل ضد حساب Stripe الخاص بک.

# Set once via the Stripe Dashboard or API. The caps live in Stripe's infrastructure.
stripe.Customer.modify(
    user_session.stripe_customer_id,
    metadata={
        "max_per_session_usd": "500",
        "max_per_day_usd": "2000",
    },
)
# When an SPT or MPP session is minted above these, Stripe rejects it at the API level.

المستوی 2: حواجز أدوات SDK. یعمل tool_input_guardrail فی OpenAI Agents SDK قبل تنفیذ کل أداة دفع ویمکنہ رفض الاستدعاء. قابلتہ فی المفہوم 5: إنہ طریقة SDK الأصلیة لإیقاف الدفع قبل حدوثہ، والعائلة التی تعمل فی الوقت المناسب. ہنا یأخذ المعالجة الکاملة، لأن ہذہ کتلة guardrail القانونیة للدورة کلہا. الکود أدناہ حقیقی ویعمل.

import json
from decimal import Decimal
from agents import Agent, function_tool, RunContextWrapper
from agents.tool_guardrails import (
    tool_input_guardrail,
    tool_output_guardrail,
    ToolInputGuardrailData,
    ToolOutputGuardrailData,
    ToolGuardrailFunctionOutput,
)

# Tool INPUT guardrail: pre-payment check. Runs BEFORE the tool executes.
@tool_input_guardrail
def enforce_per_run_spend_cap(data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
    """Reject any payment tool call where the run's total spend would exceed the user's cap.
    Runs before the tool executes, the only guardrail family that can stop a payment in time."""
    args = json.loads(data.context.tool_arguments or "{}")          # raw JSON args string -> dict
    requested = Decimal(str(args.get("max_total_usd") or args.get("max_payment_usdc") or 0))
    ctx = data.context.context                                       # the run context (a dict)
    cap = Decimal(str(ctx["user_session"].per_run_spend_cap_usd))
    spent = Decimal(str(ctx.get("run_spend_usd", 0)))
    if spent + requested > cap:
        return ToolGuardrailFunctionOutput.reject_content(
            f"Refused: would spend ${spent + requested}, run cap is ${cap}"
        )
    return ToolGuardrailFunctionOutput.allow()

# Tool OUTPUT guardrail: post-payment check. Runs AFTER the tool executes.
# Useful for verifying receipts (paid more than expected, wrong amount, etc.).
@tool_output_guardrail
def verify_receipt_integrity(data: ToolOutputGuardrailData) -> ToolGuardrailFunctionOutput:
    output = data.output or {}
    if isinstance(output, dict) and "amount_paid_usdc" in output:
        # Cross-check the receipt against what we asked for.
        pass
    return ToolGuardrailFunctionOutput.allow()

# Attach BOTH guardrails to every payment-authorizing tool.
@function_tool(
    tool_input_guardrails=[enforce_per_run_spend_cap],
    tool_output_guardrails=[verify_receipt_integrity],
)
async def x402_fetch(
    ctx: RunContextWrapper,
    url: str,
    max_payment_usdc: Decimal,
) -> "X402PaymentResult":
    ...

# An agent-level output_guardrail is fine for final-reply safety
# (like redacting PII in the agent's answer), but it does NOT prevent payments.
agent = Agent(
    name="ShoppingAgent",
    tools=[x402_fetch],
    # output_guardrails=[response_safety_guardrail],  # different job, not payment safety
)

استخدم عائلة guardrail الصحیحة

لدی SDK ثلاث عائلات حواجز أمان. تعمل حواجز الإدخال علی أول رسالة من المستخدم إلی الوکیل. وتعمل حواجز الإخراج علی الرد النہائی للوکیل. وتعمل حواجز الأدوات (tool_input_guardrail وtool_output_guardrail) علی کل استدعاء أداة مخصصة. لسلامة الدفع ترید tool_input_guardrail تحدیدا: إنہ العائلة الوحیدة التی تعمل قبل أداة الدفع ویمکنہا حجبہا. اللجوء إلی output_guardrail للتحکم فی الإنفاق ہو الخطأ الأکثر شیوعا فی کود تجارة الوکلاء. عندما یعمل، یکون المال قد ذہب.

المستوی 3: حدود التطبیق ومنطق العمل. یفرض کودک قواعد المستخدم الخاصة: سقوف یومیة لکل مستخدم، وسقوف لکل فئة، وتجار مسموحون. ہنا تعیش قواعد العمل. "یمکن لہذا المستخدم إنفاق 500 دولار یومیا لدی أی تاجر، لکن 50 دولارا فقط یومیا لدی غیر الموثقین." ہذہ القاعدة تنتمی ہنا، لا إلی بروتوکول. ہذا کود Python عادی وحقیقی.

from decimal import Decimal

class UserSession:
    def can_spend(self, amount_usd: Decimal, merchant_id: str) -> bool:
        # Per-day cap
        if self.today_spend_usd + amount_usd > self.daily_cap_usd:
            return False
        # Per-merchant cap
        merchant_cap = self._merchant_cap_for(merchant_id)
        if self.merchant_spend_usd[merchant_id] + amount_usd > merchant_cap:
            return False
        # Per-category cap (for example, "office supplies" vs "personal")
        category = self._category_for(merchant_id)
        if self.category_spend_usd[category] + amount_usd > self.category_caps[category]:
            return False
        return True

یعیش کل مستوی فی بنیة مختلفة. المستوی 1 فی السلسلة أو Stripe. والمستوی 2 فی SDK الوکیل. والمستوی 3 فی کود تطبیقک. یلتقط خطأ فی واحد منہما المستویان الآخران. إذا تجاوزت المستوی 1، فقد یفرغ خطأ حلقة وکیل واحد المحفظة کلہا. وإذا تجاوزت المستوی 2، تفقد القدرة علی إجہاض تشغیل فی منتصف الطریق. وإذا تجاوزت المستوی 3، لا تستطیع فرض سیاسة کل مستخدم أو کل فئة.

الفخ ہو الثقة فی سقوف البروتوکولات وحدہا. سقف SPT فی ACP، وسقف جلسة MPP، والحد لکل طلب فی x402 کلہا حدود علی مستوی البروتوکول. توقف إساءة استخدام بروتوکول محددة، لکنہا لا تجمع عبر البروتوکولات. فریق یستخدم SPTs من ACP فقط بسقف 50 دولارا لکل واحد لا یملک حمایة من وکیل یصدر 100 منہا متتالیة، بإجمالی 5,000 دولار. توجد المستویات الثلاثة أعلاہ بالضبط لأن سقوف البروتوکولات لا تتراکم.

خلاصة المفہوم 15: افرض حدود الإنفاق علی ثلاثة مستویات مستقلة: بنیة المحفظة أو طریقة الدفع، وحواجز أدوات SDK (tool_input_guardrail تحدیدا، لأنہ یعمل قبل کل أداة ویمکنہ حجبہا)، ومنطق العمل فی التطبیق. یستخدم کل مستوی بنیة مختلفة، لذلک یلتقط الآخران خطأ أحدہا. الخطأ الأکثر شیوعا ہو استخدام output_guardrail علی مستوی الوکیل للتحکم فی الإنفاق. یعمل علی الرد النہائی، متأخرا جدا، بعد حدوث الدفع. حدود البروتوکول (SPT، جلسة MPP، حد x402 لکل طلب) ضروریة لکنہا غیر کافیة؛ فہی لا تتراکم عبر البروتوکولات ولا عبر التشغیلات. تفرض أنظمة الإنتاج المستویات الثلاثة کلہا.

المفہوم 16: نظافة ہویة الوکیل: المفاتیح والمحافظ وسجلات التدقیق

فی سطر واحد: مفتاح توقیع الوکیل ہو الشیء الوحید الفاصل بین الإنفاق المصرح والاحتیال، لذلک تحمی المفتاح، وتفصلہ لکل وکیل، وتدورہ، وتسجل کل إنفاق فی تخزین متین.

تجلب تجارة الوکلاء فشلا فریدا للأنظمة المستقلة: ہویة الوکیل التشفیریة ہی کل ما یفصل الإنفاق الحقیقی عن الاحتیال. إذا تسرب مفتاح التوقیع، یمکن استنزاف المحفظة (أو عمیل Stripe، أو موقّع تفویض AP2) أو انتحالہا حتی تدور المفتاح. نظافة الہویة ہی مجموعة العادات التی تمنع ذلک. ہناک أربع عادات.

1. فصل المحفظة لکل وکیل. یحصل کل وکیل، أو کل فئة وکلاء، علی محفظتہ أو مقبض دفعہ الخاص. لا تشارک مفاتیح التوقیع بین وکلاء لہم وظائف مختلفة. إذا شارک وکیل التسوق ووکیل المشتریات محفظة واحدة، فإن اختراق أیہما یستنزف الاثنین. تکلف المحافظ المنفصلة قلیلا جدا (کلفة نشر لمرة واحدة) والمکسب الأمنی حقیقی.

SmartContractWallet.deploy(...) توضیحی کما فی المفہوم 15. النمط ہو المہم: محفظة واحدة لکل فئة وکیل، لا مشارکة.

# Wrong: one wallet shared across agents
shared_wallet = SmartContractWallet.deploy(...)
shopping_agent.wallet = shared_wallet
procurement_agent.wallet = shared_wallet
research_agent.wallet = shared_wallet  # one compromise drains all three

# Right: a separate wallet per agent class
shopping_agent.wallet = SmartContractWallet.deploy(
    spend_limits={"max_per_day_usdc": 100},
)
procurement_agent.wallet = SmartContractWallet.deploy(
    spend_limits={"max_per_day_usdc": 1000, "allowed_recipients": [...]},
)
research_agent.wallet = SmartContractWallet.deploy(
    spend_limits={"max_per_day_usdc": 50, "max_per_call_usdc": 0.50},
)

2. تدویر المفاتیح، بجدول وعند الطلب. دوّر مفاتیح التوقیع کل 90 یوما کخط أساس (مطابقا لنصیحة Stripe لمفاتیح API). ودوّرہا فورا عندما یترک مشغل وکیل الفریق، أو عندما یمس نشر سطح التوقیع، أو عندما یبدو شیء غریبا. عادة التدویر أہم من عدد الأیام الدقیق.

النمط أدناہ حقیقی. اسم العمیل azure_key_vault توضیحی؛ استخدم SDK خزانة المفاتیح لدی مزودک. النقطة ہی أن المفتاح یعیش فی vault وتقرأ نسختہ الحالیة عند الاستخدام.

# Read the current key version from the vault. The version changes when the key rotates.
def get_signing_key(agent_class: str) -> SigningKey:
    return azure_key_vault.get_latest_version(
        secret_name=f"agent-wallet-signing-key-{agent_class}",
    )

# Old transactions, signed with the previous version, stay valid until they expire.
# New transactions use the current version.

3. سجلات تدقیق تصمد بعد crash. یسجل کل قرار تفویض إلی تخزین متین یعیش منفصلا عن وقت تشغیل الوکیل: کل SPT صدر، وکل تفویض وقع، وکل توقیع x402، وکل جلسة MPP فتحت. إذا تعطل الوکیل، یجب أن یبقی سجل التدقیق. تمنحک Neon Postgres مع memoization فی Inngest ذلک؛ ویمکنک أیضا الکتابة مباشرة إلی تخزین کائنات (S3 أو ما یعادلہ) لأقصی متانة.

نمط سجل التدقیق ہو الدرس. اسم العمیل neon_client توضیحی؛ استخدم عمیل قاعدة بیاناتک. القاعدة ہی تسجیل القرار قبل حدوث الدفع.

# Every payment-authorizing action logs to durable storage BEFORE the action completes.
@function_tool
async def acp_create_cart_and_checkout(
    ctx: RunContextWrapper,
    merchant_id: str,
    items: list["CartItem"],
    max_total_usd: Decimal,
) -> "CheckoutResult":
    audit_id = str(uuid4())

    # Log the authorization decision FIRST, before any payment happens.
    await neon_client.audit_log.insert({
        "audit_id": audit_id,
        "agent_class": ctx.context["agent_class"],
        "user_did": ctx.context["user_session"].did,
        "action": "acp_create_cart_and_checkout",
        "merchant_id": merchant_id,
        "max_total_usd": max_total_usd,
        "timestamp": datetime.utcnow().isoformat(),
        "status": "initiated",
    })

    try:
        result = await _actually_complete_checkout(merchant_id, items, max_total_usd)
        await neon_client.audit_log.update(audit_id, {
            "status": "completed",
            "actual_total_usd": result.total_charged_usd,
            "order_id": result.order_id,
        })
        return result
    except Exception as e:
        await neon_client.audit_log.update(audit_id, {"status": "failed", "error": str(e)})
        raise

4. تتبعات موزعة عبر المعاملة کلہا. یخبرک سجل التدقیق ما نجح. وتخبرک traces بما حدث، بما فی ذلک الاستدعاءات التی فشلت أو أعیدت أو توقفت. فی تجارة الوکلاء، یکون trace الکامل غالبا الطریقة الوحیدة لتنقیح معاملة فاشلة، لأن طلب مستخدم واحد یمکن أن یتفرع إلی تشغیل SDK، و5 إلی 10 استدعاءات أداة، و2 أو 3 طلبات HTTP بروتوکول، وwebhook من Stripe یصل لاحقا، ودالة Inngest تستأنف بعد ساعات. ومن دون trace ID واحد یربط ذلک کلہ، تصبح post-mortem مستحیلة. کود OpenTelemetry أدناہ ہو API OTel الحقیقی والمستقر.

from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode

tracer = trace.get_tracer("agent-commerce")

@function_tool
async def acp_create_cart_and_checkout(
    ctx: RunContextWrapper,
    merchant_id: str,
    items: list["CartItem"],
    max_total_usd: Decimal,
) -> "CheckoutResult":
    # The span name is the protocol action; attributes capture what you filter by
    # in your observability tool (Datadog, Honeycomb, Grafana, and so on).
    with tracer.start_as_current_span(
        "acp.checkout",
        attributes={
            "agent.class": ctx.context["agent_class"],
            "user.did": ctx.context["user_session"].did,
            "acp.merchant_id": merchant_id,
            "acp.max_total_usd": float(max_total_usd),
            "acp.item_count": len(items),
        },
    ) as span:
        try:
            result = await _actually_complete_checkout(merchant_id, items, max_total_usd)
            span.set_attribute("acp.order_id", result.order_id)
            span.set_attribute("acp.actual_total_usd", float(result.total_charged_usd))
            span.set_status(Status(StatusCode.OK))
            return result
        except Exception as e:
            span.set_status(Status(StatusCode.ERROR, str(e)))
            span.record_exception(e)
            raise

یتدفق سیاق trace تلقائیا عبر httpx وopenai-agents وInngest عند وجود instrumentation الصحیح. عندما یصل webhook من Stripe بعد 20 دقیقة لنزاع علی ہذا الطلب، ینضم handler ال webhook إلی trace نفسہ عبر trace_id المحمول فی metadata الطلب. یغطی trace ID واحد عمر المعاملة کلہ، من أول طلب إلی حل النزاع.

تجیب سجلات التدقیق وtraces عن أسئلة مختلفة، وتحتاج إلی الاثنین. تجیب سجلات التدقیق عن أسئلة العمل ("کم أنفق ہذا المستخدم یوم الثلاثاء؟"). وتجیب traces عن أسئلة التنقیح ("لماذا فشل checkout للطلب abc123؟"). یسجل سجل التدقیق المسار الناجح فقط؛ ولا یلتقط أبدا الاستدعاء الذی أعید خمس مرات قبل أن یعمل، أو استدعاء البروتوکول الذی توقف 30 ثانیة قبل timeout. لا تظہر أشکال الفشل تلک إلا فی traces. تجاوز traces لأن لدیک سجلات تدقیق خطأ فی فہم وظیفة کل أداة.

أکثر خطأ شائع فی الہویة ہو معاملة عنوان المحفظة کہویة الوکیل. العنوان عام: یستطیع أی أحد الإرسال إلیہ وأی أحد التحقق من أن معاملة صدرت منہ. مفتاح التوقیع الخاص ہو الہویة، وتحمیہ علی ہذا الأساس. الفرق التی تحفظ مفاتیح التوقیع فی متغیرات البیئة (أو أسوأ، فی الکود المصدری) سلمت ہویة الوکیل لکل من یستطیع الوصول إلی تلک الأسرار. تذہب المفاتیح إلی vault، لا إلی env vars.

خلاصة المفہوم 16: ہویة الوکیل تشفیریة؛ مفتاح التوقیع ہو الشیء الوحید الفاصل بین الإنفاق المصرح والاحتیال. تحمیہا أربع عادات. فصل المحفظة لکل وکیل، حتی لا یستنزف اختراق واحد کل الوکلاء. تدویر المفاتیح بجدول وعند الطلب (خط أساس 90 یوما، وفوری عند trigger). سجلات تدقیق إلی تخزین متین یعیش بعیدا عن runtime (Neon Postgres أو تخزین کائنات). traces موزعة ب trace ID واحد یغطی المعاملة کلہا (OpenTelemetry عبر SDK وhttpx وInngest وFastAPI). تذہب مفاتیح التوقیع إلی key vault، لا إلی متغیرات البیئة ولا إلی الکود المصدری. تجیب سجلات التدقیق عن أسئلة العمل؛ وتجیب traces عن أسئلة التنقیح؛ وتحتاج الاثنین.

المفہوم 17: آلیات النزاع والاسترداد عبر البروتوکولات الأربعة

فی سطر واحد: یتعامل کل بروتوکول مع النزاعات والاستردادات بشکل مختلف، وغالبا یکون نموذج النزاع الذی تحتاجہ حالة الاستخدام أقوی ما یحدد البروتوکولات التی ترکبہا.

یعامل کل واحد من البروتوکولات الأربعة النزاعات والاستردادات بطریقتہ، وغالبا یحسم ہذا الاختلاف اختیار البروتوکول لحالة استخدام. حالة استخدام تحتاج إلی حمایة chargeback لا یمکن أن تعمل علی x402 خالص. وحالة یکون فیہا البائع بلا إعداد خدمة عملاء لا یمکن أن تستخدم ACP. ہذہ طریقة کل بروتوکول فی التعامل مع النزاع، حتی تطابق البروتوکول مع نموذج النزاع الذی تحتاجہ فعلا.

بروتوکول ACP: النزاعات عبر شبکة البطاقات. بما أن التاجر یبقی merchant of record فی ACP، فإن کل مسار نزاع قیاسی فی شبکات البطاقات یعمل. یبدأ بنک المشتری chargeback؛ وتتولی Stripe (أو أی معالج) دفاع التاجر؛ ویتبع التاجر سیاسة الاسترداد القائمة. ہذہ أکبر میزة عملیة ل ACP. کل توقعات مشتری التجزئة حول الإرجاع تعمل ببساطة.

لاسترداد ACP یبدأہ الوکیل:

acp_client.refunds.create(...) توضیحی، مثل استدعاءات عمیل ACP الأخری فی ہذہ الدورة. نموذج النتیجة وربط الأداة حقیقیان.

@function_tool
async def acp_refund(
    order_id: str,
    reason: str,
    amount_usd: Decimal | None = None,
) -> "RefundResult":
    """Start a refund through ACP. The merchant's standard refund policy applies."""
    raw = await acp_client.refunds.create(
        order_id=order_id,
        reason=reason,
        amount_usd=amount_usd,  # None means full refund
    )
    return RefundResult(
        refund_id=raw.refund_id,
        order_id=order_id,
        status=raw.status,
        amount_refunded_usd=raw.amount_refunded_usd,
    )

بروتوکول AP2: تسوی النزاعات عبر مسار التدقیق. مساہمة AP2 فی النزاع ہی سلسلة التفویضات (Intent ثم Cart ثم Payment). عندما یظہر نزاع، تکون تلک السلسلة دلیلا علی ما فوّضہ المستخدم فعلا، وتملک قوة قانونیة. لا تستبدل مسار النزاع فی السکة الأساسیة: إذا فوّض AP2 دفعة بطاقة عبر Stripe، فإن عملیة نزاع Stripe تبقی مطبقة. یضیف AP2 إثبات ما وافق علیہ المستخدم.

تدفق النزاع:

1. User claims: "I never authorized this purchase."
2. Merchant retrieves the signed AP2 Cart Mandate from the transaction record.
3. Merchant presents the Cart Mandate (with the user's signature) to the
   payment processor as part of the dispute defense.
4. The card network or processor checks the signature against the user's
   registered public key. If it is valid, the dispute is resolved for the merchant.

بروتوکول x402: لا آلیة نزاع رسمیة. مدفوعات x402 الخالصة غیر قابلة للاسترداد بالتصمیم. تستقر الدفعة علی السلسلة خلال ثانیة إلی ثانیتین؛ ولا chargeback. ہذا أکبر حد عملی ل x402. یناسب استدعاء API بقیمة 0.001 دولار (النزاع یکلف أکثر من الدفعة) وخاطئ لأی شیء قد یرید فیہ المشتری استردادا عادلا.

ثلاث طرق لتلیین خاصیة x402 غیر القابلة للاسترداد:

• ضمان Escrow. للمدفوعات الأعلی قیمة فی x402، استخدم smart-contract escrow یحفظ الأموال حتی یرسل المشتری إشارة القبول. یتضمن ERC-8004 بدائیات escrow للمعاملات متعددة الوکلاء.
• الترکیب مع AP2 وسکة مختلفة. إذا احتجت إلی سرعة x402 ومعہا دعم نزاعات، فإن ترکیب AP2 مع x402 یعطیک سلسلة التفویضات کدلیل ویبقی x402 التسویة سریعة. تبقی التسویة نفسہا غیر قابلة للعکس؛ یثبت التفویض فقط ما اتفق علیہ.
• ضمانات البائع. فی APIs المدفوعة، تتضمن شروط البائع غالبا قواعد استرداد تنفذ خارج السلسلة (یرسل البائع USDC طوعا إذا فشلت الخدمة). یعمل ذلک مع بائعین ذوی سمعة، وینہار مع مجہولین.

بروتوکول MPP: النزاعات عبر Stripe. ترث جلسات MPP المسواة علی سکک البطاقات آلیات النزاع القیاسیة فی Stripe، کما فی ACP. أما جلسات MPP المسواة بعملة مستقرة علی Tempo أو عبر Lightning فتسیر عبر تسویة النزاعات من جہة البائع لدی Stripe. تحمل Stripe التاجر مسؤولیة النتیجة بغض النظر عن السکة.

غالبا یقود نموذج النزاع الذی تحتاجہ الترکیب أکثر من الکلفة أو الکمون. منصة تسوق مستہلک تحتاج chargebacks، لذلک یناسب ACP. سوق API خالص بین الآلات لا یحتاج نزاعات إطلاقا، لذلک یناسب x402. منصة مشتریات مؤسسة تحتاج دلیلا بدرجة تدقیق، لذلک یناسب AP2 مع أی سکة تسویة.

خلاصة المفہوم 17: تختلف آلیات النزاع والاسترداد بقوة عبر البروتوکولات. یرث ACP chargebacks من شبکات البطاقات، لذلک تعمل سیاسة الإرجاع القائمة لدی التاجر. ویقدم AP2 سلسلة التفویضات کدلیل قانونی لکنہ لا یستبدل مسار النزاع فی السکة الأساسیة. وx402 غیر قابل للاسترداد بالتصمیم: مناسب للمدفوعات الصغیرة، وخاطئ حیث تہم الاستردادات. ویرث MPP آلیات نزاع Stripe عبر السکک. نموذج النزاع الذی تحتاجہ حالة الاستخدام غالبا ہو أقوی ما یفرض ترکیب البروتوکولات.

المفہوم 18: سباکة FastAPI وInngest webhook لإغلاق حلقة الطلب والاستجابة

فی سطر واحد: تصل بعض أحداث الدفع وفق جدولہا الخاص (نزاعات، توقیعات تفویض، طلبات دفع من جہة البائع)، لذلک تحتاج إلی handler رقیق فی FastAPI یلتقطہا وحدث Inngest یحمل العمل إلی workflow متین.

تعاملت الأجزاء 1 إلی 5، والمفاہیم 15 إلی 17، مع الوکیل کمشتر: یرسل طلبا، یرد البروتوکول، ویفکر SDK فی النتیجة. لکن تجارة الوکلاء تعمل فی الاتجاہین. ترسل Stripe webhooks من نوع charge.dispute.created. ویحدث توقیع تفویض AP2 خارج خادمک، علی جہاز المستخدم، ویرجع لاحقا. ویحتاج بائعو x402 إلی middleware من جہة الخادم یعید 402 Payment Required ویفحص ترویسات X-PAYMENT. لا یناسب أی من ذلک استدعاء Runner.run() واحدا. تحتاج ہذہ الأحداث إلی handlers فی FastAPI کحد HTTP، وأحداث Inngest کجسر راجع إلی workflows متینة.

یمشی ہذا المفہوم عبر الأنماط الثلاثة التی ستحتاجہا فی الإنتاج. من دونہا، ستکون فی النظام شقوق تسقط منہا الأحداث غیر المتزامنة.

النمط 1: webhook من Stripe یتدفق إلی دالة Inngest معلقة. عندما یرفع مستخدم chargeback علی طلب ACP، ترسل Stripe charge.dispute.created إلی نقطة نہایتک. قد یصل بعد خمس دقائق من الطلب أو بعد 60 یوما. workflow الذی وضع الطلب انتہی منذ زمن، لکن الوکیل ما زال یحتاج إلی الرد: إخطار التاجر، التسجیل فی التدقیق، وربما بناء دفاع. یحول handler FastAPI ال webhook إلی حدث Inngest، وتلتقطہ دالة Inngest وتشغل وکیلا للتعامل مع النزاع.

stripe.Webhook.construct_event(...) وstripe.error.SignatureVerificationError واجہات Stripe API حقیقیة. ربط Inngest حقیقی. لاحظ API الإرسال: تخرج الأحداث ک send(events=[inngest.Event(...)])، لا dict عار.

from fastapi import FastAPI, Request, HTTPException
from pydantic import BaseModel
from decimal import Decimal
import stripe, inngest

app = FastAPI()
inngest_client = inngest.Inngest(app_id="agent-commerce", is_production=False)

class StripeDisputeEventPayload(BaseModel):
    order_id: str
    dispute_id: str
    amount_usd: Decimal
    reason: str
    raw_event_id: str

@app.post("/webhooks/stripe")
async def stripe_webhook(request: Request):
    # 1. Verify the Stripe signature. This security gate is required.
    signature = request.headers.get("Stripe-Signature")
    payload = await request.body()
    try:
        event = stripe.Webhook.construct_event(
            payload=payload, sig_header=signature, secret=settings.stripe_webhook_secret,
        )
    except stripe.error.SignatureVerificationError:
        raise HTTPException(status_code=400, detail="Invalid signature")

    # 2. Route by event type. This handler does NO business logic.
    #    It only fires Inngest events so the durable workflow does the work.
    if event.type == "charge.dispute.created":
        await inngest_client.send(events=[
            inngest.Event(
                name="stripe/dispute.created",
                data=StripeDisputeEventPayload(
                    order_id=event.data.object.metadata.get("order_id"),
                    dispute_id=event.data.object.id,
                    amount_usd=Decimal(event.data.object.amount) / 100,
                    reason=event.data.object.reason,
                    raw_event_id=event.id,
                ).model_dump(),
                id=event.id,            # idempotency seed
            ),
        ])

    # 3. ACK Stripe right away. The real work runs in Inngest, durably.
    return {"received": True, "event_id": event.id}

# The Inngest function that handles the dispute: fully durable and retryable.
@inngest_client.create_function(
    fn_id="handle-stripe-dispute",
    trigger=inngest.TriggerEvent(event="stripe/dispute.created"),
    # Idempotency by raw_event_id makes sure Stripe retries do not process twice.
    idempotency="event.data.raw_event_id",
)
async def handle_stripe_dispute(ctx: inngest.Context) -> dict:
    payload = StripeDisputeEventPayload(**ctx.event.data)

    # Log to audit immediately.
    await ctx.step.run("audit-dispute-received", log_dispute_to_neon, payload)

    # Run an agent to assemble the dispute defense.
    defense_agent = Agent(
        name="DisputeDefenseAgent",
        instructions="Assemble dispute defense materials: order receipt, AP2 mandate if any, "
                     "delivery confirmation, customer communication history.",
        tools=[fetch_order_details, fetch_mandate_chain, fetch_delivery_proof, submit_dispute_response],
    )
    defense = await ctx.step.run(
        "build-and-submit-defense",
        Runner.run, defense_agent, f"Build defense for dispute {payload.dispute_id}",
    )
    return {"status": "completed", "output": {"defense_submitted": defense.final_output.model_dump()}}

یبقی handler FastAPI رقیقا (تحقق، ثم أطلق حدثا). وتکون دالة Inngest متینة (idempotency، وretries، وstep memoization). یحدث استدلال الوکیل داخل دالة Inngest، لا داخل handler ال webhook. یہم ہذا الفصل لأن Stripe تتوقع استجابة 2xx خلال نحو خمس ثوان، وقد یستغرق تشغیل وکیل 30 ثانیة أو أکثر.

النمط 2: callback لتوقیع AP2 یستأنف step.wait_for_event معلقا. أظہر المفہوم 9 أداة توقیع AP2 تطلب توقیعا وتنتظر. فی الإنتاج یحدث ذلک التوقیع خارج خادمک: یفتح المستخدم تطبیق الہاتف، یری التفویض، یضغط Approve، ویرسل التفویض الموقّع عائدا. کان workflow فی Inngest معلقا علی step.wait_for_event؛ یطلق callback فی FastAPI الحدث الذی یوقظہ.

إن callback التوقیع route خاص بک فی FastAPI. یستخدم ارتباط Inngest if_exp= (تعبیر CEL)، والحمولة المنتظرة تحت بادئة async.. یرجع wait_for_event قیمة None عند timeout. أما ap2_verify_signature وعمیل التخزین فہما توضیحیان؛ شکل workflow حقیقی.

from datetime import timedelta
from pydantic import BaseModel

class MandateSignedPayload(BaseModel):
    mandate_id: str
    user_did: str
    signature: str  # the user's signature over the mandate hash
    signed_at: str

@app.post("/callbacks/ap2/mandate-signed")
async def mandate_signed_callback(payload: MandateSignedPayload, request: Request):
    # 1. Verify the signature against this user's registered public key.
    is_valid = await ap2_verify_signature(
        mandate_id=payload.mandate_id,
        user_did=payload.user_did,
        signature=payload.signature,
    )
    if not is_valid:
        raise HTTPException(status_code=400, detail="Invalid mandate signature")

    # 2. Persist the signed mandate. Mandates have a 7-year retention requirement.
    await neon_client.mandates.insert({
        "mandate_id": payload.mandate_id,
        "user_did": payload.user_did,
        "signature": payload.signature,
        "signed_at": payload.signed_at,
        "status": "signed",
    })

    # 3. Fire the Inngest event that resumes the agent's workflow.
    await inngest_client.send(events=[
        inngest.Event(name="ap2/mandate.signed", data=payload.model_dump(), id=payload.mandate_id),
    ])
    return {"received": True, "event_id": payload.mandate_id}

# The Inngest function that was waiting. if_exp correlates the wait to this mandate.
@inngest_client.create_function(
    fn_id="agent-procurement-workflow",
    trigger=inngest.TriggerEvent(event="procurement/task.created"),
)
async def procurement_workflow(ctx: inngest.Context) -> dict:
    # ... agent creates the Intent Mandate, fires "ap2/mandate.signing.requested" ...

    # Suspend until the user signs. Zero compute is used during the wait.
    signed = await ctx.step.wait_for_event(
        "wait-for-intent-mandate-signature",
        event="ap2/mandate.signed",
        if_exp=f"async.data.mandate_id == '{ctx.event.data['mandate_id']}'",
        timeout=timedelta(hours=24),   # users can take real time
    )

    if signed is None:                 # timeout returns None
        return {"status": "abandoned", "reason": "user did not sign within 24h"}

    # Resume with the signed mandate. The agent continues from exactly where it left off.
    cont = await ctx.step.run("continue-procurement", continue_with_signed_mandate, signed)
    return {"status": "completed", "output": {"procurement_continuation": cont}}

بنی step.wait_for_event فی Inngest مع if_exp لہذا بالضبط. handler FastAPI جسر باتجاہ واحد من HTTP إلی bus أحداث Inngest. یستأنف workflow الذی علق قبل ساعات مع الحمولة الموقعة، ویواصل الوکیل من حیث توقف.

النمط 3: middleware من جہة بائع x402 (عندما تعرض API مدفوعة، لا تستہلک واحدة فقط). فی سوق متعدد الوکلاء (القرار 4)، یکون وکیلک أحیانا مشتریا وأحیانا بائعا، حیث تدفع لہ وکلاء أخری مقابل البحث أو التحلیل أو الکود. تحتاج جہة البائع إلی middleware فی FastAPI یعید 402 Payment Required، ویفحص ترویسات X-PAYMENT، ولا یقدم المورد إلا بعد أن یتحقق facilitator من الدفع.

X402Middleware من جہة البائع أدناہ توضیحی؛ لا توجد حزمة PyPI اسمہا x402_server. یأتی x402 الحقیقی من جہة الخادم عبر حزمة x402 ومساعدات الخادم وال facilitator مع تکامل framework. فکرة التماثل بین المشتری والبائع حقیقیة، وroute FastAPI حقیقی.

from fastapi import FastAPI, Request, Response
from decimal import Decimal
# Illustrative seller-side imports (see note above).
from x402_server import X402Middleware, PaymentRequirement

# Configure the middleware once at app startup.
app = FastAPI()
app.add_middleware(
    X402Middleware,
    payment_requirements_by_route={
        "/api/research": PaymentRequirement(
            scheme="exact",
            network="eip155:8453",  # Base
            asset=USDC_BASE_CONTRACT,
            recipient=settings.merchant_wallet_address,
            max_amount_usdc=Decimal("0.50"),
            expiry_seconds=300,
        ),
        "/api/code-review": PaymentRequirement(
            scheme="exact",
            network="eip155:8453",
            asset=USDC_BASE_CONTRACT,
            recipient=settings.merchant_wallet_address,
            max_amount_usdc=Decimal("2.00"),
            expiry_seconds=300,
        ),
    },
    facilitator_url="https://facilitator.cloudflare.com/x402",
)

# Your business logic. The middleware enforces payment before this runs.
@app.post("/api/research")
async def research_endpoint(request: Request):
    # By the time we reach here, the X-PAYMENT header has been verified and settled.
    # request.state.x402_proof carries the on-chain transaction hash for audit.
    query = (await request.json())["query"]

    research_agent = Agent(
        name="ResearchAgent",
        instructions="Conduct deep research on the query and return a structured report.",
        tools=[search_web, fetch_papers, summarize],
    )
    result = await Runner.run(research_agent, query)

    return Response(
        content=result.final_output,
        headers={"X-PAYMENT-PROOF": request.state.x402_proof.tx_hash},
    )

إن x402 متناظر. کود جہة المشتری من المفہوم 10 وmiddleware جہة البائع ہنا ہما نصفا البروتوکول نفسہ. یشغل السوق متعدد الوکلاء الاثنین: تشتری وکلاؤہ من خدمات خارجیة وتبیع لوکلاء خارجیة.

تتکرر ثلاثة إخفاقات فی الإنتاج:

1. تنفیذ handlers ال webhook لمنطق العمل inline. handler فی FastAPI یشغل الوکیل داخل استجابة webhook سیتجاوز timeout ذی الخمس ثوان لدی Stripe. تعید Stripe المحاولة، فیعمل الوکیل مرتین، وتخصم من المستخدم مرتین. یبقی handler رقیقا؛ وتکون دالة Inngest متینة.
2. نسیان idempotency فی webhooks. تعید Stripe تسلیمات فاشلة بالمعرف نفسہ event.id. من دون مفتاح idempotency علی دالة Inngest، تنشئ کل إعادة محاولة نسخة مکررة. استخدم "event.data.raw_event_id" کمفتاح idempotency.
3. لا فحص توقیع علی callbacks. یجب أن تتحقق callbacks الخاصة ب AP2 mandate-signed من توقیع المستخدم مقابل المفتاح العام المسجل. وإلا یستطیع أی caller تزویر أحداث mandate-signed. الفحص الفاشل یرجع 400، لا تحذیرا مسجلا.

خلاصة المفہوم 18: تجارة الوکلاء ثنائیة الاتجاہ. تصل استجابات البروتوکولات متزامنة ویتعامل معہا SDK، لکن النزاعات وتوقیعات التفویضات والاستردادات وطلبات الدفع من جہة البائع تصل لا متزامنة عبر webhooks وcallbacks. تغطی ثلاثة أنماط الحاجة التشغیلیة. یطلق handler webhook من Stripe حدث Inngest إلی workflow وکیل متین للنزاعات والاستردادات. ویطلق callback لتوقیع AP2 حدث Inngest یستأنف step.wait_for_event معلقا للتوقیع خارج المسار. ویعرض middleware من جہة بائع x402 واجہات API مدفوعة بدفع متحقق. تبقی handlers FastAPI رقیقة (تحقق وأطلق)، وتکون دوال Inngest متینة (idempotent ومعادة المحاولة). framing جہة المشتری فی الأجزاء 1 إلی 5 غیر مکتمل من دون ہذہ الثلاثة؛ تشغل أنظمة الإنتاج الثلاثة کلہا.

---

الجزء 7: الخاتمة، ما کانت الدورة تعلمہ فعلا

المفہوم 19: انضباط الترکیب الطبقی

فی سطر واحد: یتلخص کل شیء فی ہذہ الدورة فی مہمة واحدة: اقرأ حالة الاستخدام، قسمہا إلی أربع طبقات، واختر البروتوکول الصحیح فی کل طبقة.

تحتوی ہذہ الدورة علی 19 مفہوما و5 قرارات. کلہا scaffolding لادعاء واحد: تجارة الوکلاء فی 2026 لیست بروتوکولا واحدا بل معماریة طبقیة، ومہمتک أن تختار البروتوکول الصحیح فی کل طبقة لحالة الاستخدام أمامک. یتبع کل شیء آخر ذلک.

یظہر الشکل نفسہ علی ثلاثة مقاییس.

علی مقیاس البروتوکول، تحل البروتوکولات الأربعة الرئیسیة مشکلات مختلفة فی طبقات مختلفة: ACP فی الطبقة 3، وAP2 فی الطبقة 2، وx402 وMPP فی الطبقة 4. معاملتہا کمتنافسین فی الطبقة نفسہا ہو الخطأ المعماری الأکثر شیوعا. لا تتنافس إلا حیث تتداخل طبقاتہا (x402 ضد MPP فی التسویة؛ وAP2 ضد SPT فی ACP للتفویض فی بعض التدفقات). وفی کل مکان آخر تترکب.

علی مقیاس النظام، یملک نظام الإنتاج بروتوکولا واحدا من کل طبقة، موصولا عبر OpenAI Agents SDK بوصفہ العمیل الموحد. تتطابق @function_tool وRunContextWrapper وtool_input_guardrail فی SDK بنظافة مع قضایا کل طبقة. SDK لیس بروتوکولا. إنہ المنسق الذی یسمح لک بترکیب البروتوکولات بنظافة.

علی مقیاس الانضباط، عملک ہو قراءة حالة استخدام، وتقسیمہا إلی الطبقات الأربع، واختیار البروتوکول الصحیح فی کل واحدة، وتبریر کل اختیار مقابل القیود الحقیقیة للحالة: قیمة المعاملة، ومیزانیة الکمون، ونموذج النزاع، ومتطلبات التدقیق. العمل لیس "اختر بروتوکولا مفضلا." بل "فی حالة الاستخدام ہذہ، ماذا تطلب کل طبقة؟"

مشت القرارات الخمسة فی الجزء 5 عبر حالات استخدام حقیقیة بہذا الانضباط. وصل القرار 1 (تسوق المستہلک) إلی ACP مع سکک بطاقات Stripe لأن حالة الاستخدام احتاجت حمایة chargeback. ووصل القرار 2 (وکیل یدفع ل API) إلی x402 وحدہ، لأن الطبقتین 2 و4 تنطبقان فی تدفقات الآلة إلی الآلة. ووصل القرار 3 (مشتریات المؤسسة) إلی أعقد ترکیب (AP2 مع ACP مع MPP)، لأن حاجتی التدقیق والتکرار فرضتا ذلک. ووصل القرار 4 (سوق متعدد الوکلاء) إلی AP2 مع ERC-8004 ومع x402، لأن حاجة الثقة الثنائیة لا یمکن تلبیتہا بطریقة أخری. وأعاد القرار 5 بناء القرار 2 علی مکدس مختلف تماما (Google ADK مع محفظة Coinbase مع AP2 مع x402)، ووصل إلی الشکل ذی الطبقات الأربع نفسہ، مثبتا أن المعماریة لیست غلافا حول Stripe وOpenAI.

الترکیب الذی تختارہ تحددہ حالة الاستخدام، لا الذوق. فریق یختار x402 لأن "العملات المستقرة ہی المستقبل" لکنہ یبنی تجربة تسوق للمستہلک یملک الترکیب الخطأ. وفریق یختار ACP لأن "Stripe enterprise-grade" لکنہ یدفع لوصول API بسعر 0.001 دولار لکل استدعاء یملک الترکیب الخطأ. دع حالة الاستخدام تقود الاختیار.

خلاصة المفہوم 19، وخلاصة ہذہ الدورة: البروتوکولات الأربعة (ACP وAP2 وx402 وMPP) طبقات، لا بدائل. عملک أن تقرأ حالة الاستخدام، وتقسمہا إلی الطبقات الأربع (الاکتشاف، والتفویض، والتجارة، والتسویة)، وتختار البروتوکول الصحیح فی کل طبقة، وتبرر الاختیار مقابل قیود حالة الاستخدام الحقیقیة. OpenAI Agents SDK ہو العمیل الموحد الذی یرکب البروتوکولات المختارة. یبقی ہذا الانضباط صالحا أیا کانت البروتوکولات التی تفوز خلال ال 24 شہرا القادمة. الطبقات مستقرة، حتی لو تطورت البروتوکولات داخل کل طبقة.

---

ورقة مختصرة: الإطار فی صفحة واحدة

اطبعہا. علّقہا علی الحائط. استخدمہا عند مراجعة أی تصمیم لتجارة الوکلاء.

الطبقات الأربع (احفظ ہذا المکدس)

Layer 1: DISCOVERY      ->  "What's available to buy?"
Layer 2: AUTHORIZATION  ->  "Am I allowed to spend this?"
Layer 3: COMMERCE       ->  "What's the full purchase lifecycle?"
Layer 4: SETTLEMENT     ->  "Where does the money actually move?"

البروتوکولات فی کل طبقة (أفضل الاختیارات فی 2026)

الطبقة	أفضل الاختیارات	اختر بناء علی
الاکتشاف	MCP، وA2A، وأدلة الوکلاء، وواجہات التسوق بالذکاء الاصطناعی	أین تعیش الخدمات التی یحتاجہا الوکیل
التفویض	تفویضات AP2، وACP SPT، وTAP، وERC-8004	نموذج الثقة: تدقیق صارم، أصلی ل Stripe، ہویة فقط، أو متعدد الوکلاء
التجارة	ACP، وUCP، وAPI مباشر (لا شیء)	ہل تحتاج حالة الاستخدام إلی دورة حیاة تجارة؟
التسویة	x402، وMPP، وسکک البطاقات، والبنک/Lightning	الاقتصادیات: قیمة المعاملة تقود السکة

الترکیبات القانونیة الأربعة

حالة الاستخدام	المکدس
تسوق المستہلک	واجہة AI + ACP SPT + ACP + بطاقات Stripe
وکیل یدفع ل API	MCP/دلیل + EIP-3009 + (لا شیء) + x402
مشتریات مؤسسة	A2A/MCP + AP2 + ACP/UCP + MPP/cards
سوق متعدد الوکلاء	A2A + AP2 + ERC-8004 + (لا شیء) + x402

فرض حدود الإنفاق علی ثلاثة مستویات (مطلوب)

Level 1: Wallet / payment-method limits  (smart-contract caps OR Stripe customer caps)
Level 2: SDK tool guardrails             (tool_input_guardrail on each payment tool)
Level 3: Application business logic      (per-user, per-category, per-merchant policies)

إذا تجاوزت أیا من ہذہ، فأنت علی بعد bug واحد من استنزاف کامل. الخطأ الأکثر شیوعا ہو استخدام output_guardrail علی مستوی الوکیل للمستوی 2. یعمل علی الرد النہائی للوکیل، متأخرا جدا لإیقاف الدفع. استخدم tool_input_guardrail بدلا منہ.

العتبة الاقتصادیة (احفظہا)

Transaction value
├── < $5         → x402 or MPP stablecoin (card fees exceed the transaction)
├── $5 - $1,000  → ACP + card rails (chargeback protection worth the 2.9%)
└── > $1,000     → AP2 + composed stack (audit + dispute defense + multi-rail)

نموذج النزاع (غالبا أقوی قید)

Use case needs chargeback protection?
├── Yes → ACP + card rails (or MPP card mode)
└── No  → x402 acceptable (faster, cheaper, no refunds)

Use case needs audit evidence?
├── Yes → AP2 at Layer 2 (mandates as legally-admissible evidence)
└── No  → SPT or EIP-3009 sufficient

قائمة تحقق الإنتاج قبل الإطلاق

• إعداد حدود إنفاق المحفظة/طریقة الدفع فی المستوی 1
• ربط tool_input_guardrail بکل أداة تفوض دفعا (المستوی 2)
• یفرض التطبیق سقوفا لکل مستخدم، ولکل فئة، ولکل تاجر (المستوی 3)
• مفاتیح التوقیع فی key vault (Azure Key Vault أو ما یعادلہ)، لا فی env vars
• فصل المحفظة لکل وکیل (لا مفاتیح مشترکة عبر فئات الوکلاء)
• تعریف جدول تدویر المفاتیح (خط أساس 90 یوما)
• سجلات التدقیق إلی تخزین متین مستقل عن runtime الوکیل
• تمتد traces من OpenTelemetry عبر SDK وhttpx وInngest وFastAPI؛ trace ID واحد لکل معاملة
• نماذج Pydantic عند کل حد (إرجاع الأدوات، وحمولات البروتوکولات، وأجسام FastAPI، وأحداث Inngest)
• Decimal للمال فی کل مکان (لا float أبدا)
• یتحقق handler webhook من Stripe من التوقیع ویطلق حدث Inngest (handler رقیق، دالة متینة)
• یتحقق callback تفویض AP2 الموقّع من التوقیع ویستأنف step.wait_for_event
• إذا کنت تعرض APIs مدفوعة: اضبط x402 seller-side middleware لکل route
• مفتاح idempotency فی کل دالة Inngest یحرکہا webhook
• فہم وتوثیق آلیة النزاع والاسترداد لکل بروتوکول
• بوابة تأکید human-in-the-loop لأول 30 یوما فی الإنتاج
• قیاس دقة السلة قبل تخفیف بوابة التأکید

---

مرجع سریع: شجرة القرار مضغوطة

عندما تکون لدیک حالة استخدام جدیدة، امش ہذہ الشجرة.

1. What's the agent buying?
   ├── Retail goods for a user → Decision 1 pattern (ACP + cards)
   ├── API access for itself → Decision 2 pattern (x402-only)
   ├── Supplier goods/services for an org → Decision 3 pattern (AP2 + composed)
   └── Work from another agent → Decision 4 pattern (AP2 + ERC-8004 + x402)

2. What's the transaction value?
   ├── < $5 → settlement = x402 or MPP stablecoin
   ├── $5-$1,000 → settlement = card rails via ACP/MPP
   └── > $1,000 → settlement = MPP sessions OR bank rails

3. What's the dispute model?
   ├── Need chargeback protection → must include card rails somewhere
   ├── Need audit evidence → must include AP2 at Layer 2
   └── Neither → x402 / direct rail sufficient

4. What's the latency budget?
   ├── < 1 sec → only stablecoin rails work
   ├── 1-5 sec → x402, MPP, or pre-signed AP2 mandates
   └── > 5 sec → full ACP checkout works

5. Compose: pick one protocol from each layer, justified against the constraints above.

---

مراجعة فی 10 دقائق: المفاہیم ال 19 فی جملة واحدة لکل مفہوم

اقرأ ہذا عندما تنسی ما قالہ کل مفہوم. کل مدخل ہو الخلاصة التی أغلقت المفہوم؛ جمعت ہنا للرجوع السریع.

1. الافتراض الذی انکسر

بنیت أنظمة الدفع علی افتراض أن إنسانا یضغط زر الشراء. یکسر الوکلاء ذلک بثلاث طرق: لا ہویة تقلیدیة، وسلوک یبدو شاذا، ولا قناة لتوضیح النزاع. یحتاج کل کسر إلی إصلاح علی مستوی البروتوکول. لم ینجح تغلیف سکک الدفع القدیمة بتجربة وکیل أجمل.

2. لماذا لا یستطیع بروتوکول واحد حل الکسور کلہا

لا یستطیع بروتوکول واحد حل الکسور الأربعة کلہا، لأن الکسور تحدث فی طبقات مختلفة، ولکل منہا أصحاب نفوذ أقویاء. تتخصص البروتوکولات الأربعة: ACP فی التجارة، وAP2 فی التفویض، وx402 وMPP فی التسویة. داخل الطبقة تختار واحدا؛ وعبر الطبقات ترکب عدة بروتوکولات.

3. عدة OpenAI Agents SDK بوصفہا العمیل الموحد

إن SDK ہو العمیل الموحد للبروتوکولات الأربعة کلہا. یصبح کل بروتوکول دالة واحدة أو أکثر من دوال @function_tool یستدعیہا الوکیل. وتطابق output_type وcontext وtool_input_guardrail فی SDK قضایا البروتوکولات بنظافة: نتائج دفع منظمة، وسیاق دفع لکل مستخدم، وفحوص حدود إنفاق قبل التنفیذ.

4. الطبقة 1، الاکتشاف (کیف تعثر الوکلاء علی ما یمکنہا شراءہ)

تجیب الطبقة 1 عن "ما المتاح؟" تتنافس أربعة خیارات: MCP لخوادم الأدوات الداخلیة، وA2A للنظم متعددة الوکلاء، وأدلة الوکلاء لخدمات الطرف الثالث، وواجہات التسوق بالذکاء الاصطناعی للمنتجات الاستہلاکیة. اختر ما یطابق مکان وجود خدمات الوکیل المطلوبة؛ فہی لیست متنافیة.

5. الطبقة 2، الہویة والتفویض (إثبات أن الوکیل مسموح لہ)

تجیب الطبقة 2 عن سؤالین: ہل فوّض الإنسان ہذا، وہل الوکیل ہو من یدعی أنہ ہو؟ تتنافس أربعة بروتوکولات: تفویضات AP2 (صارمة التدقیق)، وACP SPT (أصلی ل Stripe)، وTAP (ہویة فقط)، وERC-8004 (ثقة متعددة الوکلاء). ادمج عبر RunContextWrapper لفحص auth لکل أداة وtool_input_guardrail لفرض الإنفاق. اختر بناء علی نموذج الثقة؛ فہی لیست قابلة للتبادل.

6. الطبقة 3، التجارة (دورة حیاة الشراء الکاملة)

تتعامل الطبقة 3 مع السلة، وcheckout، والتنفیذ، والنزاع، والاسترداد. یتنافس ACP وUCP علی تدفقات المستہلک؛ ولا یملک وصول API بین الآلات طبقة تجارة. آلیات الاسترداد والنزاع ہی التعقید الخفی الذی یفصل بروتوکول التجارة الحقیقی عن بروتوکول الدفع فقط. اختر بناء علی حالة الاستخدام: دورة حیاة مطلوبة (ACP/UCP) أو دورة حیاة متجاوزة (API مباشر).

7. الطبقة 4، التسویة (حین یتحرک المال فعلا)

الطبقة 4 ہی حیث یتحرک المال. تتنافس أربعة خیارات: x402 لعملة مستقرة بین الآلات، وMPP للجلسات متعددة السکک، وسکک البطاقات لمشتریات المستہلک مع chargebacks، والبنک أو Lightning للحالات عالیة القیمة أو منخفضة الرسوم جدا. یتعلق الاختیار غالبا بالمال: دون الدولار إلی x402، والمستہلک إلی البطاقات، والمؤسسة إلی MPP. تحدد التسویة عادة باختیار التجارة؛ اختر قاع المکدس، لا سککا معزولة.

8. بروتوکول ACP، بروتوکول تسوق المستہلک

إن ACP ہو بروتوکول التجارة الجاہز للإنتاج لتسوق المستہلک. یحدد SPT نطاق إنفاق الوکیل؛ ویبقی التاجر merchant of record. تدمجہ عبر Stripe SDK مع عمیل ACP رقیق، موصولا کأربع دوال @function_tool (تصفح، checkout، حالة، استرداد). ابدأ بتأکید المستخدم للسلال حتی تقیس دقة سلة الوکیل.

9. بروتوکول AP2، طبقة التفویض

إن AP2 ہو طبقة التفویض لتجارة وکلاء صارمة التدقیق. تشکل أنواع التفویض الثلاثة (Intent وCart وPayment) سلسلة غیر قابلة للإنکار تثبت موافقة المستخدم. یناسب step.wait_for_event تدفقات توقیع التفویض بطبیعتہ. أنشئ Intent Mandates أولا، قبل بدء التسوق، لا کفکرة لاحقة عند checkout.

10. بروتوکول x402، بروتوکول التسویة الأصیل فی HTTP

إن x402 ہو بروتوکول التسویة الأصیل فی HTTP للمدفوعات الصغیرة بین الآلات. رمز الحالة 402 مع ترویسة دفع موقعة وتوقیع EIP-3009 یسوی خلال ثانیة إلی ثانیتین بلا إنشاء حساب. حدود الإنفاق فی محفظة العقد الذکی ہی السلامة التی تحمیک فعلا، لا سقف کل طلب. افحص أسماء الترویسات مقابل نسخة المواصفة وال facilitator الذی تدمج معہ؛ فہی تختلف بین V1 وV2.

11. بروتوکول MPP، بروتوکول التسویة القائم علی الجلسات

إن MPP ہو جواب Stripe فی التسویة علی x402، مبنی للقیاس القائم علی الجلسات والتوجیہ متعدد السکک. یغطی intentان، charge (دفعة مفردة) وsession (بث مفوض مسبقا)، المشتریات المفردة والقیاس المتکرر. یستخدم شکل HTTP ترویسات قیاسیة WWW-Authenticate: Payment وAuthorization: Payment وPayment-Receipt، لذلک یبدو ک HTTP auth مألوف. اضبط سقوف الجلسات علی العمل المتوقع، لا علی الراحة.

12. أصغر مکدس صالح لمدفوعات الوکلاء

أصغر مکدس صالح ہو أصغر ترکیب یطلق قیمة لحالة الاستخدام. أربعة تراکیب شائعة: تسوق المستہلک (ACP مع بطاقات)، ووکیل API (x402 فقط)، ومشتریات المؤسسة (AP2 مع ACP/UCP ومع MPP/cards)، وسوق متعدد الوکلاء (AP2 مع ERC-8004 ومع x402). لا تبن مکدسات عامة؛ اختر ترکیبا واحدا لکل حالة استخدام وأطلقہ.

13. متی تترکب البروتوکولات عبر الطبقات وتتنافس داخل طبقة

تترکب البروتوکولات عبر الطبقات (AP2 مع x402، وACP مع x402، وMCP مع x402)؛ وتتنافس داخل الطبقة (AP2 ضد ACP SPT، وACP ضد UCP، وx402 ضد MPP). الاختبار ہو "ہل ہذہ فی الطبقة نفسہا؟" إذا نعم، اختر واحدا؛ وإذا لا، فہی غالبا تترکب.

14. آثار الکلفة والکمون فی اختیارات الترکیب

تکلف سکک البطاقات 2.9% زائد 0.30 دولار لکل معاملة لکنہا تقدم حمایة chargeback؛ وتکلف سکک العملة المستقرة أقل من سنت لکنہا تحتاج بنیة crypto-native. النقطة بالدولار حیث تتوقف سکک البطاقات عن المنطقیة تقع حول 5 إلی 10 دولارات. ونقطة الکمون حیث یصبح checkout عبر ACP بطیئا جدا تقع حول خمس ثوان للتدفقات التی تواجہ المستخدم. استخدم الکلفة والکمون لتحدید الترکیب، لا التفضیل المجرد.

15. فرض حدود الإنفاق علی ثلاثة مستویات معماریة

افرض حدود الإنفاق علی ثلاثة مستویات مستقلة: بنیة المحفظة أو طریقة الدفع، وحواجز أدوات SDK (tool_input_guardrail تحدیدا، لأنہ یعمل قبل کل أداة ویمکنہ حجبہا)، ومنطق العمل فی التطبیق. یستخدم کل مستوی بنیة مختلفة، لذلک یلتقط الآخران خطأ أحدہا. استخدام output_guardrail للتحکم فی الإنفاق ہو الخطأ الأکثر شیوعا؛ یعمل علی الرد النہائی، متأخرا جدا لإیقاف الدفع.

16. نظافة ہویة الوکیل: المفاتیح والمحافظ وسجلات التدقیق

ہویة الوکیل تشفیریة؛ مفتاح التوقیع ہو الشیء الوحید الفاصل بین الإنفاق المصرح والاحتیال. أربع عادات: فصل المحفظة لکل وکیل، وتدویر المفاتیح بجدول وعند الطلب، وسجلات التدقیق إلی تخزین متین مستقل عن runtime، وtraces موزعة ب trace ID واحد یغطی المعاملة کلہا. تذہب مفاتیح التوقیع إلی key vault، لا إلی env vars ولا إلی الکود المصدری.

17. آلیات النزاع والاسترداد عبر البروتوکولات الأربعة

یرث ACP chargebacks من شبکات البطاقات. ویقدم AP2 سلسلة التفویضات کدلیل قانونی لکنہ لا یستبدل مسار النزاع فی السکة الأساسیة. وx402 غیر قابل للاسترداد بالتصمیم: مناسب للمدفوعات الصغیرة، وخاطئ حیث تہم الاستردادات. ویرث MPP آلیات نزاع Stripe عبر السکک. نموذج النزاع الذی تحتاجہ حالة الاستخدام غالبا ہو أقوی ما یفرض ترکیب البروتوکولات.

18. سباکة FastAPI وInngest webhook: إغلاق حلقة الطلب والاستجابة

تجارة الوکلاء ثنائیة الاتجاہ: تصل النزاعات وتوقیعات التفویضات والاستردادات وطلبات الدفع من جہة البائع لا متزامنة عبر webhooks. تغطی ثلاثة أنماط الحاجة: یطلق webhook من Stripe حدث Inngest إلی workflow متین؛ ویطلق callback لتوقیع AP2 حدثا یستأنف step.wait_for_event؛ ویعرض middleware من جہة بائع x402 واجہات API مدفوعة. تبقی handlers FastAPI رقیقة؛ ودوال Inngest متینة. تشغل أنظمة الإنتاج الثلاثة.

19. انضباط الترکیب الطبقی

البروتوکولات الأربعة (ACP وAP2 وx402 وMPP) طبقات، لا بدائل. عملک أن تقرأ حالة الاستخدام، وتقسمہا إلی الطبقات الأربع، وتختار البروتوکول الصحیح فی کل واحدة، وتبرر الاختیار مقابل القیود الحقیقیة لحالة الاستخدام. OpenAI Agents SDK ہو العمیل الموحد. یبقی الانضباط صالحا أیا کانت البروتوکولات التی تفوز خلال ال 24 شہرا القادمة؛ الطبقات مستقرة حتی لو تطورت البروتوکولات فی کل طبقة.

---

قالب مراجعة التصمیم: أسئلة تطرحہا عند مراجعة أی معماریة لتجارة الوکلاء

عندما تراجع تصمیم زمیل (أو مسودتک أنت بعد یوم من الابتعاد)، امش ہذہ الأسئلة بالترتیب. یرتبط کل سؤال بقسم من ہذہ الدورة؛ إذا لم ترض الإجابة السؤال، فارجع إلی ذلک القسم.

أسئلة المعماریة

1. ما حالة الاستخدام التی یخدمہا ہذا؟ إذا کانت "عدة حالات"، فما الأساسیة؟ التصمیم الذی یحاول خدمة الحالات القانونیة الأربع کلہا ہو anti-pattern من المفہوم 12؛ علّمہ.
2. امش الطبقات الأربع صراحة. الاکتشاف؟ التفویض؟ التجارة؟ التسویة؟ أی بروتوکول فی کل طبقة؟ اجعل ترکیب البروتوکولات الأربعة یقال بصوت واضح.
3. برر اختیار کل طبقة مقابل حالة الاستخدام. لماذا ہذا البروتوکول فی ہذہ الطبقة؟ ما الذی کان سیتغیر مع بروتوکول آخر؟ ینطبق اختبار عبر/داخل من المفہوم 13 ہنا.
4. ہل یوجد تداخل بروتوکولات فی أی طبقة؟ بروتوکولان یتنافسان فی الطبقة 4؟ اثنان فی الطبقة 2؟ إذا نعم، فہذہ تعقید یحتاج إلی حالة استخدام تبررہ.

الأسئلة الاقتصادیة

5. ما توزیع قیمة المعاملات؟ دون الدولار؟ من 10 إلی 100 دولار؟ أکثر من 1,000 دولار؟ یجب أن یقود عتبة المفہوم 14 الاقتصادیة اختیار التسویة.
6. ما میزانیة الکمون؟ دون الثانیة؟ 5 إلی 30 ثانیة؟ یجب أن تقید میزانیة الکمون اختیارات التسویة والتفویض.
7. ما الکلفة لکل معاملة عند الحجم المتوقع؟ اجمع رسوم البروتوکول مع رسوم المعالج مع کلفة البنیة لکل معاملة. استخدمہا لفحص أن الترکیب مجد اقتصادیا.

أسئلة التشغیل

8. ہل فرض حدود الإنفاق موجود علی المستویات الثلاثة؟ المحفظة/طریقة الدفع، SDK، منطق عمل التطبیق. المفہوم 15: تجاوز أی واحد یعرّضک.
9. ہل نظافة الہویة موجودة؟ فصل المحفظة لکل وکیل، تدویر المفاتیح، سجلات التدقیق إلی تخزین متین، traces موزعة ب trace ID واحد لکل معاملة. عادات المفہوم 16 الأربع.
10. آلیات النزاع والاسترداد؟ ہل یتعامل الترکیب مع النزاعات التی ستحصل فی حالة الاستخدام فعلا؟ المفہوم 17: غالبا ہذا أقوی قید.
11. الغلاف التشغیلی؟ أین یتولی Inngest (أو تنفیذ متین مکافئ) التدفقات طویلة التشغیل وretries وidempotency؟ مغطی فی الدورة المکثفة فی عامل الإنتاج.
12. بوابات human-in-the-loop؟ أین یؤکد المستخدم أو المشغل داخل التدفق؟ ابدأ ببوابة تأکید لأول 30 یوما فی الإنتاج.

أسئلة webhooks وcallbacks غیر المتزامنة (المفہوم 18)

13. ہل handler webhook من Stripe موجود ورقیق؟ یتحقق من التوقیع، ویطلق حدث Inngest، ویرد ACK فی أقل من خمس ثوان. یعیش منطق العمل فی دالة Inngest، لا فی handler.
14. ہل callback توقیع تفویض AP2 موجود ویتحقق من توقیعات المستخدم؟ من دونہ لا یستأنف step.wait_for_event لدی الوکیل أبدا. ومن دون التحقق من التوقیع یستطیع أی شخص تزویر أحداث mandate-signed.
15. إذا کنت تعرض APIs مدفوعة: ہل x402 seller-side middleware مضبوط لکل route؟ تشغل الأسواق متعددة الوکلاء کود جہة المشتری وجہة البائع معا؛ وتحتاج جہة البائع إلی middleware.
16. ہل مفاتیح idempotency فی Inngest موجودة علی کل دالة یحرکہا webhook؟ تعید Stripe المحاولة ب event.id نفسہ؛ ومن دون idempotency تخصم أو تسترد مرتین.
17. طبقة العقد: ہل توجد نماذج Pydantic عند کل حد؟ إرجاع الأدوات، وحمولات البروتوکولات، وأجسام طلب واستجابة FastAPI، وحمولات أحداث Inngest، کلہا ذات أنواع. Decimal للمال، لا float أبدا.

أسئلة أنماط الفشل

18. ما أکثر نمط فشل احتمالا فی الإنتاج؟ کان لکل قرار قانونی واحد: عدم تطابق السلة (القرار 1)، وإنفاق منفلت (القرار 2)، وعدم تطابق نطاق Intent Mandate (القرار 3)، وسمعة متلاعب بہا (القرار 4). ما نمطک؟
19. ما التخفیف؟ کان لکل نمط فشل فی الجزء 5 تخفیف صریح. ہل یتضمنہ التصمیم، أم یعتمد علی "البروتوکول سیتعامل معہ"؟

أسئلة جاہزیة المسار (لنشر الإنتاج)

20. من أی مسار تعلم یعمل الفریق؟ قارئ، مبتدئ، متوسط، متقدم. کن صریحا. یحتاج نشر الإنتاج إلی عمق المسار المتقدم، لا معرفة مسار القارئ.
21. ما خطة rollback إذا أساء الوکیل التصرف؟ kill switch للمحفظة؟ إلغاء SPT؟ تعطیل الوکیل علی مستوی SDK؟ عرّف ذلک قبل الإطلاق، لا بعد الحادث.

---

المراجع

مصادر أولیة للبروتوکولات الأربعة. فضّلہا علی التعلیقات الثانویة؛ فالمواصفات تتطور أسرع من الکتابات عنہا.

بروتوکول ACP (Agentic Commerce Protocol)

• مستودع المواصفة: github.com/agentic-commerce-protocol/agentic-commerce-protocol (Apache 2.0)
• موقع المطورین: agenticcommerce.dev
• القائمان علی الصیانة: OpenAI وStripe
• وثائق تکامل Stripe: stripe.com/docs/agentic-commerce
• آخر نسخة مواصفة مذکورة: 2026-04-17

بروتوکول AP2 (Agent Payments Protocol)

• مستودع المواصفة: github.com/google-agentic-commerce/AP2 (Apache 2.0)
• موقع الوثائق: ap2-protocol.org
• أعضاء التحالف: Google مع أکثر من 60 شریکا (Salesforce وServiceNow وAdobe وShopee وEtsy وAdyen وAmerican Express وJCB وUnionPay International وPayPal وMastercard وCoinbase وغیرہم)
• مستودع امتداد a2a-x402: github.com/google-a2a/a2a-x402
• آخر نسخة مذکورة: v0.2.0 (أبریل 2026)

بروتوکول x402

• مستودع المواصفة: github.com/coinbase/x402 (Apache 2.0)
• موقع الوثائق: x402.gitbook.io (وأیضا x402.org)
• أنشأتہ Coinbase وتدیرہ الآن x402 Foundation تحت Linux Foundation (أبریل 2026)، مع Cloudflare وStripe وAWS وGoogle وغیرہم.
• تکامل Cloudflare OpenAI Agents SDK: developers.cloudflare.com/agents/x402
• دلیل التبنی: agent.market
• من أعضاء x402 Foundation: Adyen وAWS وAmerican Express وBase وCircle وCloudflare وCoinbase وGoogle وMastercard وMicrosoft وPolygon Labs وShopify وSolana Foundation وStripe وVisa

بروتوکول MPP (Machine Payments Protocol)

• موقع المواصفة: mpp.dev
• المطوران المشارکان: Stripe وTempo (blockchain L1 من Stripe، محضونة مع Paradigm)
• إعلان Stripe: stripe.com/blog/machine-payments-protocol
• تاریخ الإطلاق: 18 مارس 2026 (mainnet)
• الشرکاء عند الإطلاق: Stripe وVisa وLightspark وAnthropic وOpenAI وShopify وأکثر من 100 خدمة

بروتوکولات مجاورة

• بروتوکول A2A (Agent2Agent، Google): github.com/google-a2a/A2A، البروتوکول الذی یوسعہ AP2
• معیار MCP (Model Context Protocol، Anthropic): modelcontextprotocol.io، طبقة الأدوات والسیاق التی تکتشف الوکلاء الخدمات من خلالہا
• بروتوکول UCP (Universal Commerce Protocol، Google): أعلن عنہ کنظیر ACP لواجہات تسوق Google
• بروتوکول TAP (Trusted Agent Protocol، Visa وCloudflare): بروتوکول تحقق الہویة أطلق فی 14 أکتوبر 2025
• معیار ERC-8004: معیار ثقة علی السلسلة للمعاملات متعددة الوکلاء

عدة OpenAI Agents SDK

• حزمة Python SDK: pip install openai-agents (آخر إصدار 19 مایو 2026)
• الوثائق: openai.github.io/openai-agents-python
• حزمة JavaScript/TypeScript SDK: github.com/openai/openai-agents-js

دورات Agent Factory ذات الصلة

• الدورة المکثفة فی بناء وکلاء الذکاء الاصطناعی: أساسیات OpenAI Agents SDK (Agent وRunner.run() و@function_tool)
• الدورة المکثفة فی عامل الإنتاج: Inngest بوصفہ الغلاف التشغیلی لتدفقات وکلاء متینة
• الدورة المکثفة فی التطویر المدفوع بالتقییم: اختبار الوکلاء وتقییمہا
• الدورة المکثفة فی اختیار المعماریات الوکیلة: أی نمط وکیلی یناسب أی حالة استخدام
• الدورة المکثفة فی نشر الوکلاء (cloud deployment): غلاف السحابة (Azure Container Apps مع Neon وCloudflare). قید العمل؛ أضف الرابط عند إطلاقہا.

أدوات التشغیل وطبقة العقد (تستخدم بکثافة فی المفہومین 16 و18)

• منصة Inngest: inngest.com، منصة التنفیذ المتین التی تشغل workflows الوکلاء فی ہذہ الدورة
• إطار FastAPI: fastapi.tiangolo.com، طبقة HTTP غیر المتزامنة حیث تعیش نقاط نہایة webhook وmiddleware x402 من جہة البائع
• مکتبة Pydantic: pydantic.dev، عقد النوع عند کل حد (إرجاع الأدوات، وحمولات البروتوکولات، وأجسام FastAPI، وأحداث Inngest)
• نظام OpenTelemetry: opentelemetry.io، tracing موزع مع auto-instrumentation ل httpx وopenai-agents وFastAPI وInngest؛ trace ID واحد یغطی المعاملة کلہا
• عمیل httpx: python-httpx.org، عمیل HTTP غیر المتزامن تحت x402-client وعمیل ACP وامتداد AP2 a2a-x402
• خدمة Azure Key Vault: حیث تعیش مفاتیح التوقیع فی الإنتاج، وتدور وفق انضباط المفہوم 16
• وثائق Stripe webhooks: stripe.com/docs/webhooks، التحقق من التوقیع، وأنواع الأحداث، ودلالات retry

---

أصبحت تملک الإطار کلہ: الطبقات الأربع، والبروتوکولات الأربعة، وقواعد ترکیبہا، وخمسة قرارات عملیة، ومخاوف الإنتاج التی تحدد ہل یصمد النظام، ومرجعا من صفحة واحدة للاحتفاظ بہ. ستواصل البروتوکولات التحرک. أما انضباط الطبقات الأربع فلن یتحرک. ابن من الطبقات، وستبقی علی صواب حتی عندما تتغیر أسماء البروتوکولات.