وكلاء قادرون على الدفع: ACP وAP2 وx402 وMPP في الإنتاج

دورة مكثفة عن البروتوكولات الأربعة التي تجعل أنظمة OpenAI Agents SDK قادرة على إنفاق المال: عند التجار، وأمام واجهات API، ومع وكلاء آخرين، وعبر الاقتصاد المفتوح. هذه الدورة للمهندسين الذين شحنوا وكلاء بالفعل، والآن يحتاجون إلى جعلهم يدفعون.

19 مفهوماً. 5 قرارات. 3 مخططات. أربعة مسارات تعلم. مسار القارئ يستغرق ساعتين إلى ثلاث ساعات من القراءة الخالصة: حزمة الطبقات الأربع، وكل بروتوكول بعمق، وقواعد التركيب، بلا إعداد. تضيف مسارات المبتدئ والمتوسط والمتقدم عمقاً عملياً متزايداً في توصيل الوكلاء بالبروتوكولات، وتشغيل التركيب بشكل متين، وإدارة الهوية، والإنفاق، والنزاعات. تستغرق تقريباً يوماً واحداً، ثم يومين إلى ثلاثة أيام، ثم أربعة إلى خمسة أيام. التقدير الصادق: ساعتان إلى ثلاث للقراءة، وأربعة إلى خمسة أيام حتى يجعل فريق واحد هذه الحزمة عادة عملية. اختر مسارك قبل مختبر القرارات في الجزء 5.

الفكرة الواحدة التي تقوم عليها الدورة كلها هي: البروتوكولات الأربعة ليست منافسة لبعضها. إنها طبقات. تسأل معظم المقالات: "ACP أم x402؟" وهذا سؤال يخلط بين طبيعة الأشياء. النظام الحقيقي في 2026 يستخدم عدة بروتوكولات معاً، لأن كل واحد يحل طبقة مختلفة من مشكلة تجارة الوكلاء. وكيل تسوق للمستهلك يستخدم ACP في طبقة التجارة، وسكك البطاقات في التسوية. وكيل يدفع لواجهات API يستخدم x402 في الطبقتين، لأن مدفوعات الآلة الصغيرة تجعل التفويض والتسوية ينهاران في طبقة واحدة. وكيل مشتريات للمؤسسة يستخدم Mandates من AP2 لإثبات أن الإنسان فوّض الإنفاق، ثم Stripe MPP في التسوية. ستتعلم أن تقرأ حالة الاستخدام وتختار التركيب الصحيح.

إذا لم تأخذ دورات Agent Factory الأخرى

تذكر هذه الدورة بعض الدورات الشقيقة: الدورة المكثفة في بناء وكلاء الذكاء الاصطناعي لأساسيات SDK، والدورة المكثفة في Production Worker لتشغيل الوكلاء بمتانة مع Inngest، والدورة المكثفة في التطوير المدفوع بالتقييم، والدورة المكثفة في اختيار المعماريات الوكيلة. تستطيع قراءة هذه الدورة وحدها. البروتوكولات الأربعة، والتقسيم الطبقي، وكود SDK، وانضباط القرار كلها قائمة بذاتها. الشيء الوحيد المفيد: كود الجزء 3 يفترض أنك تستطيع قراءة Agent وRunner.run() و@function_tool. إذا كانت جديدة عليك، ف skim دورة بناء وكلاء الذكاء الاصطناعي أو وثائق OpenAI Agents SDK أولاً، ثم عد.

ما يقابل كل بروتوكول إذا كنت تستخدم حزمة مختلفة

إذا لم تكن تعمل على OpenAI Agents SDK مع Stripe وCoinbase وCloudflare، فهذا الجدول يطابق كل تنفيذ مرجعي مع بدائل شائعة. مواصفات البروتوكولات لا تعتمد على حزمة بعينها؛ أسماء البدائيات فقط تختلف.

البروتوكول	SDK المرجعي الأساسي في 2026	بدائل شائعة	الترخيص / الحوكمة
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 مع توقيع mandates مخصص، أو 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

طريقة استخدام الجدول: عندما تقول الدورة "صل أداة @function_tool الخاصة بالوكيل بنقطة نهاية Stripe ACP" وأنت تستخدم Adyen مع LangGraph، فاقرأها هكذا: "صل أداة LangGraph المكافئة بنقطة نهاية Adyen ACP." الحجة نفسها؛ الأسماء تتغير. لا تحتاج إلى تعلم حزمة Stripe لتفهم الدورة. طابق البدائيات، اتبع الإطار، ثم طبقه على حزمك.

المسرد

📖 المصطلحات التي تستخدمها هذه الدورة، افتحها في القراءة الأولى وارجع إليها لاحقاً

البروتوكولات الأربعة الرئيسية

• ACP (Agentic Commerce Protocol). بروتوكول تسوق المستهلك، بنته OpenAI وStripe. يحكم كيف يكمل الوكيل checkout لدى تاجر حقيقي نيابة عن شخص. يشغل ChatGPT Instant Checkout. يعيش غالباً في طبقة التجارة. ترخيصه Apache 2.0.
• AP2 (Agent Payments Protocol). بروتوكول التفويض، بنته Google مع أكثر من 60 شريكاً. ينتج "mandates" موقعة تثبت أن إنساناً سمح للوكيل بالإنفاق. لا يحرك المال بنفسه؛ بل يثبت أن الإنفاق كان مفوضاً. ترخيصه Apache 2.0.
• x402. بروتوكول تسوية أصيل في HTTP، بنته Coinbase وتحكمه الآن Linux Foundation. يحيي رمز HTTP 402 "Payment Required" غير المستخدم، حتى يستطيع الوكيل دفع تكلفة استدعاء API خلال ثانية إلى ثانيتين بعملة مستقرة. ترخيصه Apache 2.0.
• MPP (Machine Payments Protocol). بروتوكول التسوية من Stripe وTempo. حركته الأساسية هي "الجلسة": يوافق الوكيل مسبقاً على سقف إنفاق، ثم يبث دفعات صغيرة كثيرة داخله. متعدد السكك: stablecoin وLightning وبطاقات. ترخيصه Apache 2.0.

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

• طبقة الاكتشاف. حيث يعرف الوكيل ما يستطيع شراءه. تجيب عنها خوادم MCP، وA2A، وأدلة الوكلاء، أو واجهات التسوق داخل منتجات الذكاء الاصطناعي. السؤال: "ما المتاح؟"
• طبقة الهوية والتفويض. تثبت شيئين قبل تحريك المال: أن الإنسان سمح بهذا الإنفاق، وأن الوكيل هو من يدعيه. السؤال: "هل يُسمح لي بالإنفاق؟"
• طبقة التجارة. تشغل عملية الشراء كاملة: السلة، والcheckout، والتنفيذ، والنزاع، والاسترداد. السؤال: "ما دورة حياة الشراء الكاملة؟" وتُتجاوز كلياً في استدعاءات API البسيطة.
• طبقة التسوية. حيث ينتقل المال فعلياً. السؤال: "أين يتحرك المال حقاً؟"
• سكة التسوية. الأنبوب الفعلي الذي يسافر المال عبره: شبكات البطاقات، أو stablecoins على blockchain، أو التحويل البنكي، أو Lightning.

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

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

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

• Stablecoin. عملة مشفرة مربوطة بقيمة مستقرة، عادة دولار أمريكي واحد. يستخدمها الوكلاء حتى تبقى دفعة 0.05 دولار بقيمة خمسة سنتات بين الإرسال والتسوية.
• USDC. العملة المستقرة المرتبطة بالدولار التي تستخدمها معظم مدفوعات x402. تصدرها Circle.
• HTTP 402 Payment Required. رمز HTTP محجوز منذ 1997 وبقي غير مستخدم حتى أحياه x402. يرد الخادم بـ402 مع متطلبات الدفع؛ يعيد العميل الطلب مع إثبات دفع موقّع.
• EIP-3009 (transferWithAuthorization). معيار Ethereum الذي يبنى عليه x402. يسمح للمشتري بتوقيع دفعة خارج السلسلة يرسلها طرف آخر إلى السلسلة، فلا يدفع المشتري gas ولا يلمس blockchain مباشرة.
• Facilitator في x402. طرف ثالث اختياري يتحقق من التوقيع ويرسل الدفع على السلسلة للتاجر، حتى لا يشغل التاجر plumbing خاصاً بـblockchain.
• CAIP-2. طريقة قياسية لتسمية blockchain حتى يبقى البروتوكول محايد السلسلة.
• EIP-155 / chain id. مخطط الترقيم داخل CAIP-2 لسلاسل Ethereum-style. eip155:8453 يعني سلسلة Base.
• محفظة عقد ذكي. محفظة crypto تُفرض قواعد إنفاقها، مثل سقف العملية أو اليوم أو المستلم، بكود على blockchain نفسه. لذلك تصمد الحدود حتى إذا اختل كود الوكيل.
• جلسة MPP. حركة MPP الأساسية. بدلاً من توقيع كل دفعة مفردة، يفتح الوكيل جلسة بسقف إنفاق وحد زمني، ثم يبث دفعات صغيرة محسوبة حتى تغلق.

مفاهيم التجارة والمال

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

حزمة الوكيل والبروتوكولات المجاورة

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

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

ستستفيد أكثر من هذه الدورة إذا كان لديك:

1. دورة Build AI Agents أو خبرة مكافئة في SDK. التكاملات معروضة ككود SDK، لذلك يجب أن تقرأ Agent وRunner.run() و@function_tool براحة. انظر دورة بناء وكلاء الذكاء الاصطناعي.
2. دورة Choosing Agentic Architectures أو حس تصميم مكافئ. إطار "أي تركيب لأي حالة استخدام" في الجزء 5 يبني على انضباط اختيار النمط. انظر دورة اختيار المعماريات الوكيلة.
3. أساسيات HTTP. رموز الحالة، ودورة الطلب/الاستجابة، والترويسات. يعمل x402 خصوصاً على مستوى HTTP.
4. مفردات دفع أساسية. تاجر، تسوية، نزاع، chargeback. تشرح الدورة الأجزاء الخاصة بالوكلاء، لكنها تفترض أنك تعرف معنى "merchant of record".

لا تحتاج إلى خبرة blockchain أو smart contracts، ولا تحتاج إلى خبرة سابقة بأي من البروتوكولات الأربعة. ستتعلم ما يكفي لمتابعة الدورة.

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

تعمل هذه الدورة على أربعة أعماق. اختر مسارك قبل الجزء 5.

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

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

حزمة الطبقات الأربع

هذا هو المخطط الذي يحمل بقية الدورة.

كل حالة تجارة وكلاء تلمس الطبقات الأربع، لكن حالات الاستخدام المختلفة تركب بروتوكولات مختلفة داخل كل طبقة. وكيل تسوق للمستهلك: MCP للاكتشاف، وACP SPT للتفويض، وACP للتجارة، وسكك البطاقات للتسوية. وكيل يدفع لواجهات API: دليل وكلاء للاكتشاف، وتوقيع EIP-3009 للتفويض، ولا طبقة تجارة أصلاً، وx402 للتسوية. وكيل مشتريات للمؤسسة: دليل A2A، وAP2 mandate، وACP أو UCP للتجارة، وStripe MPP للتسوية. القاعدة بسيطة: اختر بروتوكولاً واحداً لكل طبقة، واجعل حالة الاستخدام تبرر كل اختيار.

الجزء 1: لماذا تحتاج تجارة الوكلاء إلى بروتوكولات جديدة

هل تقرأ الجزء 1 قراءة خفيفة؟

يقدم هذا الجزء ستة أسماء بسرعة: ACP وAP2 وx402 وMPP وMCP وA2A، وثلاث طبقات. هذا مقصود: إنه briefing لا deep dive. أقل ما تحتاج إلى حفظه: ACP للتسوق الاستهلاكي، AP2 للتفويض عبر mandates، x402 للدفع المستقر لكل طلب HTTP، MPP للدفع عبر جلسات. MCP وA2A يساعدان الوكلاء على الاكتشاف والتخاطب، وليسا بروتوكولي دفع.

المفهوم 1: الافتراض الذي انكسر

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

بُنيت أنظمة الدفع على افتراض صامت: إنسان أمام لوحة المفاتيح يضغط "اشتر". كل شاشة، وكل فحص احتيال، وكل عملية نزاع، وكل نموذج تسجيل صمم للبشر. يكسر وكلاء الذكاء الاصطناعي هذا بثلاث طرق:

الكسر 1: الوكلاء لا يملكون عناوين بريد وهواتف كما يملكها البشر. تريد تدفقات الدفع الاستهلاكية حساباً، ويريد الحساب بريداً وهاتفاً واسماً غالباً. الوكيل المستقل لا يملك ذلك. إذا اختلقتها فقد أنشأت كياناً يفشل KYC فور أن يفحصه نظام الاحتيال.

الكسر 2: الوكلاء يتصرفون آلاف المرات في الثانية. تكشف أنظمة الاحتيال السلوك الغريب بالسرعة والمكان والنمط. وكيل يجري 1000 استدعاء API في دقيقة يشبه هجوم credential-stuffing. ما هو طبيعي للوكيل إنذار للإنسان.

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

الكسر	ما لا تستطيع سكك البشر إصلاحه	ما تعطيه سكك الوكلاء
لا بريد ولا حساب	إجبار الوكلاء على حسابات مزيفة	هوية مشفرة مثل TAP أو ERC-8004، أو رموز محددة النطاق مثل ACP SPT وAP2 Mandate
سلوك عالي التكرار	حظر حركة تبدو كأنها هجوم	دفع HTTP لكل طلب عبر x402، أو جلسات مسبقة التفويض عبر MPP
لا هاتف للنزاعات	إرسال نزاعات إلى بريد لا يقرأه الوكيل	تفويض قائم على mandates في AP2 مع audit trail غير قابل للإنكار

مسار "فلنغلف المدفوعات القديمة بتجربة مستخدم أجمل للوكلاء" فشل بالفعل. حاولت عدة شركات ناشئة في 2024 و2025 إعطاء الوكلاء حسابات شبيهة بالبشر بهوية مختلقة. كشفتها أنظمة الاحتيال، وتراكمت chargebacks، وتدهورت علاقات التجار. اتضح أن الإصلاحات على مستوى البروتوكول مطلوبة، لا اختيارية.

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

المفهوم 2: لماذا لا يستطيع بروتوكول واحد الفوز

في سطر واحد: تحدث الكسور في أربع طبقات مختلفة، ومعها incumbents أقوياء، لذلك تقسم البروتوكولات العمل حسب الطبقة بدلاً من أن يبتلع واحد منها كل شيء.

لو حاول بروتوكول واحد حل كل شيء، لاحتاج أن يحدد: كيف يجد الوكيل ما يشتريه، وكيف يثبت أن الإنسان فوّضه، وكيف يدير دورة شراء كاملة، وكيف يتحرك المال. هذه طبقات مختلفة، ولكل طبقة لاعبون راسخون: الاكتشاف لمحركات البحث وAPIs، والهوية لـOAuth وسلطات الشهادات، والتجارة لـStripe وAdyen وShopify، والتسوية لـVisa وMastercard وACH وسكك crypto. لم يكن ممكناً أن يتفق كل هؤلاء على بروتوكول واحد.

ما حدث بدلاً من ذلك أن كل بروتوكول اختار الطبقة التي يملك راعيه فيها نفوذاً أكبر:

البروتوكول	موضع نفوذ الراعي	الطبقة التي أخذها
ACP	OpenAI تملك قناة التسوق في ChatGPT، وStripe تملك تكامل التجار	التجارة لتدفقات "مشتري بشري عبر AI"
AP2	Google لديها محافظ Android وتحالف واسع	التفويض عبر mandates موقعة
x402	Coinbase لديها بنية stablecoin، وCloudflare لديها edge في HTTP	التسوية لمدفوعات الآلة الصغيرة
MPP	Stripe لديها علاقات التجار، وTempo لديها blockchain	التسوية للمؤسسات والتدفقات متعددة السكك

لذلك لا تتقاتل البروتوكولات داخل كل طبقة بالطريقة نفسها. في التسوية يتنافس x402 وMPP فعلاً. في التجارة يتنافس ACP وUCP. في التفويض تتنافس AP2 وTAP وERC-8004. أما عبر الطبقات فهي تُركّب.

خلاصة المفهوم 2: لا يستطيع بروتوكول واحد إصلاح كل الكسور لأنها تعيش في طبقات مختلفة. تتخصص البروتوكولات: ACP في التجارة، وAP2 في التفويض، وx402 وMPP في التسوية. داخل الطبقة تختار واحداً؛ وعبر الطبقات تركب عدة بروتوكولات.

المفهوم 3: OpenAI Agents SDK كعميل موحد

في سطر واحد: لا تتحدث إلى أربعة بروتوكولات بأربع طرق مختلفة؛ تجعل كل واحد أداة يستدعيها الوكيل، ويصبح SDK العميل الواحد الذي يركبها.

في OpenAI Agents 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

@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."""
    spt = stripe.PaymentTokens.create(
        amount=int(max_amount * 100),
        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,
    )

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

result = await Runner.run(shopping_agent, "Buy me a red t-shirt under $30")

ما هو حقيقي هنا: ربط Agent وRunner.run و@function_tool. ما هو بديل تعليمي: عملاء الدفع. stripe.PaymentTokens.create ليس استدعاء Stripe حقيقياً؛ ACP الإنتاجي يتكامل عبر نقاط نهاية Stripe ACP الحية. وX402Client(wallet=..., max_per_request=...) مبسط أيضاً. يعطي الجزء 3 لكل بروتوكول backend mock قابل للتشغيل حتى ترى الـharness من البداية إلى النهاية من دون تحريك مال حقيقي.

ثلاثة أجزاء من بنية SDK مهمة للمدفوعات:

1. قيمة إرجاع typed لنتائج الدفع. عندما تعيد أداة الدفع Pydantic model، يحصل reasoner على معلومات نظيفة عن النجاح والفشل والخطوة التالية.
2. Runner.run(..., context=...) لسياق الدفع. يحتاج الوكيل عادة هوية المستخدم، وحدود الإنفاق، ومقبض المحفظة. مررها عبر context بدلاً من خبزها في التعليمات.
3. tool_input_guardrail لحدود الإنفاق. يعمل قبل تنفيذ الأداة ويمكنه رفض الاستدعاء. هذه هي طريقة SDK الأصلية لإيقاف الدفع قبل حدوثه.

خلاصة المفهوم 3: OpenAI Agents SDK هو العميل الموحد للبروتوكولات الأربعة. يصبح كل بروتوكول @function_tool يستدعيه الوكيل. typed returns، وcontext، وtool_input_guardrail تطابق قضايا الدفع: نتائج منظمة، وسياق لكل مستخدم، وإيقاف الدفع قبل تنفيذه.

---

---

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

قابلت الطبقات الأربع في الجزء 1؛ هنا نراها عن قرب. كل طبقة تجيب عن سؤال مختلف، ولها بروتوكولات متنافسة، وتفرض قراراً واحداً: أي بروتوكول يناسب هذه الطبقة في حالة الاستخدام هذه؟

المفهوم 4: الطبقة 1، الاكتشاف

في سطر واحد: الاكتشاف هو المكان الذي يعرف فيه الوكيل ما المتاح للشراء، وآليته الصحيحة تعتمد على مكان وجود تلك الخدمات.

قبل أن يتعامل الوكيل، يجب أن يعرف ما الموجود. يحتاج وكيل التسوق إلى تجار يحملون المنتج. يحتاج وكيل يدفع لـAPI إلى معرفة نقاط النهاية التي تملك البيانات وما تكلفتها. يحتاج وكيل المشتريات إلى موردين يمرون بقواعد compliance. الاكتشاف يجيب: "ما المتاح؟"

البروتوكول	كيف يعمل	الأنسب له
MCP	تعرض خوادم الأدوات دوال قابلة للاستدعاء؛ يتصل الوكيل، يسرد الأدوات، ويستدعيها	الوصول البرمجي إلى خدمات محددة وصلها المطور؛ العمل عالي الحجم؛ طبقة اكتشاف الأدوات المهيمنة
A2A	تنشر الوكلاء ما تقدمه داخل envelopes قياسية؛ وتكتشفها وكلاء أخرى	أنظمة متعددة الوكلاء؛ وهي طبقة الاكتشاف التي يوسعها AP2
أدلة الوكلاء مثل Agent.market وlobster.cash وTenzro	أسواق عامة تسرد APIs وخدمات مدفوعة؛ يستعلمها الوكلاء ككتالوج	خدمات طرف ثالث تكتشف وقت التشغيل
واجهات التسوق داخل AI مثل ChatGPT Instant Checkout وGoogle AI Mode	منتجات AI استهلاكية تجمع اكتشاف المنتجات وACP checkout	تدفقات المستهلك حيث يتحدث المستخدم مع AI ويرى المنتجات داخله

يدعم SDK خوادم MCP مباشرة. أما الاكتشاف غير MCP فتغلفه كأداة @function_tool عادية تعيد قوائم منظمة.

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

research_mcp = MCPServerStreamableHttp(
    name="research-services",
    params={"url": "https://research-services.example.com/mcp"},
)

@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. خدمات طرف ثالث تظهر وقت التشغيل، استخدم الأدلة. منتجات استهلاكية، استخدم واجهة تسوق AI ومعها ACP في طبقة التجارة.

خلاصة المفهوم 4: الاكتشاف يجيب "ما المتاح؟" الخيارات الأربعة هي MCP، وA2A، وأدلة الوكلاء، وواجهات التسوق داخل AI. اختر بحسب مكان عيش الخدمات؛ وهذه الخيارات قد تجتمع.

المفهوم 5: الطبقة 2، الهوية والتفويض

في سطر واحد: التفويض هو حيث يثبت الوكيل أن الإنسان سمح بالإنفاق وأن الوكيل هو من يدعيه، قبل أن يتحرك المال.

قبل تحريك المال، يجب إثبات شيئين: هوية الوكيل، وتفويض الإنسان. إذا تخطيت الطبقة 2 فستحصل على احتيال، أو شلل حيث يحتاج كل تعامل إلى نقرة بشرية.

البروتوكول	كيف يعمل	أقوى موضع له
AP2 Mandates	اعتمادات موقعة: Intent، ثم Cart، ثم Payment	التدفقات الثقيلة بالتدقيق، والصناعات المنظمة، وتدفقات متعددة الوكلاء
ACP SPT	تصدر Stripe رمز Shared Payment Token محدوداً بتاجر ومبلغ وزمن	التسوق الاستهلاكي حيث Stripe هو المعالج وسكك البطاقات تحمل chargeback discipline
TAP	توقيع هوية الوكيل داخل ترويسات HTTP، ويتحقق التجار عبر دليل Visa	التحقق من الهوية تحديداً، غالباً إضافة لا بديل
ERC-8004	سجل على السلسلة لهويات الوكلاء وتاريخ تعاملاتهم	تدفقات multi-agent بلا ثقة مشتركة

سؤالا هذه الطبقة هما: "هل فوّض الإنسان هذا؟" و"هل الوكيل هو من يدعيه؟" يجيب AP2 بسلسلة mandates موقعة. يجيب ACP بـSPT تصدره Stripe بعد تفويض المستخدم. يجيب TAP عن الهوية فقط. ويجيب ERC-8004 بسجل الهوية على السلسلة.

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

@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 "{}")
    requested = Decimal(str(args.get("max_amount_usd", 0)))
    ctx = data.context.context
    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()

@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."""
    user_session = ctx.context["user_session"]
    spt = stripe.PaymentTokens.create(
        amount=int(max_amount_usd * 100),
        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],
)

أي guardrail يوقف الدفع؟

للدفع تحتاج tool_input_guardrail تحديداً: يعمل قبل أداة الدفع ويمكنه رفضها. يعمل output_guardrail على الرد النهائي للوكيل، وهذا متأخر جداً لإيقاف المال؛ يصلح لتنظيف الرد النهائي لا للتحكم في الإنفاق.

خلاصة المفهوم 5: تجيب طبقة التفويض عن سؤالين: هل فوّض الإنسان هذا؟ وهل الوكيل هو من يدعيه؟ AP2 مناسب للتدقيق، وACP SPT مناسب للتدفقات Stripe-native، وTAP للهوية، وERC-8004 للثقة بين الوكلاء. ادمجها عبر context وtool_input_guardrail.

المفهوم 6: الطبقة 3، التجارة

في سطر واحد: التجارة هي كل ما في الشراء الحقيقي عدا التفويض والتسوية: السلة، والطلب، والتنفيذ، والنزاع، والاسترداد. واستدعاء API بسيط يتجاوزها تماماً.

تغطي التجارة دورة الشراء الكاملة: cart، وcheckout، وتأكيد الطلب، وتتبع التنفيذ، والنزاعات، والردود، وchargebacks. تفصل هذه الطبقة بين checkout وبين تحويل مال. لا يحتاج استدعاء API آلي إلى طبقة تجارة، أما شراء مستهلك فيحتاجها بوضوح.

البروتوكول	ماذا يفعل	الأنسب له
ACP	تدفق منظم: صيغة سلة، تأكيد طلب، حالة تنفيذ، نزاعات، وردود. يبقى التاجر merchant of record.	تسوق المستهلك: سلع تجزئة، اشتراكات، تنفيذ مادي.
UCP	دورة مشابهة مبنية حول واجهات Google للتسوق وGoogle Pay	تجار Google Shopping ووكلاء على واجهات Google AI
Direct API	لا بروتوكول تجارة أصلاً، بل HTTP API ودفع عبر x402 أو MPP	APIs وcompute وdata feeds حيث الشيء المباع استجابة API بلا حالة

أكثر ما يستهين به المهندسون هو الردود والنزاعات. من يشتري قميصاً بالمقاس الخطأ يتوقع إرجاعه. يجب أن يقول بروتوكول التجارة كيف يبدأ الإرجاع، وكيف يسمع الوكيل عنه، وكيف يعود المال عبر التسوية. يحصل ACP على هذا بشكل عملي لأنه يبقي التاجر merchant of record.

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

خلاصة المفهوم 6: التجارة تدير دورة الشراء الكاملة. ACP وUCP يتنافسان في تدفقات المستهلك؛ واستدعاءات machine-to-machine لا تملك طبقة تجارة. الردود والنزاعات هي الوزن الخفي الذي يميز بروتوكول التجارة الحقيقي عن دفع فقط.

المفهوم 7: الطبقة 4، التسوية

في سطر واحد: التسوية هي حيث تنتقل الدولارات فعلياً، واختيارها يتعلق غالباً باقتصاديات العملية.

كل ما فوق التسوية تنسيق. تكتمل المعاملة فقط عندما تكتمل التسوية.

البروتوكول	كيف يعمل	الاقتصاديات	الأنسب له
x402	HTTP-native؛ تسوية بتحويل stablecoin على Base/Solana/EVM موقّع بـEIP-3009	gas أقل من سنت، نهاية خلال 1-2 ثانية، بلا رسوم بروتوكول	مدفوعات machine-to-machine الصغيرة عالية التكرار
MPP	جلسات: يوافق الوكيل مسبقاً على سقف ومدة، ثم يبث دفعات محسوبة. متعدد السكك	رسوم Stripe على البطاقات؛ قريبة من الصفر على stablecoin	المؤسسات، الاشتراكات، التدفقات متعددة السكك
سكك البطاقات	Visa/Mastercard/Amex عبر Stripe؛ يقدم الوكيل SPT أو Payment Mandate	نحو 2.9% + 0.30 دولار	تدفقات المستهلك حيث يلزم chargeback
التحويل البنكي / Lightning	ACH وSEPA وBitcoin Lightning	رسوم ثابتة منخفضة أو أقل من سنت	قيم عالية أو مدفوعات عابرة للحدود

المدفوعات دون الدولار تذهب إلى x402، حيث gas stablecoin أقل من سنت. مشتريات المستهلك حتى نحو 1000 دولار تذهب إلى سكك البطاقات عبر ACP، لأن حماية chargeback تساوي الرسوم. الاشتراكات المتكررة تذهب إلى جلسات MPP. والتحويلات B2B الكبيرة تذهب إلى سكك البنك أو Lightning.

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."""
    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})",
        )
    response = await x402_client.get(url, max_payment_usdc=max_payment_usdc)
    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,
    )

هذا الفحص داخل الأداة مفيد لتجربة المستخدم، لكنه ليس الأمان الحقيقي. الأمان الذي يحميك فعلاً هو حدود محفظة العقد الذكي. حتى لو حذفت الفحص من الكود، ترفض حدود المحفظة التحويل على السلسلة.

خلاصة المفهوم 7: التسوية هي موضع تحرك المال. x402 لمدفوعات stablecoin الآلية، وMPP للجلسات متعددة السكك، والبطاقات لتدفقات المستهلك ذات chargebacks، والبنك أو Lightning للقيم العالية أو الرسوم المنخفضة جداً.

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

وضعت الأجزاء 1 و2 الإطار: أربع طبقات، وبروتوكولات متعددة داخل كل طبقة، وSDK كعميل موحد. يمشي الجزء 3 في كل بروتوكول رئيسي: ما هو، بدائياته، شكل تكامله مع SDK، وكيف تشغله الفرق في الإنتاج.

🧰 Pydantic كطبقة عقد: اقرأ مرة، وينطبق على كل بروتوكول أدناه

تستخدم كل عينات الكود في الجزء 3 نماذج Pydantic لا قواميس Python عارية، لحمولات البروتوكول، ونتائج الأدوات، وأجسام FastAPI، وأحداث Inngest. هذا هو الجزء الذي لا ينبغي تجاوزه.

تعبر أربعة حدود في تدفق تجارة الوكيل: نتيجة @function_tool إلى reasoner، ثم إلى نقطة نهاية البروتوكول، ثم استجابة البروتوكول، وأحياناً webhook لاحق إلى FastAPI. عند كل حد، تفقد القواميس غير typed حقولاً أو تغير الشكل. تلتقط نماذج 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.
    ...

استخدم Decimal للمال دائماً. كل مبلغ في هذه الدورة يستخدم Decimal لا float. يفقد floating point الدقة بطرق تتضاعف مع آلاف micropayments.

النماذج المشتركة مثل PaymentToolResult وMandateResult وOrderStatusResult وRefundResult وDiscoveryResult وX402PaymentResult وMPPSessionResult وMPPMeteredCallResult تعيش في models.py وتستوردها كتل الكود التالية بدلاً من إعادة تعريفها في كل مرة.

المفهوم 8: ACP، بروتوكول تسوق المستهلك

في سطر واحد: 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.

أين يقع. يعيش ACP غالباً في الطبقة 3، التجارة، ويمتد إلى الطبقة 2 عبر آلية الرمز. يغطي تكوين السلة، والcheckout، وإدارة الطلب، وحالة التنفيذ، والردود. يبقى التاجر merchant of record.

البدائيتان المهمتان.

1. Shared Payment Token (SPT). رمز لمرة واحدة من معالج الدفع، محدود بتاجر واحد وسقف مبلغ ونافذة قصيرة واستخدام واحد غالباً.
2. Cart Mandate عبر امتداد AP2. يستطيع ACP التركب مع AP2 لمزيد من التدقيق، بحيث يوقع المستخدم Cart Mandate قبل إرسال SPT.

تكامل SDK. ACP هو الأكثر جاهزية للإنتاج مع SDK لأن OpenAI شاركت في بنائه. يعطيك Stripe Python SDK مع client ACP رقيق التكامل الكامل.

from agents import Agent, 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
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."""
    user_session = ctx.context["user_session"]
    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,
    )
    result = await acp_client.checkout.complete(
        merchant_id=merchant_id,
        items=[i.model_dump() for i in items],
        spt_token=spt.token,
    )
    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())

shopping_agent = Agent(
    name="ShoppingAgent",
    instructions="Help the user shop at ACP-enabled merchants. Browse, confirm, checkout, check status, and refund only on explicit request.",
    tools=[acp_browse_merchant, acp_create_cart_and_checkout],
    model="gpt-5.5",
)

الحقيقي: scaffold الخاص بـSDK وtyped models. التعليمي: acp_client وstripe.PaymentTokens.create كما كُتبا؛ في الإنتاج تستبدلهما بنقاط نهاية Stripe ACP الحية. ACP يعمل على الـharness السحابي العادي: Stripe SDK داخل FastAPI، استدعاءات ACP عبر HTTPS، وSPTs داخل سياق التشغيل. أبق مفاتيح Stripe في key vault لا في env vars.

تشغيل ACP بمتانة يناسب step.run في Inngest. وعندما يحتاج الوكيل إلى انتظار موافقة المستخدم على السلة، يستخدم step.wait_for_event.

@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:
    cart = await ctx.step.run(
        "agent-builds-cart", build_cart_fn, ctx.event.data["user_query"],
    )
    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:
        return {"status": "abandoned", "reason": "user did not confirm in time"}
    result = await ctx.step.run("complete-checkout", complete_checkout_fn, cart["cart_id"])
    return {"status": "completed", "output": result}

أكثر خطأ شائع: تخطي تأكيد المستخدم على السلة. ابدأ بتأكيد السلة في أول شهر إنتاج، ثم خففه فقط بعد قياس cart accuracy.

خلاصة المفهوم 8: ACP هو بروتوكول التجارة الجاهز للإنتاج لتسوق المستهلك مع OpenAI Agents SDK. يحدد SPT نطاق إنفاق الوكيل، ويبقى التاجر merchant of record. ادمجه كأدوات browse وcheckout وstatus وrefund، واجعل Inngest يبني بوابة تأكيد السلة.

المفهوم 9: AP2، طبقة التفويض

في سطر واحد: ينتج AP2 إثباتات موقعة بأن إنساناً سمح بالإنفاق؛ لا يحرك المال بنفسه، بل يثبت أن تحريك المال كان مسموحاً.

AP2 مواصفة مفتوحة من Google مع أكثر من 60 شريكاً، أطلقت في سبتمبر 2025، وآخر إصدار مذكور v0.2.0 في أبريل 2026. هو طبقة تفويض لا طبقة تجارة ولا تسوية. ينتج mandates موقعة ثم يترك التسوية للسكة المناسبة.

Mandate	متى ينشأ	ماذا يثبت
Intent Mandate	بداية المهمة، يوقعه المستخدم	أن المستخدم سمح للوكيل بالعمل داخل قواعد محددة
Cart Mandate	بعد بناء سلة محددة وقبل checkout	أن المستخدم وافق على هذه السلة بهذا السعر
Payment Mandate	لحظة الدفع	أن المستخدم فوّض هذه الدفعة على هذه السكة

تكوّن الثلاثة سلسلة تدقيق لا يستطيع الموقع إنكارها. إذا ظهر نزاع لاحقاً، تصبح السلسلة دليلاً على ما فوّضه المستخدم.

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

@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."""
    user_session = ctx.context["user_session"]
    mandate = IntentMandate(
        principal_did=user_session.did,
        agent_did=ctx.context["agent_did"],
        task=task_description,
        rules=rules.model_dump(),
        issued_at=datetime.utcnow().isoformat(),
    )
    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")
    ctx.context["intent_mandate"] = signed
    return MandateResult(mandate_id=signed.id, status="signed", expires_at=rules.expires_at)

استيرادات ap2 وMandateSigner هنا تعليمية؛ الفكرة الحقيقية هي سلسلة mandates والتوقيع عبر A2A/verifiable credentials. تضيف AP2 إلى harness سطح توقيع للمستخدم، وتخزيناً متيناً للـmandates طوال نافذة النزاع، وغالباً retention لسنوات.

خلاصة المفهوم 9: AP2 طبقة التفويض للتجارة الثقيلة بالتدقيق. أنواع mandates الثلاثة تشكل سلسلة غير قابلة للإنكار. step.wait_for_event هو الشكل الطبيعي لانتظار التوقيع. أنشئ Intent Mandate أولاً، قبل أن يبدأ الوكيل التسوق.

المفهوم 10: x402، بروتوكول التسوية الأصيل في HTTP

في سطر واحد: يسمح x402 للوكيل بدفع تكلفة استدعاء API خلال ثانية إلى ثانيتين بعملة مستقرة، عبر إحياء رمز HTTP 402.

x402 يحول رمز 402 Payment Required إلى طبقة دفع عاملة لـAPIs وتجارة machine-to-machine. أنشأته Coinbase في مايو 2025، ثم انتقل إلى x402 Foundation تحت Linux Foundation في أبريل 2026. يعيش غالباً في الطبقة 4، التسوية، لكنه يلمس الاكتشاف عبر أدلة مثل Agent.market، وقد يكفي وحده في تدفقات machine-to-machine.

بدائياته الأربع:

1. رمز HTTP 402. يرد الخادم بمتطلبات الدفع: scheme، network بصيغة CAIP-2 مثل eip155:8453، asset، recipient، max amount، وexpiry.
2. ترويسة تفويض الدفع. يعيد العميل الطلب مع ترويسة تحمل تفويضاً موقّعاً.
3. EIP-3009. توقيع دفع خارج السلسلة يرسله طرف آخر على السلسلة.
4. Facilitator. طرف اختياري يتحقق من التوقيع ويرسل الدفع للتاجر.

أسماء الترويسات تتغير حسب الإصدار

استخدمت x402 V1 وV2 أسماء ترويسات مختلفة بين المواصفة والمسهّلين. بعض الوثائق تستخدم PAYMENT-REQUIRED وPAYMENT-SIGNATURE وPAYMENT-RESPONSE، وأمثلة أقدم تستخدم X-PAYMENT. التدفق واحد؛ تحقق من الأسماء في مواصفة الإصدار والمسهّل الذي تدمجه.

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: ... }

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

research_mcp = MCPServerStreamableHttp(
    name="research-services",
    params={"url": "https://research-services.example.com/mcp"},
)
research_mcp_with_payments = withX402Client(
    research_mcp,
    wallet=agent_wallet,
    max_per_call_usdc=Decimal("0.10"),
    max_per_session_usdc=Decimal("10.00"),
)

x402_client = X402Client(wallet=agent_wallet)

@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."""
    response = await x402_client.get(url, max_payment_usdc=max_payment_usdc)
    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,
    )

هذه الاستيرادات الخاصة بـCloudflare وx402 client تعليمية في Python؛ الحزمة الحقيقية من جهة المشتري هي x402-client، واستدعاء حي يحتاج حساباً ممولاً ونقطة نهاية 402 حقيقية. x402 لا يضيف تقريباً بنية تحتية إلى harness: محفظة عقد ذكي، مفتاح في vault، وعميل يوقع ثم يعيد طلب HTTP.

حد المحفظة هو الأمان الذي يحميك

لا تتعامل مع x402 كأنك أعطيت الوكيل بطاقة ائتمان. الأمان الحقيقي هو حد الإنفاق على السلسلة في محفظة العقد الذكي، لا max_payment_usdc لكل طلب. محفظة hot بلا سقف يمكن أن تُستنزف بحلقة وكيل عالقة.

خلاصة المفهوم 10: x402 هو بروتوكول التسوية الجاهز لمدفوعات machine-to-machine الصغيرة. رمز 402، وترويسة دفع موقعة، وتدفق EIP-3009 تسوّي خلال ثانية إلى ثانيتين. memoization في Inngest يمنع الدفع المكرر عند retry، وحدود المحفظة على السلسلة هي الحماية الفعلية.

المفهوم 11: MPP، بروتوكول التسوية القائم على الجلسات

في سطر واحد: يسمح MPP للوكيل بفتح tab مسبق الدفع بسقف إنفاق، ثم بث دفعات صغيرة كثيرة داخله عبر عدة سكك حتى يغلقه.

MPP مبني من Stripe وTempo، وأعلن عنه في مارس 2026. ينافس x402 في الطبقة 4، لكنه يختلف فلسفياً: x402 stablecoin لكل طلب؛ MPP متعدد السكك ويدعم charge لمرة واحدة وsession لجلسة تدفقات كثيرة.

البعد	x402	MPP
تكرار التفويض	لكل طلب	لكل charge أو لكل session
شكل HTTP	402 مخصص وترويسات دفع	WWW-Authenticate / Authorization / Payment-Receipt
السكك	stablecoin فقط	Tempo stablecoin، Lightning، بطاقات، ACH
أفضل ملاءمة	API calls مفردة ومدفوعات صغيرة	اشتراكات، مؤسسات، وتدفقات تحتاج fallback fiat

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."""
    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,
    )
    ctx.context.setdefault("mpp_sessions", {})[service_id] = session.id
    return MPPSessionResult(
        session_id=session.id,
        status="active",
        expires_at=session.expires_at,
    )

stripe.MPPSession هنا واجهة تعليمية؛ ليست حالياً اسماً في Stripe Python SDK كما كتب. الحقيقة المهمة هي session lifecycle: تفويض سقف، استخدام محسوب، ثم إغلاق. يضيف MPP خطوة إعداد واحدة: تفعيل MPP في حساب Stripe. أما Tempo فيتعامل معه خادم MPP من Stripe، ولا يلمسه الوكيل مباشرة.

أكثر خطأ شائع: جلسات كبيرة أو طويلة أكثر من اللازم. سقف الجلسة هو حد خسارتك عند الخطأ. جلسة 5 دولارات لخمس دقائق أكثر أماناً من جلسة 50 دولاراً لساعة، إذا كان العمل المتوقع 30 استدعاء صغيراً.

خلاصة المفهوم 11: MPP هو جواب Stripe التسووي على x402، مضبوط للجلسات وmulti-rail. charge للمرة الواحدة وsession للبث المتكرر. الجلسات أرخص من توقيع كل طلب عند التكرار العالي، لكن يجب ضبط سقفها على حجم العمل المتوقع لا على الراحة.

الجزء 4: قواعد التركيب، متى تستخدم البروتوكولات معاً

المفهوم 12: أصغر حزمة دفع وكيلة قابلة للشحن

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

حالة الاستخدام	الطبقة 1: الاكتشاف	الطبقة 2: التفويض	الطبقة 3: التجارة	الطبقة 4: التسوية	لماذا هذا MVP
تسوق المستهلك	واجهة تسوق AI أو MCP catalog	ACP SPT أو AP2 في المجالات المنظمة	ACP	بطاقات عبر Stripe	المشترون يريدون chargeback؛ ACP + Stripe هو المسار الذي يشحن اليوم
وكيل يدفع لـAPI	MCP يدعم x402 أو Agent.market	توقيع EIP-3009	لا شيء	x402 على Base أو Solana	في machine-to-machine تنهار الطبقتان 2 و4؛ لا دورة شراء
مشتريات مؤسسة	A2A داخل شبكة الشركاء	AP2 Intent Mandate	ACP/UCP أو direct API	MPP للجلسات أو بطاقات للمرات المفردة	audit trail غير قابل للتجاوز
سوق multi-agent	A2A أو دليل وكلاء	AP2 + فحص سمعة ERC-8004	لا شيء	x402 غالباً، أو MPP إذا كانت Stripe موصولة	الثقة والدفع مطلوبان على الجانبين

الفخ هو توصيل ACP وAP2 وx402 وMPP دفعة واحدة "للمرونة". تحصل على أربعة أضعاف سطح التكامل ولا إجابة واضحة على "أي بروتوكول يعمل متى؟" اختر تركيباً واحداً، اشحنه، وأضف آخر فقط عندما تفرضه حالة استخدام ثانية.

خلاصة المفهوم 12: أصغر حزمة قابلة للشحن هي أصغر بروتوكولات تحقق قيمة. تسوق المستهلك: ACP + بطاقات. دفع APIs: x402 فقط. مشتريات المؤسسة: AP2 + ACP/UCP + MPP/بطاقات. سوق multi-agent: AP2 + ERC-8004 + x402.

المفهوم 13: متى تركب البروتوكولات ومتى تتنافس

في سطر واحد: البروتوكولات في طبقات مختلفة تركب؛ والبروتوكولات في الطبقة نفسها تستبدل بعضها.

تركيب عبر الطبقات	خريطة الطبقات	أين يشحن
AP2 + ACP	AP2 في التفويض، ACP في التجارة	المجالات المنظمة التي تحتاج تدقيقاً فوق ACP
AP2 + x402	AP2 في التفويض، x402 في التسوية	تدفقات crypto-native تحتاج audit عبر a2a-x402
ACP + x402	ACP في التجارة، x402 لتدفقات API فرعية	منصات هجينة تتضمن شراء مستهلك وإنفاق API
MCP + x402	MCP في الاكتشاف، x402 في التسوية	نمط Cloudflare للأدوات MCP المدفوعة

تنافس داخل طبقة	الطبقة	متى يفوز كل واحد
AP2 ضد ACP SPT ضد TAP	2	AP2 للتدقيق، ACP SPT لتدفقات Stripe، TAP للهوية فقط
ACP ضد UCP	3	ACP للوصول عبر ChatGPT، وUCP للوصول عبر Gemini
x402 ضد MPP	4	x402 للمدفوعات الصغيرة المفردة، MPP للجلسات والاشتراكات وmulti-rail

اختبار القرار: هل البروتوكولان في الطبقة نفسها؟ إذا نعم، اختر واحداً أو ادفع كلفة دعم الاثنين لتدفقات فرعية مختلفة. إذا لا، فغالباً يركبان.

خلاصة المفهوم 13: عبر الطبقات تركب البروتوكولات؛ داخل الطبقة تتنافس. AP2 + x402 تركيب، أما x402 ضد MPP فقرار طبقة تسوية.

المفهوم 14: الكلفة والكمون وما يفرض الاختيار

في سطر واحد: حجم العملية والانتظار المقبول يقرران بروتوكول التسوية، لأن رسوم البطاقات تسحق المدفوعات الصغيرة وcheckout البطيء يكسر الحلقات الضيقة.

التركيب	الكلفة النموذجية لكل عملية	الكمون النموذجي
ACP + بطاقات	2.9% + 0.30 دولار	5 إلى 30 ثانية
ACP + جلسات MPP	2.9% على البطاقات أو نحو 0.5% على Tempo stablecoin	1 إلى 3 ثوان لكل metered call
AP2 + x402	gas أقل من سنت، بلا رسوم بروتوكول	2 إلى 5 ثوان، مع إضافة توقيع mandate
x402 فقط	gas أقل من سنت، بلا رسوم بروتوكول	1 إلى 2 ثانية
MPP sessions فقط	قريب من الصفر على Tempo stablecoin؛ رسوم Stripe على البطاقات	50 إلى 500 ms داخل جلسة نشطة

إذا تجاوزت الرسوم 5% من قيمة العملية فهي مشكلة. استدعاء API بقيمة 0.05 دولار يدفع 0.30 دولار رسوم بطاقة لا معنى له؛ استخدم x402 أو MPP stablecoin. قميص بقيمة 50 دولاراً يستحق chargeback cover. حد الدولار الذي تتوقف عنده البطاقات عن المعنى يقع تقريباً بين 5 و10 دولارات.

ما قيمة العملية؟
├── دون الدولار: x402 أو MPP sessions
├── 1 إلى 10 دولارات: x402 أو MPP، مع AP2 إذا احتجت audit
├── 10 إلى 1000 دولار: ACP + بطاقات
└── أكثر من 1000 دولار: AP2 + ACP/UCP + MPP أو سكك بنكية

ما ميزانية الكمون؟
├── أقل من ثانية: MPP sessions على Tempo أو x402 على Base
├── 1 إلى 5 ثوان: x402 أو MPP أو AP2 mandates موقعة مسبقاً
└── أكثر من 5 ثوان: checkout كامل عبر ACP مقبول

خلاصة المفهوم 14: دع الكلفة والكمون يفرضان التركيب. البطاقات تعطي chargeback بكلفة أعلى، وstablecoin رخيص لكنه يحتاج plumbing خاصاً. تحت 5-10 دولارات تفوز سكك الآلة غالباً.

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

القرار 1: وكيل تسوق للمستهلك

حالة الاستخدام: وكيل يساعد الناس على التسوق لدى تجار ACP مثل Walmart وEtsy وبائعي Shopify. يطلب المستخدم ما يريد؛ يبحث الوكيل في الكتالوجات، يعرض الخيارات، ويكمل checkout بعد التأكيد. القيم 5 إلى 500 دولار، والردود وchargebacks مطلوبة.

• الاكتشاف. واجهة تسوق AI أو كتالوجات MCP؛ عملياً واجهة AI لأنها تجمع التجار.
• التفويض. ACP SPT محدود بتاجر ومبلغ ونافذة زمنية.
• التجارة. ACP لأن السلة والcheckout والتنفيذ والردود مطلوبة.
• التسوية. بطاقات عبر Stripe، لأن chargeback cover يستحق الرسوم.

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

أغلب فشل إنتاجي: cart mismatch. العلاج: اطلب تأكيد المستخدم قبل إصدار SPT، وقس cart accuracy، واضبط التعليمات إذا هبطت دون 95%.

القرار 2: وكيل بحث يدفع لواجهات API

حالة الاستخدام: وكيل بحث يدفع لمصادر بيانات: أخبار، تغذيات مالية، بحث متخصص. يكتشف APIs مدفوعة وقت التشغيل، يوازن الكلفة والقيمة، ويدفع لكل استدعاء. قيم من 0.001 إلى 0.50 دولار، بلا إنسان في الحلقة بعد البداية، ولا دورة تجارة.

• الاكتشاف. Agent.market مع MCP-via-Cloudflare.
• التفويض والتسوية. ينهاران في توقيع EIP-3009 عبر x402، مع حدود محفظة وحاجز أداة في SDK.
• التجارة. لا شيء؛ API مباشرة.

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

أغلب فشل إنتاجي: إنفاق runaway بسبب حلقة عالقة. العلاج: حدود محفظة على السلسلة، وحواجز إنفاق في SDK، وdedup cache حتى لا تدفع مرتين للبيانات نفسها.

القرار 3: وكيل مشتريات مؤسسة

حالة الاستخدام: مؤسسة منظمة تفوض الوكيل لشراء 50 لوحة مفاتيح من موردين معتمدين تحت 5000 دولار. audit trail مطلوب قانونياً.

• الاكتشاف. MCP داخلي للموردين المعتمدين.
• التفويض. AP2 Intent ثم Cart ثم Payment Mandates.
• التجارة. ACP للموردين الداعمين، وdirect B2B APIs للبقية.
• التسوية. MPP للجلسات المتكررة، وبطاقات عبر ACP للشراء المفرد.

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

أغلب فشل إنتاجي: نطاق Intent Mandate لا يطابق السلة. العلاج: تحقق من نطاق mandate قبل أن يبدأ الوكيل التسوق.

القرار 4: سوق متعدد الوكلاء

حالة الاستخدام: منصة يستأجر فيها وكيل وكلاء آخرين. Agent A يحتاج بحثاً؛ Agent B يبيع البحث كخدمة x402. لا توجد ثقة مسبقة، والدفع crypto-native بلا بطاقات.

• الاكتشاف. A2A.
• التفويض. AP2 mandates لإثبات موافقة المستخدم، وERC-8004 لفحص سمعة الطرف الآخر.
• التجارة. لا شيء؛ طلب A2A مباشر ونتيجة.
• التسوية. x402 عبر امتداد a2a-x402.

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 يمكن تضخيمها بعمليات صغيرة ناجحة. العلاج: اجمع السمعة مع هوية المشغل، وحجم العمليات، وتاريخ النزاعات، ومراجعة بشرية فوق مبلغ معين.

القرار 5: حزمة بلا Stripe ولا OpenAI

لإثبات أن الإطار لا يعتمد على مكتبة واحدة، يعيد هذا القرار بناء وكيل البحث الذي يدفع لـAPIs بحزمة مختلفة: Google ADK للتشغيل، ومحفظة عقد ذكي من Coinbase للهوية على السلسلة، وAP2 mandates للتفويض، وx402 مباشر للتسوية.

from google.adk import Agent
from google.adk.tools import function_tool
from coinbase_agentkit import AgentKit, SmartWalletProvider
from decimal import Decimal
from datetime import datetime, timedelta

from .models import X402PaymentResult, PaymentToolResult, DiscoveryResult

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)

@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."""
    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,
    )

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",
    tools=[search_agent_directory, x402_paid_fetch],
)

OpenAI + Stripe	Google ADK + Coinbase	المفهوم نفسه
from agents import Agent, function_tool	from google.adk import Agent وfunction_tool	runtime الوكيل
RunContextWrapper	context={...} في run_async	حالة لكل تشغيل
حدود عبر Stripe customer	SmartWalletProvider(spend_limits={...})	حدود إنفاق chain-native
tool_input_guardrail	فحص داخل الأداة + حدود المحفظة	تحقق قبل التنفيذ
Runner.run(agent, ...)	agent.run_async(...)	تشغيل الوكيل

خلاصة القرار 5: بنية الطبقات الأربع ليست قصة Stripe وOpenAI متخفية. الاكتشاف، التفويض، التجارة، التسوية، اختر بروتوكولاً لكل طبقة وبرره بحالة الاستخدام: هذا ينجو من تبديل المكتبات.

الجزء 6: مخاوف الإنتاج، ما يقتلك عند التشغيل الحقيقي

مسار القارئ

إذا كنت تقرأ للفهم لا للشحن، يمكنك skim هذا الجزء. إذا كنت تبني هذا فعلاً، فهذه المفاهيم هي الفرق بين نظام يعمل ونظام يستنزف محفظة.

المفهوم 15: فرض حدود الإنفاق على ثلاثة مستويات

في سطر واحد: أوقف الوكيل عن الإفراط في الإنفاق بفرض الحد في ثلاثة أماكن مستقلة، حتى يمسك مكانان آخران خطأ المكان الأول.

الفشل الأخطر بسيط: ينفق الوكيل أكثر مما سمح له. كل بروتوكول لديه سقفه، لكن لا يكفي سقف واحد بمفرده.

المستوى 1: حدود المحفظة وطريقة الدفع. هذا هو السقف الذي يحميك فعلاً. محفظة العقد الذكي للوكيل في x402، أو حساب Stripe في ACP وMPP، تحمل حدوداً تفرضها البنية التحتية مهما فعل كود الوكيل.

from decimal import Decimal

wallet_spend_limits = {
    "max_per_transaction_usdc": Decimal("10.00"),
    "max_per_day_usdc": Decimal("100.00"),
    "max_per_merchant_usdc": Decimal("50.00"),
}
agent_wallet = SmartContractWallet.deploy(
    owner=user_did,
    spend_limits=wallet_spend_limits,
    chain="eip155:8453",
)

stripe.Customer.modify(
    user_session.stripe_customer_id,
    metadata={
        "max_per_session_usd": "500",
        "max_per_day_usd": "2000",
    },
)

المستوى 2: حواجز أدوات SDK. يعمل tool_input_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
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."""
    args = json.loads(data.context.tool_arguments or "{}")
    requested = Decimal(str(args.get("max_total_usd") or args.get("max_payment_usdc") or 0))
    ctx = data.context.context
    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
def verify_receipt_integrity(data: ToolOutputGuardrailData) -> ToolGuardrailFunctionOutput:
    output = data.output or {}
    if isinstance(output, dict) and "amount_paid_usdc" in output:
        pass
    return ToolGuardrailFunctionOutput.allow()

المستوى 3: قواعد التطبيق والعمل. هنا تعيش قواعد المستخدمين: سقف يومي، وسقف لكل تاجر، وسقف لكل فئة.

from decimal import Decimal

class UserSession:
    def can_spend(self, amount_usd: Decimal, merchant_id: str) -> bool:
        if self.today_spend_usd + amount_usd > self.daily_cap_usd:
            return False
        merchant_cap = self._merchant_cap_for(merchant_id)
        if self.merchant_spend_usd[merchant_id] + amount_usd > merchant_cap:
            return False
        category = self._category_for(merchant_id)
        if self.category_spend_usd[category] + amount_usd > self.category_caps[category]:
            return False
        return True

خلاصة المفهوم 15: افرض حدود الإنفاق في ثلاثة أماكن: المحفظة أو طريقة الدفع، وtool_input_guardrail في SDK، ومنطق التطبيق. لا تستخدم output_guardrail للتحكم في الإنفاق؛ يعمل بعد فوات الأوان.

المفهوم 16: نظافة هوية الوكيل: المفاتيح والمحافظ وسجلات التدقيق

في سطر واحد: مفتاح توقيع الوكيل هو الفاصل الوحيد بين إنفاق مفوض واحتيال، لذلك تحميه، وتفصله لكل وكيل، وتدوره، وتسجل كل إنفاق في تخزين متين.

أربع عادات تحمي الهوية:

1. فصل المحافظ لكل فئة وكيل. لا تشارك مفتاح توقيع واحد بين وكيل تسوق ووكيل مشتريات ووكيل بحث.
2. تدوير المفاتيح. كل 90 يوماً كخط أساس، وفوراً عند خروج عامل، أو تغيير deployment يمس سطح التوقيع، أو ظهور سلوك مريب.
3. Audit logs تصمد بعد crash. كل SPT، وكل mandate، وكل توقيع x402، وكل جلسة MPP تسجل إلى تخزين متين قبل إكمال الفعل.
4. Distributed traces. audit log يقول ماذا نجح؛ traces تقول ماذا حدث، بما في ذلك retries والتعطلات. تحتاج الاثنين.

def get_signing_key(agent_class: str) -> SigningKey:
    return azure_key_vault.get_latest_version(
        secret_name=f"agent-wallet-signing-key-{agent_class}",
    )

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":
    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_status(Status(StatusCode.OK))
            return result
        except Exception as e:
            span.set_status(Status(StatusCode.ERROR, str(e)))
            span.record_exception(e)
            raise

لا تعامل عنوان المحفظة كهوية الوكيل؛ العنوان عام. مفتاح التوقيع الخاص هو الهوية. ضعه في key vault، لا في env vars ولا في المصدر.

خلاصة المفهوم 16: هوية الوكيل مشفرة. احم مفاتيح التوقيع، وافصل المحافظ، ودوّر المفاتيح، واكتب audit logs إلى تخزين متين، واجعل trace ID واحداً يغطي العملية كلها.

المفهوم 17: النزاعات والردود عبر البروتوكولات الأربعة

في سطر واحد: يعالج كل بروتوكول النزاعات والردود بشكل مختلف، وغالباً يكون نموذج النزاع المطلوب أقوى عامل يحدد التركيب.

ACP: النزاعات عبر شبكات البطاقات. لأن التاجر يبقى merchant of record، تعمل مسارات chargeback والاسترداد الحالية. هذه أكبر ميزة عملية لـACP.

AP2: النزاع يحل عبر audit trail. سلسلة mandates دليل على ما فوّضه المستخدم. لا تستبدل مسار النزاع الخاص بالسكة، لكنها تضيف الدليل.

x402: لا آلية نزاع رسمية. المدفوعات غير قابلة للاسترداد بالتصميم، وهذا مناسب لـ0.001 دولار API call، وخاطئ لأي حالة يتوقع فيها المشتري refund.

MPP: النزاعات عبر Stripe. جلسات MPP على البطاقات ترث dispute machinery من Stripe، والجلسات على Tempo أو Lightning تمر عبر حل النزاع من جهة البائع لدى Stripe.

خلاصة المفهوم 17: ACP يرث chargebacks، وAP2 يقدم سلسلة mandates كدليل قانوني، وx402 غير قابل للاسترداد، وMPP يرث آليات Stripe عبر السكك. نموذج النزاع الذي تحتاجه حالة الاستخدام قد يفرض البروتوكول أكثر من الكلفة والكمون.

المفهوم 18: FastAPI وInngest webhooks لإغلاق الحلقة

في سطر واحد: بعض أحداث الدفع تصل في وقتها الخاص، مثل النزاعات وتوقيعات mandates وطلبات الدفع من جهة البائع، لذلك تحتاج FastAPI handler رقيقاً يلتقطها وInngest event يحمل العمل إلى workflow متين.

ثلاثة أنماط إنتاجية:

1. Stripe webhook إلى Inngest. يصل charge.dispute.created بعد دقائق أو بعد 60 يوماً. يتحقق FastAPI من التوقيع، يرسل Inngest event، ويعيد ACK سريعاً. تعمل business logic داخل Inngest لا داخل webhook.
2. AP2 mandate callback. يوقع المستخدم على هاتفه، يرسل callback، يتحقق FastAPI من التوقيع، ويحرك step.wait_for_event كان معلقاً.
3. x402 seller-side middleware. عندما تعرض API مدفوعة، يعيد middleware 402 Payment Required ويتحقق من ترويسات الدفع قبل تشغيل business logic.

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

    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,
            ),
        ])
    return {"received": True, "event_id": event.id}

يبقى FastAPI handler رقيقاً: تحقق، أطلق event، أعد ACK. الوظيفة المتينة في Inngest تتعامل مع retries وidempotency وتشغيل الوكيل. هذا مهم لأن Stripe يريد 2xx خلال نحو خمس ثوان، وتشغيل وكيل قد يأخذ 30 ثانية أو أكثر.

خلاصة المفهوم 18: تجارة الوكلاء ثنائية الاتجاه. النزاعات والتوقيعات والردود وطلبات البائع تصل عبر webhooks. FastAPI حدود HTTP، وInngest جسر المتانة، والوكيل يعمل داخل workflow لا داخل handler.

الجزء 7: الخاتمة، ما كانت الدورة تعلمه فعلاً

المفهوم 19: انضباط التركيب الطبقي

في سطر واحد: البروتوكولات الأربعة طبقات لا بدائل. عملك أن تقرأ حالة الاستخدام، تكسرها إلى أربع طبقات، تختار البروتوكول الصحيح في كل طبقة، وتبرر الاختيار بقيود الحالة الحقيقية.

لن تثبت أسماء البروتوكولات كما هي إلى الأبد. قد يتغير ACP، وقد يندمج x402 في حزمة أخرى، وقد تحصل MPP على اعتماد أوسع، وقد تظهر طبقة تفويض جديدة. لكن الطبقات الأربع ستبقى: الاكتشاف، والتفويض، والتجارة، والتسوية. إذا فكرت من الطبقات، ستبقى قراراتك صحيحة حتى عندما تتغير الأسماء.

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

الطبقات الأربع

1. الاكتشاف: ما المتاح؟ MCP، وA2A، والأدلة، وواجهات التسوق.
2. الهوية والتفويض: هل يُسمح للوكيل بالإنفاق؟ AP2، وACP SPT، وTAP، وERC-8004.
3. التجارة: هل توجد دورة شراء كاملة؟ ACP، وUCP، أو لا شيء في API مباشر.
4. التسوية: أين يتحرك المال؟ x402، وMPP، والبطاقات، والبنك، وLightning.

التركيبات canonical الأربعة

• تسوق المستهلك: واجهة AI + ACP SPT + ACP + بطاقات.
• وكيل يدفع لـAPI: MCP/دليل + EIP-3009 + لا تجارة + x402.
• مشتريات مؤسسة: MCP داخلي + AP2 + ACP/UCP/direct API + MPP/بطاقات.
• سوق multi-agent: A2A + AP2/ERC-8004 + لا تجارة + x402.

فرض حدود الإنفاق

• المستوى 1: حدود المحفظة أو طريقة الدفع.
• المستوى 2: tool_input_guardrail في SDK.
• المستوى 3: قواعد التطبيق والعمل.

العتبة الاقتصادية

• تحت 5 دولارات: x402 أو MPP stablecoin.
• 5 إلى 1000 دولار: ACP + بطاقات غالباً.
• فوق 1000 دولار: AP2 + MPP أو سكك بنكية.

نموذج النزاعات

• تحتاج chargeback: أدرج سكك بطاقات.
• تحتاج دليل audit: أدرج AP2.
• لا تحتاج نزاعاً: x402 المباشر غالباً يكفي.

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

• حدود wallet/payment-method على مستوى البنية التحتية
• tool_input_guardrail على كل أداة تفويض دفع
• قواعد application/business logic لحدود المستخدم والفئة والتاجر
• مفاتيح التوقيع في key vault، لا في env vars
• فصل محافظ لكل فئة وكيل
• جدول تدوير مفاتيح محدد
• audit logs إلى تخزين متين مستقل عن runtime
• traces عبر SDK وhttpx وInngest وFastAPI، trace ID واحد لكل عملية
• Pydantic models عند كل حد، وDecimal للمال دائماً
• Stripe webhook handler يتحقق من التوقيع ويرسل Inngest event
• AP2 callback يتحقق من التوقيع ويستأنف step.wait_for_event
• إذا كنت تعرض APIs مدفوعة: x402 seller-side middleware لكل route
• idempotency key في كل Inngest function يحركها webhook
• آلية النزاع والرد موثقة لكل بروتوكول
• human-in-the-loop confirmation gate لأول 30 يوم إنتاج
• قياس cart accuracy قبل تخفيف بوابة التأكيد

مرجع سريع: شجرة القرار المختصرة

1. ماذا يشتري الوكيل؟
   ├── سلع تجزئة لمستخدم: نمط القرار 1 (ACP + بطاقات)
   ├── وصول API لنفسه: نمط القرار 2 (x402 فقط)
   ├── سلع/خدمات موردين لمؤسسة: نمط القرار 3 (AP2 + تركيب)
   └── عمل من وكيل آخر: نمط القرار 4 (AP2 + ERC-8004 + x402)

2. ما قيمة العملية؟
   ├── < $5: التسوية = x402 أو MPP stablecoin
   ├── $5-$1,000: التسوية = بطاقات عبر ACP/MPP
   └── > $1,000: التسوية = MPP sessions أو سكك بنكية

3. ما نموذج النزاع؟
   ├── تحتاج chargeback: يجب إدراج سكك بطاقات
   ├── تحتاج دليل audit: يجب إدراج AP2 في الطبقة 2
   └── لا هذا ولا ذاك: x402 / direct rail يكفي

4. ما ميزانية الكمون؟
   ├── < 1 ثانية: سكك stablecoin فقط
   ├── 1-5 ثوان: x402 أو MPP أو AP2 mandates موقعة مسبقاً
   └── > 5 ثوان: checkout كامل عبر ACP يعمل

5. ركّب: اختر بروتوكولاً واحداً من كل طبقة، مبرراً بالقيود أعلاه.

مراجعة في 10 دقائق: المفاهيم التسعة عشر في جملة واحدة

1. افترضت أنظمة الدفع أن إنساناً يضغط buy؛ يكسر الوكلاء ذلك بالهوية والسلوك والنزاعات.
2. لا يحل بروتوكول واحد كل شيء؛ البروتوكولات تتخصص حسب الطبقة.
3. OpenAI Agents SDK هو العميل الموحد؛ كل بروتوكول يصبح أداة.
4. الاكتشاف يجيب "ما المتاح؟" عبر MCP أو A2A أو الأدلة أو واجهات التسوق.
5. التفويض يثبت موافقة الإنسان وهوية الوكيل.
6. التجارة تدير السلة والcheckout والتنفيذ والنزاع والرد.
7. التسوية هي انتقال المال، ويختارها الاقتصاد والكمون.
8. ACP بروتوكول التجارة الجاهز لتسوق المستهلك.
9. AP2 طبقة تفويض قائمة على mandates غير قابلة للإنكار.
10. x402 تسوية HTTP لمدفوعات machine-to-machine الصغيرة.
11. MPP تسوية مبنية على جلسات متعددة السكك.
12. MVP هو أصغر تركيب يخدم حالة استخدام واحدة.
13. البروتوكولات تركب عبر الطبقات وتتنافس داخل الطبقة.
14. الكلفة والكمون يفرضان سكة التسوية.
15. حدود الإنفاق تحتاج ثلاثة مستويات مستقلة.
16. هوية الوكيل مفتاح توقيع؛ احمه وافصله ودوّره وسجله.
17. نموذج النزاع قد يفرض البروتوكول أكثر من أي عامل آخر.
18. webhooks وcallbacks تحتاج FastAPI رقيقاً وInngest متيناً.
19. الطبقات ستبقى حتى إذا تغيرت أسماء البروتوكولات.

قالب مراجعة التصميم

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

1. ما حالة الاستخدام الأساسية؟ إذا كانت "عدة حالات"، فما الأولى؟
2. امش الطبقات الأربع صراحة: الاكتشاف، التفويض، التجارة، التسوية.
3. برر اختيار كل طبقة مقابل حالة الاستخدام.
4. هل يوجد تداخل بروتوكولات داخل طبقة واحدة؟ إذا نعم، ما حالة الاستخدام التي تبرر التعقيد؟

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

5. ما توزيع قيمة العمليات؟
6. ما ميزانية الكمون؟
7. ما الكلفة لكل عملية عند الحجم المتوقع؟

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

8. هل حدود الإنفاق مفروضة في المستويات الثلاثة؟
9. هل نظافة الهوية موجودة: محافظ منفصلة، تدوير مفاتيح، audit logs، traces؟
10. هل آلية النزاع والرد تطابق ما سيحدث فعلاً؟
11. أين يعيش durable execution مثل Inngest؟
12. أين توجد بوابات human-in-the-loop؟

أسئلة webhooks وcallbacks

13. هل Stripe webhook handler موجود ورقيق؟
14. هل AP2 mandate callback يتحقق من توقيع المستخدم؟
15. إذا كنت تعرض APIs مدفوعة، هل x402 middleware مضبوط لكل route؟
16. هل idempotency keys موجودة لكل function يحركها webhook؟
17. هل توجد Pydantic models عند كل حد وDecimal للمال؟

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

18. ما أكثر فشل إنتاجي احتمالاً؟
19. ما التخفيف المحدد، وهل هو في التصميم أم مجرد أمل في أن البروتوكول سيتعامل معه؟

أسئلة جاهزية المسار

20. أي مسار تعلم يعمل منه الفريق: قارئ، مبتدئ، متوسط، متقدم؟
21. ما خطة rollback إذا أساء الوكيل التصرف: kill switch للمحفظة، revocation لـSPT، تعطيل الوكيل على مستوى SDK؟

المراجع

مصادر أولية للبروتوكولات الأربعة. فضّلها على التعليقات الثانوية لأن المواصفات تتحرك أسرع من المقالات عنها.

ACP (Agentic Commerce Protocol)

• مستودع المواصفة: github.com/agentic-commerce-protocol/agentic-commerce-protocol (Apache 2.0)
• موقع المطورين: agenticcommerce.dev
• القائمان على الصيانة: OpenAI وStripe
• وثائق Stripe integration: 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 شريكاً
• مستودع امتداد 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
• تكامل Cloudflare OpenAI Agents SDK: developers.cloudflare.com/agents/x402
• دليل الاعتماد: agent.market

MPP (Machine Payments Protocol)

• موقع المواصفة: mpp.dev
• المطوران المشاركان: Stripe وTempo
• إعلان Stripe: stripe.com/blog/machine-payments-protocol
• تاريخ الإطلاق: 18 مارس 2026

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

• A2A: github.com/google-a2a/A2A
• MCP: modelcontextprotocol.io
• UCP: بروتوكول Google النظير لـACP لواجهات Google shopping
• TAP: بروتوكول Visa وCloudflare لإثبات الهوية
• ERC-8004: معيار ثقة على السلسلة لمعاملات multi-agent

OpenAI Agents SDK

• Python SDK: pip install openai-agents
• الوثائق: openai.github.io/openai-agents-python
• JavaScript/TypeScript SDK: github.com/openai/openai-agents-js

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

• دورة Build AI Agents: أساسيات OpenAI Agents SDK
• دورة Production Worker: Inngest كغلاف تشغيل متين
• دورة Eval-Driven Development: اختبار وتقييم الوكلاء
• دورة Choosing Agentic Architectures: أي نمط وكيلي يناسب أي حالة استخدام
• دورة Deploying Agents: harness السحابي عبر Azure Container Apps وNeon وCloudflare

أدوات التشغيل والعقود

• Inngest: inngest.com
• FastAPI: fastapi.tiangolo.com
• Pydantic: pydantic.dev
• OpenTelemetry: opentelemetry.io
• httpx: python-httpx.org
• Azure Key Vault: حيث تعيش مفاتيح التوقيع في الإنتاج
• Stripe webhooks documentation: stripe.com/docs/webhooks

---

أصبحت لديك الآن الحزمة كاملة: الطبقات الأربع، والبروتوكولات الأربعة، وقواعد التركيب، وخمسة قرارات عملية، ومخاوف الإنتاج التي تحدد هل يصمد النظام، ومرجع صفحة واحدة. ستستمر البروتوكولات في الحركة. أما انضباط الطبقات الأربع فلن يتحرك. ابنِ من الطبقات، وستبقى على الطريق الصحيح حتى عندما تتغير أسماء البروتوكولات.