Payment-Enabled Agents: ACP, AP2, x402, और Production में MPP
चार protocols पर एक क्रैश कोर्स जो OpenAI Agents SDK सिस्टम को पैसा खर्च करने देता है: merchants पर, APIs के मुकाबले, अन्य agents के साथ, खुली अर्थव्यवस्था में। उन इंजीनियरों के लिए जिन्होंने agents भेज दिया है और अब उन्हें भुगतान करने की आवश्यकता है।
19 अवधारणाएँ। 5 निर्णय. 3 चित्र. चार सीखने वाले ट्रैक। रीडर ट्रैक 2-3 घंटे का शुद्ध पढ़ने वाला है: चार-परत stack, प्रत्येक protocol गहराई में, composition नियम, कोई सेटअप नहीं। शुरुआती, मध्यवर्ती और उन्नत ट्रैक agents से protocols तक वायरिंग करने, composition को टिकाऊ रूप से चलाने और identity, खर्च और विवादों को प्रबंधित करने में हाथों-हाथ गहराई बढ़ाते हैं। वे लगभग 1 दिन, 2-3 दिन और 4-5 दिन चलते हैं। ईमानदार अनुमान: इसे पढ़ने के लिए 2-3 घंटे, stack को काम करने की आदत बनाने के लिए एक टीम को 4-5 दिन।भाग 5 में decision lab से पहले अपना ट्रैक चुनें।
यह एक विचार है जिस पर यह पाठ्यक्रम बनाया गया है: चार protocols प्रतिद्वंद्वी नहीं हैं। वे परतें हैं। अधिकांश लेख पूछते हैं "ACP या x402?" यह प्रश्न एक गलती है कि ये protocols किस प्रकार की चीज़ हैं। 2026 में एक वास्तविक सिस्टम शिपिंग उनमें से कई का एक साथ उपयोग करता है, क्योंकि प्रत्येक agent-commerce समस्या का एक अलग layer हल करता है। एक consumer shopping agent निपटान में commerce layer और card rails पर ACP का उपयोग करता है। एक API-paying agent दोनों में x402 का उपयोग करता है, क्योंकि machine-to-machine micropayments के लिए वे दो layers एक में ढह जाते हैं। एक enterprise procurement agent यह साबित करने के लिए AP2 mandates का उपयोग करता है कि मानव ने खर्च को अधिकृत किया है, फिर निपटान में Stripe MPP। आप उपयोग के मामले को पढ़ना और सही रचना तक पहुंचना सीखेंगे।
इस कोर्स में कुछ भाई-बहनों के नाम शामिल हैं: Build AI Agents क्रैश कोर्स (SDK मूल बातें), Production Worker क्रैश कोर्स (Inngest के साथ agents को स्थायी रूप से चलाना), Eval-Driven Development क्रैश कोर्स, और Choosing Agentic Architectures क्रैश कोर्स। आप इसे उनके बिना भी पढ़ सकते हैं। चार protocols, layering, SDK code, और निर्णय अनुशासन सभी अपने आप पर खड़े हैं। एक चीज़ जो मदद करती है: भाग 3 code मानता है कि आप Agent, Runner.run(), और @function_tool पढ़ सकते हैं। यदि वे नए हैं, तो पहले Build AI Agents क्रैश कोर्स या OpenAI Agents SDK docs पर जाएं, फिर वापस आएं।
यदि आप किसी भिन्न stack पर हैं तो प्रत्येक protocol मानचित्र क्या दर्शाता है?
यदि आप OpenAI Agents SDK प्लस Stripe, Coinbase, और Cloudflare पर नहीं हैं, तो यह तालिका प्रत्येक संदर्भ कार्यान्वयन को सामान्य विकल्पों में मैप करती है। protocol specs स्टैक-अज्ञेयवादी हैं; केवल primitive नाम भिन्न हैं।
| Protocol | प्राथमिक संदर्भ SDK (2026) | सामान्य विकल्प | लाइसेंस/शासन |
|---|---|---|---|
| ACP (Agentic Commerce Protocol) | Stripe SDK (stripe) प्लस OpenAI Agents SDK; PayPal ACP server tools; Worldpay क्रेडेंशियल | Adyen ACP, Shopify-नेटिव checkout API | Apache 2.0, OpenAI प्लस Stripe और github.com/agentic-commerce-protocol/agentic-commerce-protocol |
| AP2 (Agent Payments Protocol) | Google ADK प्लस Python, TypeScript, Kotlin, Go में संदर्भ कार्यान्वयन | LangGraph प्लस कस्टम mandate signing, AutoGen प्लस a2a-x402 | Apache 2.0, Google प्लस github.com/google-agentic-commerce/AP2 पर 60+ भागीदार |
| x402 | x402-client (Python), @x402/client (JS/TS), Coinbase Developer Platform, Cloudflare withX402Client, AgentPay MCP | प्रत्यक्ष EIP-3009 कार्यान्वयन; Lobster.cash; Crossmint agent wallets | Apache 2.0, Coinbase द्वारा निर्मित, अब Linux Foundation के x402 फाउंडेशन के अंतर्गत |
| MPP (Machine Payments Protocol) | Stripe PaymentIntents प्लस MPP एक्सटेंशन; Tempo blockchain SDK | प्रत्यक्ष Lightning Network; Tempo देशी SDK | Apache 2.0, Stripe प्लस Tempo; specs पर mpp.dev |
| A2A (Agent2Agent, layer AP2 विस्तारित) | Google ADK | कस्टम A2A कार्यान्वयन | Apache 2.0, Google प्लस Linux Foundation |
| MCP (Model Context Protocol, discovery layer) | Anthropic MCP servers और ग्राहक; openai-agents MCP समर्थन | LangChain MCP | MIT, Anthropic |
तालिका का उपयोग करने के लिए: जब पाठ्यक्रम कहता है "agent के @function_tool को Stripe ACP endpoint पर तार दें" और आप Adyen प्लस LangGraph पर हैं, तो इसे "तार समकक्ष LangGraph" के रूप में पढ़ें tool से Adyen ACP समापन बिंदु।" तर्क वही है; नाम बदल जाते हैं. आपको केवल इस पाठ्यक्रम को पढ़ने के लिए Stripe stack सीखने की आवश्यकता नहीं है। primitives को मैप करें, framework का पालन करें, इसे अपने स्टैक पर लागू करें।
शब्दावली
📖 इस पाठ्यक्रम में जिन शब्दों का उपयोग किया गया है, उन्हें पहले पढ़ें और बाद में देखें
चार शीर्षक protocols
- ACP (Agentic Commerce Protocol). consumer-shopping protocol, OpenAI और Stripe द्वारा निर्मित। यह नियंत्रित करता है कि एक agent किसी व्यक्ति की ओर से वास्तविक merchant पर checkout को कैसे पूरा करता है। पॉवर्स ChatGPT त्वरित checkout। अधिकतर commerce परत पर रहता है। Apache 2.0.
- AP2 (Agent Payments Protocol). authorization protocol, Google द्वारा 60+ भागीदारों के साथ बनाया गया। यह signed "mandates" का उत्पादन करता है जो साबित करता है कि एक इंसान ने agent को खर्च करने की अनुमति दी है। यह स्वयं धन को स्थानांतरित नहीं करता है; यह साबित करता है कि खर्च अधिकृत था। Apache 2.0.
- x402. HTTP-नेटिव settlement protocol, Coinbase द्वारा निर्मित और अब Linux फाउंडेशन द्वारा शासित है। यह अप्रयुक्त HTTP 402 "Payment Required" status code को पुनर्जीवित करता है ताकि एक agent एक API कॉल के लिए एक stablecoin के साथ एक से दो सेकंड में भुगतान कर सके। Apache 2.0.
- MPP (Machine Payments Protocol). Stripe और Tempo का settlement protocol। इसकी चाल "session" है: agent एक खर्च सीमा को पूर्व-अनुमोदित करता है, फिर इसके विरुद्ध कई छोटे भुगतान स्ट्रीम करता है। Multi-rail (stablecoin, Lightning, कार्ड)। Apache 2.0.
layers (पूरे पाठ्यक्रम की रीढ़)
- Discovery परत। layer जहां agent पाता है कि वह क्या खरीद सकता है। MCP servers, A2A, agent directories, या AI shopping सतहों द्वारा उत्तर दिया गया। प्रश्न: "क्या उपलब्ध है?"
- Authorization layer (Identity और Authorization भी)। layer जो पैसे के स्थानांतरण से पहले दो चीजें साबित करता है: मानव ने इस खर्च की अनुमति दी, और agent वह है जो वह होने का दावा करता है। प्रश्न: "क्या मुझे इसे खर्च करने की अनुमति है?"
- Commerce परत। layer जो पूरी खरीदारी चलाता है: cart, checkout, fulfillment, dispute, refund। प्रश्न: "संपूर्ण purchase lifecycle क्या है?" सादे API कॉल के लिए पूरी तरह से छोड़ दिया गया।
- Settlement परत। layer जहां पैसा वास्तव में हाथ बदलता है। प्रश्न: "पैसा वास्तव में कहाँ जाता है?"
- Settlement rail (या rail)। वास्तविक पाइप जिसके माध्यम से पैसा यात्रा करता है: कार्ड नेटवर्क (Visa/Mastercard Stripe के माध्यम से), stablecoins एक blockchain पर, बैंक हस्तांतरण (ACH/SEPA), या Lightning। "एक rail चुनें" का अर्थ है "चुनें कि पैसा कैसे चलता है।"
Authorization primitives
- Mandate (AP2). एक signed डिजिटल प्रमाण कि एक मानव ने एक विशिष्ट प्रकार के खर्च को अधिकृत किया है। AP2 में तीन हैं: इरादा, Cart, और भुगतान (नीचे)। वे मिलकर एक श्रृंखला बनाते हैं जिसका आप बाद में ऑडिट कर सकते हैं।
- आशय अधिदेश। agent शुरू होने से पहले उपयोगकर्ता द्वारा पहला mandate, signed: कार्य के नियम। उदाहरण: "120 डॉलर से कम में जूते खरीदें।" यह सीमा निर्धारित करता है कि agent को अंदर रहना चाहिए।
- Cart अधिदेश। agent के बाद उपयोगकर्ता द्वारा मध्य mandate, signed ने एक विशिष्ट cart बनाया है: "हां, ये सटीक आइटम इस सटीक कीमत पर हैं।" उन प्रवाहों में उपयोग किया जाता है जहां कोई मानव अनुमोदन के लिए मौजूद होता है।
- भुगतान अधिदेश। भुगतान के समय अंतिम mandate, signed (या Intent Mandate के विरुद्ध स्वतः उत्पन्न): "इस सटीक भुगतान को इस सटीक रेल पर अधिकृत करें।"
- SPT (Shared Payment Token). ACP का आदिम. payment processor (Stripe) से एक बार का टोकन एक merchant, एक राशि सीमा और एक छोटी समय विंडो पर लॉक हो जाता है। यदि $50 के लिए स्वीकृत एक agent $1,000 खर्च करने का प्रयास करता है, तो SPT विफल हो जाता है। AP2 भुगतान अधिदेश का कार्ड-रेल चचेरा भाई।
- अस्वीकार्य। एक signed रिकॉर्ड जिसे हस्ताक्षरकर्ता बाद में बनाने से इनकार नहीं कर सकता। AP2 mandate श्रृंखला non-repudiable है: "मैंने इसे कभी अधिकृत नहीं किया" उपयोगकर्ता के स्वयं के क्रिप्टोग्राफ़िक हस्ताक्षर के विरुद्ध नहीं है।
Settlement और crypto primitives
- stablecoin। एक cryptocurrency एक स्थिर मूल्य पर आंका जाता है, आमतौर पर एक US dollar। Agents इसका उपयोग करें ताकि भेजने और निपटान के बीच "$0.05 भुगतान" पांच सेंट का रहे।
- USDC. विशिष्ट डॉलर-जुड़ी stablecoin अधिकांश x402 भुगतान का उपयोग करते हैं। एक USDC का मतलब एक US dollar के बराबर है। सर्कल द्वारा जारी किया गया.
- HTTP 402 भुगतान आवश्यक। एक HTTP status code 1997 से आरक्षित है लेकिन x402 द्वारा इसे पुनर्जीवित करने तक अप्रयुक्त था। server "402" प्लस भुगतान आवश्यकताओं का उत्तर देता है; client retries signed भुगतान प्रमाण के साथ संलग्न है।
- EIP-3009 (transferWithAuthorization). Ethereum मानक x402 पर बनाया गया है। यह एक buyer को एक भुगतान off-chain पर हस्ताक्षर करने देता है जिसे कोई अन्य व्यक्ति on-chain सबमिट करता है, इसलिए buyer कभी भी gas fees का भुगतान नहीं करता है या सीधे blockchain को नहीं छूता है।
- Facilitator (x402)। एक वैकल्पिक तृतीय पक्ष जो signature की जांच करता है और merchant के लिए भुगतान on-chain जमा करता है, इसलिए merchant को अपना स्वयं का blockchain प्लंबिंग चलाने की आवश्यकता नहीं है। Coinbase और Cloudflare दोनों facilitator चलाते हैं।
- CAIP-2. blockchain को नाम देने का एक मानक तरीका ताकि protocol chain-agnostic रह सके। x402 CAIP-2 फॉर्म में चेन लिखता है।
- EIP-155 / chain id। Ethereum-शैली श्रृंखलाओं के लिए CAIP-2 के अंदर नंबरिंग योजना।
eip155:8453का अर्थ है Base श्रृंखला; नंबर chain id है. (आप x402 code मेंeip155:8453देखेंगे; इसका मतलब सिर्फ "बेस" है।) - Smart-contract wallet। एक crypto wallet जिसके व्यय नियम (प्रति-लेन-देन सीमा, दैनिक सीमा, प्रति-प्राप्तकर्ता सीमा) code द्वारा blockchain पर ही लागू किए जाते हैं। क्योंकि श्रृंखला उन्हें लागू करती है, भले ही agent का अपना code खराब हो जाए, ये सीमाएं कायम रहती हैं।
- MPP सत्र। MPP की signature चाल। हर एक भुगतान के लिए signing के बजाय, agent एक खर्च सीमा और एक समय सीमा के साथ एक "session" खोलता है, फिर इसके बंद होने तक कई छोटे मीटर वाले भुगतान स्ट्रीम करता है। "agent के लिए एक प्रीपेड टैब" के बारे में सोचें।
- Sessions model (MPP). उपरोक्त पैटर्न का सामान्य नाम: एक सीमा और अवधि को पूर्व-अधिकृत करें, फिर इसके विरुद्ध कई छोटे शुल्क मीटर करें। बार-बार कॉल आने पर प्रत्येक micropayment से सस्ता।
Commerce और धन अवधारणाएँ
- निपटान। वह क्षण जब पैसा वास्तव में buyer से विक्रेता के पास चला जाता है। settlement से पहले सब कुछ सिर्फ कोरियोग्राफी है; सौदा तभी पूरा होता है जब settlement पूरा हो जाता है।
- रिकॉर्ड का Merchant (MoR)। लेन-देन के लिए व्यवसाय कानूनी रूप से हुक पर है: यह कर, disputes और ग्राहक सहायता को संभालता है। ACP में merchant MoR रहता है। सादे machine-to-machine x402 कॉल में अक्सर कोई MoR नहीं होता है।
- chargeback। जब buyer का बैंक कार्ड से भुगतान को उलट देता है, आमतौर पर किसी विवाद के बाद। Card rails समर्थन chargebacks; शुद्ध x402 नहीं है। chargebacks की आवश्यकता अक्सर यह तय करती है कि आप कौन सा protocol उपयोग करते हैं।
- विवाद। एक buyer की एक आरोप को औपचारिक चुनौती ("मैंने इसे अधिकृत नहीं किया" / "आइटम कभी नहीं आया")। अलग-अलग protocols disputes को अलग-अलग हल करते हैं; वह अंतर अक्सर protocol चुनने पर मजबूर करता है।
- निष्क्रियता। एक संपत्ति जहां एक ही ऑपरेशन को दो बार करने का प्रभाव एक बार करने के समान ही होता है। यह मायने रखता है क्योंकि समान इवेंट आईडी के साथ Stripe retries webhooks; idempotency key के बिना आपका code refund या दो बार चार्ज हो सकता है।
agent stack और निकटवर्ती protocols
- Agent वाणिज्य। कोई भी लेनदेन जहां एक स्वायत्त AI agent buyer, seller, या दोनों है, उस समय कोई मानव क्लिक खरीद नहीं करता है। "AI-असिस्टेड" shopping से भिन्न जहां एक व्यक्ति अभी भी बटन दबाता है।
- OpenAI Agents SDK.
Agent,Runner.run(),@function_toolऔर guardrail के साथ agent लूप बनाने के लिए Python/JavaScript toolkit। इस कोर्स में यह "यूनिवर्सल client" है: प्रत्येक भुगतान protocol एक या अधिक tools बन जाता है जिसे agent कॉल कर सकता है। - MCP (Model Context Protocol). Anthropic का tools और agents के संदर्भ को उजागर करने के लिए खुला मानक। agent commerce में यह अक्सर discovery layer: agents MCP server के माध्यम से खरीदने योग्य सेवाएं ढूंढता है। MIT लाइसेंस प्राप्त।
- A2A (Agent2Agent). Google का protocol agents के लिए एक दूसरे से बात करने और खोजने के लिए। AP2 A2A के शीर्ष पर बनाया गया है: एक mandate एक A2A संदेश के रूप में यात्रा करता है। Apache 2.0.
- UCP (Universal Commerce Protocol). Google का commerce-layer protocol, ACP का peer है, जो Google shopping surfaces (Gemini, Google AI Mode) के around बना है। Commerce layer पर यह ACP से compete करता है।
- TAP (Trusted Agent Protocol). HTTP request हेडर के अंदर agent के identity को साबित करने के लिए Visa और Cloudflare का protocol। यह सत्यापित करता है कि agent कौन है, न कि इसे कितना खर्च करने की अनुमति है, इसलिए यह आमतौर पर इसे बदलने के बजाय किसी अन्य प्रमाणीकरण protocol में जोड़ता है।
- ERC-8004. agent identity और प्रतिष्ठा के लिए एक on-chain मानक: agents की एक सार्वजनिक रजिस्ट्री और उनका लेनदेन इतिहास, इसलिए बिना किसी पूर्व संबंध वाला agent किसी अन्य पर भरोसा करने से पहले उसके ट्रैक रिकॉर्ड की जांच कर सकता है।
tool_input_guardrail. एक OpenAI Agents SDK guardrail जो tool निष्पादित होने से पहले चलता है और कॉल को अस्वीकार कर सकता है। यह किसी भुगतान को होने से पहले रोकने का SDK-देशी तरीका है। इस पाठ्यक्रम की रीढ़: यह सात भुगतान tool में दिखाई देता है। (इसके विपरीतoutput_guardrail, जो agent के अंतिम उत्तर पर चलता है, भुगतान रोकने के लिए बहुत देर हो चुकी है।)
पूर्वावश्यकताएँ
आपको इस पाठ्यक्रम से अधिकतम लाभ मिलेगा यदि आपके पास:
- Build AI Agents क्रैश कोर्स, या समकक्ष SDK अनुभव। protocol एकीकरण SDK code के रूप में दिखाए जाते हैं, इसलिए आपको
Agent,Runner.run(), और@function_toolको आराम से पढ़ने की आवश्यकता है। Build AI Agents क्रैश कोर्स देखें। - Choosing Agentic Architectures क्रैश कोर्स, या समकक्ष डिज़ाइन सेंस। भाग 5 में "कौन सा composition किस उपयोग के मामले में" framework उस पैटर्न-चयन अनुशासन पर आधारित है। Choosing Agentic Architectures क्रैश कोर्स देखें।
- बुनियादी HTTP. Status codes, अनुरोध/response चक्र, हेडर। x402 विशेष रूप से HTTP स्तर पर कार्य करता है।
- बुनियादी भुगतान शब्दावली। Merchant, settlement, dispute, chargeback। पाठ्यक्रम agent-विशिष्ट भागों की व्याख्या करता है लेकिन यह मानता है कि आप जानते हैं कि "merchant ऑफ़ रिकॉर्ड" क्या है।
आपको blockchain या smart-contract अनुभव की नहीं आवश्यकता है (पाठ्यक्रम पालन करने के लिए पर्याप्त x402 और EIP-3009 सिखाता है; कोई Solidity नहीं), और आपको चार protocol में से किसी के साथ पूर्व अनुभव की आवश्यकता नहीं है। वे सभी प्राथमिक स्रोतों से सिखाए गए हैं।
चार learning tracks
यह कोर्स चार गहराइयों पर काम करता है।भाग 5 से पहले अपना ट्रैक चुनें।
| ट्रैक | समय | आप क्या करोगे | के लिए सर्वोत्तम |
|---|---|---|---|
| पाठक | 2-3 घंटे | सभी अवधारणाओं और निर्णयों को पढ़ें; रनिंग code छोड़ें. | इंजीनियर निर्णय ले रहे हैं कि गहरा निवेश करना है या नहीं। PMs और architects जिन्हें विक्रेता प्रस्तावों का मूल्यांकन करने के लिए framework की आवश्यकता है। |
| शुरुआती | ~1 दिन | रीडर प्लस x402 client उदाहरण प्लस एक ACP परीक्षण लेनदेन को Stripe परीक्षण मोड में चलाएं। | agent commerce में नए इंजीनियर जो सबसे सरल protocol (x402) और सबसे अधिक उत्पादन के लिए तैयार (ACP) के साथ व्यावहारिक समय चाहते हैं। |
| मध्यवर्ती | 2-3 दिन | शुरुआती प्लस एक agent बनाएं जो एक प्रकार के लेनदेन के लिए ACP और दूसरे के लिए x402 का उपयोग करता है, साथ ही वायर AP2 Intent Mandate चेक का उपयोग करता है। | इंजीनियर एक वास्तविक सिस्टम की शिपिंग कर रहे हैं जिसमें compose एकाधिक protocol हैं। |
| उन्नत | 4-5 दिन | इंटरमीडिएट प्लस composed सिस्टम को टिकाऊ रूप से चलाएं (Inngest envelope), तार spend limits और मानव-अनुमोदन द्वार, trace, लागत और dispute metrics को मापें, और एक पूर्ण refund चक्र को संभालें। | production सिस्टम के लिए जिम्मेदार इंजीनियर वास्तविक उपयोगकर्ताओं के लिए वास्तविक धन ले जा रहे हैं। |
एक उपयोगी self-check: "मेरे मन में जो use case है, उसके लिए value ship करने वाला सबसे छोटा protocol composition क्या है?" अगर Part 4 के बाद इसका जवाब नहीं दे पा रहे हैं, तो Part 4 फिर पढ़ें। अगर जवाब दे पा रहे हैं, तो आपका track बस इस बात का सवाल है कि "smallest composition" से "production-grade composition" तक कितना आगे जाना चाहते हैं।
चार-परत stack
यह वह आरेख है जिस पर बाकी सभी चीज़ें टिकी हुई हैं।
प्रत्येक agent-commerce उपयोग का मामला सभी चार layers को छूता है, लेकिन प्रत्येक पर अलग-अलग उपयोग के मामले compose अलग-अलग protocols होते हैं। एक consumer shopping agent: discovery के लिए MCP, authorization के लिए एक ACP shared payment token, commerce के लिए ACP, निपटान के लिए card rails। एक API-paying agent: discovery के लिए एक agent directory, authorization के लिए एक EIP-3009 signature, बिल्कुल भी commerce layer नहीं, निपटान के लिए x402। एक enterprise procurement agent: एक A2A निर्देशिका, एक AP2 mandate, ACP या commerce के लिए UCP, निपटान के लिए Stripe MPP। नियम सरल है: प्रति layer एक protocol चुनें, और उपयोग के मामले को प्रत्येक चयन को उचित ठहराने दें।
भाग 1: agent commerce को नए protocols की आवश्यकता क्यों है
भाग 1 में छह नाम (ACP, AP2, x402, MPP, MCP, A2A) और तीन layers तेज शामिल हैं। यह जानबूझकर किया गया है: यह हिस्सा ब्रीफिंग है, गहरा गोता नहीं। आपको कम से कम यह रखने की आवश्यकता है: ACP consumer shopping (Stripe प्लस OpenAI) है, AP2 authorization mandates (Google प्लस 60 भागीदार) है।x402 HTTP (Coinbase) पर per-request stablecoin भुगतान है, MPP session-based multi-rail भुगतान (Stripe प्लस Tempo) है।MCP और A2A agents एक-दूसरे को ढूंढने और बात करने के तरीके हैं, भुगतान protocol नहीं। नामों को ढीले ढंग से पकड़ें. भाग 2 गहराई में प्रत्येक पर लौटता है और वे दूसरे पास पर टिके रहेंगे।
संकल्पना 1: वह धारणा जो टूट गई
एक पंक्ति में: भुगतान प्रणालियों ने माना कि एक इंसान खरीद पर क्लिक कर रहा था, और agents ने उस धारणा को एक साथ तीन तरीकों से तोड़ दिया।
भुगतान प्रणालियाँ एक शांत धारणा पर बनाई गई थीं: एक इंसान कीबोर्ड पर है, खरीद पर क्लिक कर रहा है। प्रत्येक स्क्रीन, प्रत्येक धोखाधड़ी जांच, प्रत्येक dispute प्रक्रिया, प्रत्येक साइनअप फॉर्म लोगों के लिए डिज़ाइन किया गया था। AI agents उस धारणा को एक ही समय में तीन तरीकों से तोड़ता है।
ब्रेक 1: agents में ईमेल पते नहीं हैं। Consumer भुगतान प्रवाह के लिए एक खाता चाहिए। एक account एक ईमेल, एक फ़ोन नंबर, अक्सर एक नाम चाहता है। एक स्वायत्त agent में इनमें से कुछ भी नहीं है। उन्हें नकली बनाएं, और आपने एक ऐसी इकाई बनाई है जो धोखाधड़ी का पता लगते ही KYC विफल हो जाती है। साइनअप प्रवाह में एक रिश्ते के लिए आवेदन करने वाले मानव को शामिल किया गया है; agent को कुछ और चाहिए।
ब्रेक 2: agents प्रति सेकंड हजारों बार कार्य करता है। धोखाधड़ी का पता लगाने की दर, स्थान और पैटर्न के आधार पर अजीब व्यवहार को चिह्नित करता है। एक agent एक मिनट में 1,000 API कॉल करना बिल्कुल एक क्रेडेंशियल-स्टफिंग हमले जैसा दिखता है। agent के लिए सामान्य बात एक इंसान के लिए अलार्म है, और rails को इंसानों के लिए ट्यून किया गया है।
ब्रेक 3: agents फोन नहीं उठा सकता। Dispute रिज़ॉल्यूशन मानता है कि buyer तक पहुंचा जा सकता है: "क्या आपने इसे अधिकृत किया है?" किसी आरोप को अधिकृत करने वाला agent उत्तर नहीं दे सकता है, और इसके पीछे के व्यक्ति को यह भी पता नहीं होगा कि आरोप लगा है। जब buyer सॉफ्टवेयर हो तो Disputes को एक अलग model की आवश्यकता होती है।
प्रत्येक ब्रेक को protocol स्तर पर ठीक करने की आवश्यकता है, UI पर पेंट के एक कोट की नहीं:
| तोड़ना | मानव-रेल सुधार क्या नहीं कर सकता | agent-रेल फिक्स आपको क्या देता है |
|---|---|---|
| कोई ईमेल या account नहीं | agents को फर्जी अकाउंट बनाने के लिए बाध्य करें | क्रिप्टोग्राफ़िक identity (TAP, ERC-8004) या स्कोप्ड टोकन (ACP SPT, AP2 Mandate) |
| उच्च-आवृत्ति व्यवहार | किसी हमले की तरह लगने वाले ट्रैफ़िक को रोकें | HTTP-मूल per-request भुगतान (x402) या pre-authorized sessions (MPP) |
| disputes के लिए कोई फ़ोन नहीं | ईमेल disputes agent नहीं पढ़ सकता | non-repudiable ऑडिट ट्रेल के साथ जनादेश-आधारित authorization (AP2) |
"बस पुराने भुगतानों को बेहतर agent UX में लपेटें" पथ पहले ही विफल हो चुका है। 2024 और 2025 में कई स्टार्टअप्स ने इसे आज़माया: agents को बनी-बनाई पहचान के साथ मानव जैसे खाते दें। धोखाधड़ी का पता चलने से वे पकड़े गए, chargebacks ढेर हो गए, merchant रिश्ते टूट गए। protocol-स्तरीय सुधार आवश्यक साबित हुए, वैकल्पिक नहीं। इसीलिए ACP, AP2, x402, और MPP सभी एक ही बारह महीनों के भीतर दिखाई दिए।
संकल्पना 1 की निचली पंक्ति: भुगतान प्रणालियों ने मान लिया कि एक मानव क्लिक खरीदता है। Agents इसे तीन तरीकों से तोड़ता है: कोई पारंपरिक identity, खतरनाक व्यवहार पैटर्न, किसी विवाद को स्पष्ट करने के लिए कोई चैनल नहीं। प्रत्येक ब्रेक को protocol-स्तरीय फिक्स की आवश्यकता होती है। पुराने rails को अच्छे UX में लपेटना विफल रहा। चार protocols प्रत्येक इन ब्रेक के एक अलग मिश्रण को कवर करते हैं।
अवधारणा 2: एक protocol क्यों नहीं जीत सकता
एक पंक्ति में: ब्रेक चार अलग-अलग पदधारियों के साथ चार अलग-अलग layers पर होते हैं, इसलिए protocols ने काम को एक द्वारा पूरा निगलने के बजाय layer द्वारा विभाजित किया।
एक उचित प्रश्न: यदि सभी चार protocols समान तीन ब्रेक को ठीक करने के लिए आए, तो उनमें से एक भी क्यों नहीं जीता? उत्तर संरचनात्मक है. ब्रेक अलग-अलग layers पर होते हैं, और एक protocol जिसने उन सभी को ठीक करने का प्रयास किया है, वह किसी के भी अपनाने के लिए बहुत बड़ा होगा।
इस बारे में सोचें कि एक एकीकृत protocol को क्या निर्दिष्ट करना होगा:
- agents उपलब्ध merchants और सेवाओं का पता कैसे लगाएं। वह discovery परत है।
- agents कैसे साबित करें कि वे कौन हैं और एक इंसान ने खर्च को अधिकृत किया है। वह authorization परत है।
- agents पूरी खरीदारी कैसे चलाता है, disputes और refunds शामिल हैं। वह commerce परत है।
- पार्टियों के बीच पैसा वास्तव में कैसे चलता है? वह settlement परत है।
प्रत्येक layer में पहले से ही मजबूत पदाधिकारी हैं। Discovery खोज इंजन और API से संबंधित है। Identity OAuth और प्रमाणपत्र प्राधिकारियों से संबंधित है। Commerce Stripe, Adyen और Shopify से संबंधित है। Settlement Visa, Mastercard, और ACH, साथ ही नई crypto रेल से संबंधित है। एक एकीकृत protocol को प्रत्येक layer पर प्रत्येक पदधारी को इस पर सहमत होने की आवश्यकता होगी। ऐसा कभी नहीं होने वाला था.
इसके बजाय क्या हुआ कि प्रत्येक protocol ने एक layer को चुना जहां उसके प्रायोजक के पास सबसे अधिक लाभ था:
| Protocol | जहां इसके प्रायोजक का उत्तोलन है | layer यह लिया |
|---|---|---|
| ACP | OpenAI shopping चैनल (ChatGPT) का मालिक है; Stripe merchant एकीकरण का मालिक है | Commerce, मानव-खरीदार-AI प्रवाह के लिए |
| AP2 | Google में Android wallets और 60-साझेदार गठबंधन है | Authorization, mandates signed क्रेडेंशियल के रूप में |
| x402 | Coinbase में stablecoin बुनियादी ढांचा है; Cloudflare में HTTP किनारा है | Settlement, machine-to-machine micropayments के लिए |
| MPP | Stripe में merchant संबंध हैं; Tempo में blockchain है | Settlement, enterprise और multi-rail प्रवाह के लिए |
तो protocols layer के अंदर लड़ाई न करें; वे एक को परिभाषित करने के लिए प्रतिस्पर्धा करते हैं। settlement पर, x402 और MPP वास्तव में प्रतिस्पर्धा करते हैं, और अधिकांश "x402 बनाम MPP" टुकड़े याद करते हैं कि यह एकमात्र स्थान है जहां वे वास्तव में ओवरलैप होते हैं। commerce पर, ACP और UCP प्रतिस्पर्धा करते हैं। authorization पर, AP2, TAP, और ERC-8004 प्रतिस्पर्धा करते हैं।
इससे हमें एक विचार मिलता है कि यह पूरा पाठ्यक्रम इसी पर आधारित है।layer के भीतर, आप एक protocol चुनते हैं। layers में, आप कई compose हैं। चार protocols के बीच चयन करने के लिए विकल्प नहीं हैं; वे स्टैक करने के लिए layers हैं। एक consumer shopping agent निपटान पर commerce और card rails पर ACP चलाता है। एक API-paying agent x402 को settlement पर चलाता है और commerce को पूरी तरह से छोड़ देता है। एक enterprise agent निपटान पर AP2 mandates authorization और MPP पर चलता है। भाग 5 में decision tree इस layer को परत दर परत चलता है। इसे थामे रखें: इसके बाद का प्रत्येक अनुभाग इसे मानता है।
संकल्पना 2 की निचली पंक्ति: एक protocol सभी चार ब्रेक को ठीक नहीं कर सकता क्योंकि ब्रेक चार layers पर रहते हैं, प्रत्येक में मजबूत पदधारी होते हैं। protocols विशेषज्ञ: commerce पर ACP, authorization पर AP2, निपटान पर x402 और MPP। layer के भीतर आप एक चुनें; layers के पार आप कई compose हैं।
संकल्पना 3: OpenAI Agents SDK सार्वभौमिक client के रूप में
एक पंक्ति में: आप चार protocols चार अलग-अलग तरीकों से बात नहीं करते हैं; agent कॉलों में से प्रत्येक एक tool बन जाता है, और SDK एकल client है जो उन सभी को जोड़ता है।
एक व्यावहारिक प्रश्न: चार layers पर चार protocols दिए गए, एक agent वास्तव में उनका उपयोग कैसे करता है? 2026 में उत्तर यह है कि agent के framework सार्वभौमिक ग्राहक बन जाता है। प्रत्येक protocol एक SDK या एक HTTP endpoint को उजागर करता है, और framework इसे एक उपकरण के रूप में तार देता है। यह OpenAI Agents SDK, LangGraph, AutoGen और CrewAI के लिए समान रूप से सत्य है। हम पूरे समय OpenAI Agents SDK का उपयोग करेंगे।
SDK के लिए, प्रत्येक protocol एकीकरण एक ही आकार का अनुसरण करता है: protocol को एक या अधिक @function_tool functions में लपेटें, उन्हें Agent को सौंपें, और Runner.run को लूप चलाने दें।
नीचे दिए गए
stripe.PaymentTokens.create,X402Client(wallet=...), औरfrom ap2 import ...कॉल उदाहरणात्मक हैं: वे protocol एकीकरण के आकार को दर्शाते हैं। उनके चारों ओर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 कॉल नहीं है (production ACP लाइव Stripe ACP endpoints के माध्यम से एकीकृत होता है), और समृद्ध X402Client(wallet=..., max_per_request=...) कंस्ट्रक्टर भी उदाहरणात्मक है। वास्तविक buyer-side पैकेज x402-client है, और लाइव कॉल के लिए एक वित्त पोषित account और एक वास्तविक 402 endpoint की आवश्यकता होती है, जो यह कोर्स नहीं करता है। भाग 3 प्रत्येक protocol को एक चलने योग्य मॉक बैकएंड देता है ताकि आप वास्तविक धन को स्थानांतरित किए बिना हार्नेस कार्य को शुरू से अंत तक देख सकें।
आकार सभी चार protocol में समान है। SDK सार्वभौमिक client है; प्रत्येक protocol सिर्फ एक tool है, agent इसके बारे में बताता है और जरूरत पड़ने पर कॉल करता है। भुगतान के लिए SDK संरचना के तीन भाग मायने रखते हैं:
- भुगतान परिणामों के लिए एक टाइप किया गया रिटर्न मान। जब एक भुगतान tool returns एक Pydantic model होता है, तो agent के रीज़नर को स्पष्ट प्रकार की जानकारी मिलती है कि क्या सफल हुआ, क्या विफल हुआ और आगे क्या करना है। भाग 3 इन साझा परिणाम models को एक बार परिभाषित करता है।
- भुगतान संदर्भ के लिए
Runner.run(..., context=...)। agent को अक्सर उपयोगकर्ता के identity, खर्च सीमा और wallet हैंडल की आवश्यकता होती है। इन्हें निर्देशों में बेक करने के बजाय SDK केcontextपैरामीटर से गुजारें।contextप्रति-रन और प्रति-उपयोगकर्ता है। - खर्च सीमा के लिए
tool_input_guardrail। एक tool input guardrail प्रत्येक tool के निष्पादित होने से पहले चलता है और कॉल को अस्वीकार कर सकता है। यह किसी भुगतान को होने से पहले रोकने का SDK-मूल तरीका है, बाद में नहीं। संकल्पना 15 पूर्ण तीन-स्तरीय प्रवर्तन पर चलता है। agent-स्तरoutput_guardrailइसका समाधान नहीं करता है, क्योंकि यह agent के अंतिम उत्तर पर सक्रिय होता है, किसी भी भुगतान के बाद tool पहले ही चल चुका है।
संकल्पना 3 की निचली पंक्ति: OpenAI Agents SDK सभी चार protocol के लिए सार्वभौमिक client है। प्रत्येक
@function_toolagent कॉल बन जाता है। SDK का टाइप किया गया रिटर्न,context, औरtool_input_guardrailभुगतान संबंधी चिंताओं को स्पष्ट रूप से मैप करता है: संरचित परिणाम, प्रति-उपयोगकर्ता संदर्भ, और ऐसा होने से पहले भुगतान रोकना। एकीकरण का आकार चारों में समान है; भाग 3 प्रत्येक में भरता है।
भाग 2: चार layers गहराई में
आप भाग 1 में चार layers से मिले; यहां हर एक करीब है। प्रत्येक layer एक अलग प्रश्न का उत्तर देता है, उसका अपना प्रतिस्पर्धी protocols होता है, और एक निर्णय को बाध्य करता है: इस उपयोग के मामले के लिए, कौन सा protocol इस layer के लिए सबसे उपयुक्त है? भाग 3 से पहले भाग 2 पढ़ें। यहां परत-दर-परत फ़्रेमिंग वह है जो भाग 3 में protocol विवरण को प्रतिद्वंद्वियों की सूची की तरह पढ़ने के बजाय सुसंगत बनाती है।
संकल्पना 4: Layer 1, Discovery (agents कैसे खोजें कि वे क्या खरीद सकते हैं)
एक पंक्ति में: Discovery वह जगह है जहां agent यह पता लगाता है कि खरीदने के लिए क्या उपलब्ध है, और सही तंत्र इस बात पर निर्भर करता है कि वे सेवाएँ वास्तव में कहाँ रहती हैं।
इससे पहले कि agent लेनदेन कर सके, उसे यह पता लगाना होगा कि वहां क्या है। एक shopping agent को merchants की आवश्यकता होती है जो उत्पाद ले जाए। एक API-paying agent को यह जानना होगा कि कौन से endpoints के पास data है और उनकी कीमत क्या है। एक procurement agent को ऐसे आपूर्तिकर्ताओं की आवश्यकता है जो इसके अनुपालन नियमों को पारित करते हों। Discovery उत्तर "क्या उपलब्ध है?"
2026 में यहां चार गंभीर विकल्प प्रतिस्पर्धा करते हैं:
| Protocol | यह कैसे काम करता है | के लिए सर्वोत्तम |
|---|---|---|
| MCP (Anthropic) | Tool server कॉल करने योग्य functions को उजागर करते हैं; agent कनेक्ट होता है, tools को सूचीबद्ध करता है, और उन्हें कॉल करता है | डेवलपर द्वारा वायर्ड की गई विशिष्ट सेवाओं तक प्रोग्रामेटिक पहुंच; उच्च मात्रा agent कार्य; प्रमुख agent-toolींग discovery layer |
| A2A (Google) | Agents वे जो पेशकश करते हैं उसे मानक लिफाफे में प्रकाशित करें; अन्य agents उन्हें खोजें | बहु-agent पारिस्थितिकी तंत्र जहां agents को सहकर्मी agents खोजने की आवश्यकता है; discovery layer AP2 विस्तारित है |
| Agent directories (agent.मार्केट, lobster.cash, टेन्ज़्रो) | सार्वजनिक बाज़ारों की सूची सशुल्क APIs और सेवाएँ; agents query उन्हें एक कैटलॉग की तरह | runtime पर तृतीय-पक्ष सेवाएँ खोजी गईं; agent commerce के "येलो पेज"। |
| AI shopping surfaces (ChatGPT Instant Checkout, Google AI मोड, वॉलमार्ट-इन-चैटGPT) | Consumer AI उत्पाद discovery प्लस ACP checkout उत्पाद के साथ निर्मित | Consumer प्रवाहित होता है जहां उपयोगकर्ता AI से बात कर रहा होता है और यह उत्पादों को इनलाइन प्रदर्शित करता है |
SDK में MCP के लिए प्रथम श्रेणी का समर्थन है: एक MCP server को कुछ पंक्तियों में एक agent पर तार दें और इसके सभी tools agent के तर्क के लिए उपलब्ध हो जाते हैं। गैर-MCP discovery के लिए, इसे एक साधारण @function_tool के रूप में लपेटें जो queries निर्देशिका और संरचित लिस्टिंग लौटाता है।
नीचे दी गई
MCPServerStreamableHttpवायरिंग वास्तविक और आयात योग्य है।agent_market_clientकॉल उदाहरणात्मक है: यह एक डायरेक्ट्री 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 बनाम निर्देशिकाएं" नहीं है। यह है: मेरी agent की सेवाएँ वास्तव में कहाँ रहती हैं? अपने संगठन के आंतरिक, MCP का उपयोग करें। साझेदार agents के नेटवर्क पर, A2A का उपयोग करें। तृतीय-पक्ष APIs जिसे आप runtime पर खोजते हैं, निर्देशिकाओं का उपयोग करें। Consumer उत्पाद, AI shopping सतह (और commerce layer पर ACP) का उपयोग करें। ये परस्पर अनन्य नहीं हैं; एक वास्तविक agent अक्सर कई का उपयोग करता है।
संकल्पना 4 की निचली पंक्ति: Discovery उत्तर "क्या उपलब्ध है?" चार विकल्प प्रतिस्पर्धा करते हैं: आंतरिक tool server के लिए MCP, मल्टी-agent इकोसिस्टम के लिए A2A, तृतीय-पक्ष सेवाओं के लिए निर्देशिका, consumer उत्पादों के लिए AI सतह। SDK में प्रथम श्रेणी MCP समर्थन है और बाकी को
@function_toolfunction के रूप में तार देता है। यह चुनें कि सेवाएँ कहाँ रहती हैं; वे परस्पर अनन्य नहीं हैं।
संकल्पना 5: Layer 2, Identity और Authorization (agent की अनुमति है)
एक पंक्ति में: Authorization वह जगह है जहां agent साबित करता है कि मानव ने इस खर्च की अनुमति दी है और agent वह है जो वह होने का दावा करता है, किसी भी पैसे के स्थानांतरण से पहले।
इससे पहले कि पैसा चल सके, दो चीजें सच होनी चाहिए: agent वह है जो वह होने का दावा करता है, और मानव इस खर्च को अधिकृत करता है। वे अलग-अलग समाधानों वाली अलग-अलग समस्याएं हैं, और Layer 2 settlement होने से पहले दोनों का समाधान कर देता है। Layer 2 को छोड़ें और आपको दो विफलताओं में से एक मिलेगी: धोखाधड़ी (किसी का भी agent किसी का भी पैसा खर्च कर सकता है) या पक्षाघात (प्रत्येक लेनदेन की पुष्टि के लिए क्लिक करने के लिए एक मानव की आवश्यकता होती है)।
यह 2026 में सबसे अधिक विवादित layer है। चार विकल्प, चार दर्शन:
| Protocol | यह कैसे काम करता है | सबसे मजबूत जहां |
|---|---|---|
| AP2 Mandates (Google) | Signed क्रेडेंशियल: Intent Mandate ("120 डॉलर से कम में जूते खरीदें"), Cart Mandate ("यह cart, यह कीमत"), Payment Mandate ("इस rail को अधिकृत करें") | ऑडिट-भारी प्रवाह जिसके लिए सहमति के non-repudiable प्रमाण की आवश्यकता होती है; मल्टी-agent प्रवाह वहां होता है जहां merchant ने buyer का agent पहले कभी नहीं देखा है |
| ACP SPT (OpenAI प्लस Stripe) | Stripe एक Shared Payment Token को एक merchant, राशि और समय विंडो तक सीमित करता है; agent इसे प्रस्तुत करता है; merchant सत्यापित करता है और चार्ज करता है | Consumer shopping जहां Stripe प्रोसेसर है और card rails chargeback अनुशासन रखता है |
| TAP (Visa प्लस Cloudflare) | agent के identity signature HTTP headers में सवारी करता है; merchants इसे Visa की निर्देशिका के विरुद्ध सत्यापित करें | विशेष रूप से Identity सत्यापन (authorization नहीं); आमतौर पर किसी अन्य प्रमाणीकरण protocol में जोड़ा जाता है, अकेले उपयोग नहीं किया जाता है |
| ERC-8004 प्लस on-chain प्रतिष्ठा | पिछले सौदों से प्रतिष्ठा स्कोर के साथ, agent पहचान और लेनदेन इतिहास की एक on-chain रजिस्ट्री | बिना किसी पूर्व विश्वास के शुद्ध मल्टी-agent प्रवाह; उच्च-दांव B2B जहां प्रतिष्ठा जांचने लायक है |
दो प्रश्नों Layer 2 को उत्तर देना होगा, और प्रत्येक protocol उनका उत्तर कैसे देता है:
- "क्या मानव ने इसे अधिकृत किया?" AP2 प्रत्यायोजित करने से पहले उपयोगकर्ता signed के साथ उत्तर देता है। ACP SPT Stripe के साथ उत्तर देता है, जो उपयोगकर्ता द्वारा account स्तर पर अधिकृत होने के बाद ही बनाया जाता है। TAP इसका उत्तर नहीं देता; यह केवल पहचान है. ERC-8004, signed on-chain लेनदेन के साथ उत्तर देता है।
- "क्या agent वह है जो वह होने का दावा करता है?" AP2 signing कुंजी के साथ उत्तर देता है (केवल वास्तविक agent ही हस्ताक्षर कर सकता है)। ACP, SPT के व्यापारी-क्षेत्र के साथ उत्तर देता है (केवल अधिकृत merchant ही इसे भुना सकता है)। TAP Visa की निर्देशिका लुकअप के साथ उत्तर देता है। ERC-8004 on-chain identity रिकॉर्ड के साथ उत्तर देता है।
SDK आपको दो एकीकरण बिंदु देता है: एक tool input guardrail जो भुगतान tool से पहले चलता है, और run context जो प्रति-उपयोगकर्ता स्थिति को दोनों में ले जाता है।
नीचे दी गई guardrail,
@function_tool, औरAgentवायरिंग वास्तविक SDK है और चलती है (विशेषता पथdata.context.tool_argumentsऔरdata.context.contextकी पुष्टि स्थापित SDK के विरुद्ध की गई है)। tool के अंदरstripe.PaymentTokens.createकॉल उदाहरणात्मक है; production ACP लाइव Stripe ACP endpoint का उपयोग करता है।
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 में तीन guardrail प्रकार हैं और वे अलग-अलग क्षणों में फायर करते हैं। input_guardrail पहले agent के प्रारंभिक इनपुट पर चलता है। output_guardrail उपयोगकर्ता के लिए अंतिम agent के response पर चलता है। tool_input_guardrail और tool_output_guardrail प्रत्येक function-tool कॉल पर, उसके निष्पादित होने से पहले और बाद में चलते हैं। भुगतान सुरक्षा के लिए आपको tool input guardrail की आवश्यकता है: यह भुगतान tool चलने से पहले सक्रिय हो जाता है और कॉल को अस्वीकार कर सकता है। भुगतान रोकने के लिए एक output guardrail बहुत देर से चालू होता है; यह अंतिम उत्तर को साफ करने के लिए उपयोगी है (मान लीजिए, संवेदनशील data को संशोधित करना), किसी tool को अवरुद्ध करने के लिए नहीं। संकल्पना 15 इस पर लौटती है; यह सबसे आम गलती है।
यहां आप जो चुनाव करते हैं वह आपके विश्वास model पर निर्भर करता है। यदि उपयोगकर्ता आपके ऐप में signed है और आप Stripe के माध्यम से SPTs ढाल सकते हैं, तो ACP आपको सबसे अधिक उत्पादन-तैयार कहानी देता है। यदि आपको non-repudiable ऑडिट ट्रेल्स की आवश्यकता है, जैसा कि विनियमित उद्योगों में होता है या B2B procurement, AP2 mandates फिट बैठता है। यदि आपको authorization से अलग क्रिप्टोग्राफ़िक identity की आवश्यकता है, तो TAP जोड़ें। बिना किसी साझा विश्वास वाली शुद्ध मल्टी-agent सेटिंग में, ERC-8004 इस कमी को पूरा करता है। ये विनिमेय नहीं हैं.
संकल्पना 5 की निचली पंक्ति: Authorization दो प्रश्नों के उत्तर देता है: "क्या मानव ने इसे अधिकृत किया है?" और "क्या agent वह है जो वह होने का दावा करता है?" चार protocols प्रतिस्पर्धा करते हैं: AP2 mandates (ऑडिट-भारी), ACP SPT (धारी-मूल), TAP (केवल पहचान), ERC-8004 (मल्टी-agent ट्रस्ट)। SDK प्रति-tool जांच के लिए run context और खर्च सीमा के लिए
tool_input_guardrail(जो प्रत्येक tool से पहले चलता है और इसे अस्वीकार कर सकता है) के माध्यम से एकीकृत होता है। विश्वास model द्वारा चुनें.
अवधारणा 6: Layer 3, Commerce (पूर्ण purchase lifecycle)
एक पंक्ति में: Commerce वास्तविक खरीदारी में वह सब कुछ है जो authorization या settlement नहीं है: cart, ऑर्डर, fulfillment, dispute, refund, और एक सादा API कॉल इसे पूरी तरह से छोड़ देता है।
Authorization और settlement मिलकर "अनुमति के साथ पैसे की आवाजाही" को कवर करते हैं। Commerce खरीदारी में बाकी सब कुछ शामिल करता है: संरचित cart, ऑर्डर पुष्टिकरण, fulfillment ट्रैकिंग, dispute रिज़ॉल्यूशन, refunds, chargebacks, रिटर्न। यह layer है जो checkout को धन हस्तांतरण से अलग करता है। एक सादे machine-to-machine API कॉल के लिए commerce layer की आवश्यकता नहीं है; यह सिर्फ एक API कॉल है। consumer खरीदारी के लिए स्पष्ट रूप से एक की आवश्यकता होती है।
तीन अर्थपूर्ण भिन्न विकल्प:
| Protocol | यह क्या करता है | के लिए सर्वोत्तम |
|---|---|---|
| ACP (OpenAI प्लस Stripe) | एक संरचित प्रवाह: cart प्रारूप, ऑर्डर पुष्टिकरण, fulfillment स्थिति, dispute वृद्धि, refund। merchant रिकॉर्ड का merchant बना हुआ है। | Consumer shopping: retail माल, सदस्यता, भौतिक पूर्ति। पॉवर्स ChatGPT त्वरित checkout। |
| UCP (Google) | एक समान जीवनचक्र, Google की shopping सतहों (मिथुन, Google AI मोड) और Google पे के आसपास बनाया गया है | Merchants पर Google Shopping; agents Google AI सतहों पर |
| डायरेक्ट API (machine-to-machine) | कोई commerce protocol बिल्कुल नहीं, बस एक HTTP API। x402 या MPP के माध्यम से भुगतान। कोई cart नहीं, कोई disputes नहीं, कोई refund नहीं। | API पहुंच, गणना, data फ़ीड: खरीदारी जहां खरीदी गई चीज़ एक स्टेटलेस API response है |
तो ACP और UCP प्रतिस्पर्धा करते हैं; "प्रत्यक्ष API" इस layer की अनुपस्थिति है, कोई तीसरा प्रतियोगी नहीं है, और यह अक्सर शून्य के बगल में खुशी से बैठता है। एक consumer प्लेटफ़ॉर्म ACP या UCP (या दोनों, यदि यह ChatGPT और जेमिनी तक फैला है) चुनता है। एक API marketplace इस layer को बिल्कुल भी नहीं चुनता है, क्योंकि इसकी खरीदारी को प्रबंधित करने के लिए कोई जीवनचक्र नहीं है।
अधिकांश इंजीनियर जिस हिस्से को कम आंकते हैं वह है refunds और विवाद। जो ग्राहक गलत आकार की टी-शर्ट का ऑर्डर देता है, वह उसे वापस भेजने की अपेक्षा करता है। commerce protocol को यह बताना होगा कि वापसी कैसे शुरू होती है, agent इसके बारे में कैसे सुनता है, और refund निपटान के माध्यम से वापस कैसे प्रवाहित होता है। merchant को रिकॉर्ड के merchant के रूप में रखने से ACP को यह अधिकार मिलता है: मौजूदा dispute मशीनरी (Stripe का chargeback प्रवाह, खुदरा विक्रेता की वापसी नीति) बस काम करती है। डायरेक्ट-API दृष्टिकोण इसे अनदेखा करने से गलत हो जाता है। अक्सर कोई refund पथ नहीं होता है, जो $0.0001 API कॉल के लिए ठीक है और $500 API क्रेडिट के लिए गलत है।
Commerce प्रवाह को आमतौर पर अनुक्रम में काम करने वाले कई tools की आवश्यकता होती है:
नीचे दिए गए
acp_clientकॉल उदाहरणात्मक हैं; वे ACP commerce बैकएंड के लिए खड़े हैं। Pydantic models,@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],
)
यहां पूछने योग्य प्रश्न यह है कि क्या आपके उपयोग के मामले में commerce जीवनचक्र की आवश्यकता है। यदि ऐसा होता है (cart, refund, dispute), ChatGPT पहुंच के लिए ACP या Google पहुंच के लिए UCP चुनें, या दोनों। यदि ऐसा नहीं होता है, तो इस layer को छोड़ें और सीधे authorization से निपटान पर जाएं। इसे गलत करने के दो तरीके हैं: एक उपभोक्ता-वाणिज्य protocol को machine-to-machine कॉल पर मजबूर करना (बहुत अधिक), या वास्तविक consumer खरीदारी पर commerce को छोड़ना और फिर बाद में बुरी तरह से disputes को फिर से लागू करना (बहुत कम)।
अवधारणा 6 की निचली पंक्ति: Commerce पूर्ण purchase lifecycle को संभालता है: cart, checkout, fulfillment, dispute, refund। ACP और UCP consumer प्रवाह के लिए प्रतिस्पर्धा करते हैं; machine-to-machine एक्सेस में कोई commerce layer ही नहीं है। Refund और dispute यांत्रिकी छिपा हुआ वजन है जो वास्तविक commerce protocol को केवल-भुगतान वाले से अलग करता है। SDK tools (cart, checkout, स्थिति, refund) के अनुक्रम के रूप में commerce तार करता है। उपयोग के मामले के अनुसार चुनें: जीवनचक्र आवश्यक (ACP/UCP) या छोड़ दिया गया (प्रत्यक्ष API)।
अवधारणा 7: Layer 4, Settlement (पैसा वास्तव में चलता है)
एक पंक्ति में: Settlement वह जगह है जहां डॉलर वास्तव में हिरासत में बदलाव करते हैं, और चयन ज्यादातर लेनदेन के अर्थशास्त्र के बारे में होता है।
मूल्य को buyer से विक्रेता तक ले जाएँ। इस layer से ऊपर की हर चीज़ कोरियोग्राफी है; settlement वह जगह है जहां डॉलर (या stablecoins, या जो भी इकाई है) वास्तव में हाथ बदलते हैं। agent settlement पूरा होने के बाद ही लेनदेन पूरा करता है।
चार गंभीर विकल्प, प्रत्येक का अपना अर्थशास्त्र और सीमाएं हैं:
| Protocol | यह कैसे काम करता है | अर्थशास्त्र | के लिए सर्वोत्तम |
|---|---|---|---|
| x402 | HTTP-मूल; EIP-3009 के साथ Base/Solana/EVM, signed पर stablecoin स्थानांतरण के माध्यम से व्यवस्थित होता है | सब-सेंट गैस, 1-2 सेकंड अंतिमता, कोई protocol शुल्क नहीं | Machine-to-machine micropayments; उच्च-आवृत्ति, कम-मूल्य (API पहुंच, प्रति-कॉल बिलिंग) |
| MPP | Sessions: agent एक सीमा और अवधि को पूर्व-अधिकृत करता है, फिर मीटर्ड भुगतान स्ट्रीम करता है। Multi-rail (stablecoin Tempo पर, Lightning, कार्ड) | card rails पर Stripe शुल्क; stablecoin पर लगभग शून्य; सदस्यता-अनुकूल | Enterprise और multi-rail प्रवाह; आवर्ती सदस्यताएँ; एक envelope में फ़िएट और crypto दोनों की आवश्यकता वाले मामले |
| Card rails (Stripe/Adyen/Worldpay) | Visa, Mastercard, एमेक्स Stripe के माध्यम से; agent एक SPT (ACP) या Payment Mandate (AP2) प्रस्तुत करता है; प्रोसेसर कार्ड को चार्ज करता है | कार्ड के लिए लगभग 2.9% प्लस $0.30; स्थापित dispute मशीनरी | Consumer प्रवाह; chargeback एक्सपोज़र के साथ लेनदेन; अंतर्राष्ट्रीय कार्ड स्वीकृति |
| बैंक स्थानांतरण / Lightning | ACH, SEPA, बिटकॉइन Lightning | ACH ~$0.25 निश्चित; बिजली उपकेंद्र; SEPA ~€0.20 | उच्च-मूल्य प्रवाह जहां 2.9% कार्ड शुल्क नुकसान पहुंचाता है; Lightning के माध्यम से सीमा पार micropayments |
settlement का चुनाव अधिकतर पैसे के बारे में है। उप-डॉलर भुगतान x402 पर जाता है, जहां stablecoin गैस उप-सेंट है। Consumer लगभग $1,000 तक की खरीदारी ACP के माध्यम से card rails पर जाती है, जहां chargeback सुरक्षा 2.9% के लायक है। आवर्ती सदस्यताएँ MPP सत्रों में जाती हैं। बड़े B2B स्थानांतरण bank rails या Lightning पर जाते हैं। और उपरोक्त layers आमतौर पर चुनने के लिए बाध्य करता है: ACP पर commerce का अधिकतर अर्थ card rails पर settlement है; discovery पर x402-भुगतान किए गए MCP server का अधिकतर अर्थ निपटान के समय x402 होता है।
हेडलाइन-नंबर ट्रैप पर नज़र रखें। x402 के लेन-देन की मात्रा या MPP की एकीकरण गणना का हवाला देने वाले टुकड़े गुमराह कर सकते हैं। सही प्रश्न यह नहीं है कि "किसका आयतन सबसे अधिक है?" यह "इस लेन-देन के अर्थशास्त्र में कौन सा फिट बैठता है?" card rails पर सेटल की गई $0.001 API कॉल की फीस कॉल से अधिक है। x402 stablecoin पर तय किया गया $5,000 procurement chargeback सुरक्षा को समाप्त कर देता है जो एक कार्ड आपको देता है।
Settlement आमतौर पर उच्च-परत tool के साइड इफेक्ट के रूप में सक्रिय होता है: agent शायद ही कभी settle_payment() को सीधे कॉल करता है; settlement acp_checkout() या x402_fetch() के अंदर होता है। लेकिन spend limits SDK स्तर पर अभी भी मायने रखता है:
नीचे दिया गया
x402_client.getकॉल उदाहरणात्मक है; इसका मतलब buyer-side 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 + ... चेक tool बॉडी के अंदर एक सॉफ्ट गार्ड है, जो तेज, मैत्रीपूर्ण विफलता के लिए उपयोगी है लेकिन वास्तविक सुरक्षा के लिए नहीं। जो सुरक्षा वास्तव में आपकी सुरक्षा करती है वह agent के smart-contract wallet है। भले ही आपने इन-tool चेक हटा दिया हो, फिर भी कॉन्सेप्ट 15 से wallet कैप्स on-chain ट्रांसफर को अस्वीकार कर देंगे। tool का चेक UX के लिए है; wallet कैप सुरक्षा हैं।
यहां कदम rail को चुनना है जो लेनदेन के अर्थशास्त्र से मेल खाता है, फिर पुष्टि करें कि यह आपकी commerce पसंद के साथ संगत है। उप-डॉलर machine-to-machine x402 पर जाता है। Consumer खरीदारी ACP के माध्यम से card rails पर जाती है। Enterprise सदस्यताएँ MPP पर जाती हैं। settlement को अलग से न चुनें; इसे composed स्टैक के निचले भाग के रूप में चुनें।
संकल्पना 7 की निचली पंक्ति: Layer 4 (Settlement) वह जगह है जहां पैसा वास्तव में चलता है। चार विकल्प प्रतिस्पर्धा करते हैं। machine-to-machine stablecoin भुगतान के लिए x402। multi-rail सत्रों के लिए MPP। Card rails consumer खरीदारी के लिए जिसके लिए chargeback की आवश्यकता है। उच्च मूल्य या बहुत कम शुल्क वाले मामलों के लिए बैंक या Lightning। चुनाव ज्यादातर पैसे के बारे में है: उप-डॉलर x402 को जाता है, consumer कार्ड को जाता है, enterprise एमपीपी को जाता है। SDK उच्च-परत tool के साइड इफेक्ट के रूप में settlement चलाता है। यह
RunContextWrapperके साथ रन और session स्तर पर खर्च को सीमित करता है, और wallet के on-chain कैप layer हैं जिन्हें कोई भी बायपास नहीं कर सकता है।
भाग 3: गहराई में चार protocols, OpenAI Agents SDK एकीकरण के साथ
भाग 1 और 2 ने फ़्रेमिंग सेट की: चार layers, कई protocols प्रति layer, यूनिवर्सल client के रूप में SDK। भाग 3 चार शीर्षकों protocols में से प्रत्येक को करीब से दिखाता है। प्रत्येक के लिए आपको वह मिलेगा जो वह है, इसकी कुंजी primitives, SDK एकीकरण code, और टीमें इसे कैसे तैनात और चलाती हैं, इस पर संक्षिप्त नोट्स।
इन्हें चार समानांतर गहरे गोता के रूप में पढ़ें। प्रत्येक protocol का आकार समान है, इसलिए आप उनकी साथ-साथ तुलना कर सकते हैं।
इस आरेख में पैटर्न में से एक के माध्यम से SDK में प्रत्येक protocol अवधारणा 8 से 11 तारों तक। नीचे तीन-स्तरीय spend-limit stack भाग 6 में अवधारणा 15 का पूर्वावलोकन करता है। पढ़ते समय इसे अपनी आंख के कोने में रखें: यह जो सुरक्षा अनुशासन दिखाता है वह इस code को ऐसी चीज़ में बदल देता है जिसे आप वास्तव में तैनात कर सकते हैं।
🧰 Pydantic अनुबंध layer के रूप में: एक बार पढ़ें, नीचे दिए गए प्रत्येक protocol पर लागू होता है
भाग 3 में प्रत्येक code नमूना Pydantic models का उपयोग करता है, न कि सादे Python निर्देशों का, protocol payloads, tool returns, FastAPI request और response बॉडी, और Inngest इवेंट पेलोड। यह वह हिस्सा है जिसे आप छोड़ नहीं सकते। यह वही है जो पूरे सिस्टम को एक साथ रखता है।
एक विशिष्ट agent-वाणिज्य प्रवाह में चार सीमाएँ पार हो जाती हैं:
- SDK का
@function_tool, agent के रीज़नर को एक मान लौटाता है। - वह मान तार को protocol endpoint (ACP, AP2, x402, MPP) तक पार करता है।
- protocol एक response लौटाता है जो पीछे की ओर जाता है।
- कभी-कभी webhook बाद में आता है और FastAPI हैंडलर में चला जाता है।
प्रत्येक सीमा पर, एक अलिखित आदेश चुपचाप फ़ील्ड खो देता है, जबरदस्ती छोड़ देता है, और गलत आकार भेज देता है। Pydantic models सीमा पर सभी चार प्रकार की विफलताओं को पकड़ता है, उन त्रुटियों के साथ जो सटीक क्षेत्र की ओर इशारा करती हैं।
यहां वह पैटर्न है जो नीचे दी गई प्रत्येक अवधारणा में दोहराया जाता है:
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.
...
इस पैमाने पर इसके महत्व के तीन ठोस कारण:
- तर्ककर्ता रिटर्न प्रकार को फीडबैक के रूप में उपयोग करता है। जब
acp_checkoutएक टाइप किया हुआCheckoutResultलौटाता है, तो agent के अगले तर्क चरण को साफ फ़ील्ड नाम और प्रकार मिलते हैं, न कि एक कठोर निर्देश। उपकरण-चयन सटीकता मापनीय रूप से बढ़ जाती है। - FastAPI मूल रूप से Pydantic का उपयोग करता है। Stripe webhooks, AP2 mandate callbacks, और MPP session ईवेंट सभी Pydantic में डिसेरिएलाइज़ हो जाते हैं। FastAPI हैंडलर में models: वही models agent के tools रिटर्न। एक अनुबंध, दो समापन बिंदु।
- Inngest इवेंट Pydantic पेलोड ले जाते हैं। जब एक FastAPI webhook handler एक Inngest इवेंट फायर करता है, तो payload एक Pydantic model है। निलंबित
step.wait_for_eventसीधे टाइप किया गया payload प्राप्त करता है। वर्कफ़्लो में कोई JSON पार्सिंग नहीं।
पैसे के लिए दशमलव, हमेशा। इस पाठ्यक्रम में प्रत्येक मौद्रिक राशि Decimal का उपयोग करती है, कभी float का नहीं। पैसे पर फ़्लोटिंग-पॉइंट गणित उन तरीकों से सटीकता खो देता है जो हजारों micropayments में मिश्रित होते हैं। Stripe SDK दोनों को स्वीकार करता है लेकिन Decimal में वापस रिपोर्ट करता है। x402 राशियाँ on-chain पूर्णांक के रूप में आती हैं (USDC में 6 दशमलव स्थान हैं) जिन्हें आप Decimal में लपेटते हैं। पैसा हर जगह Decimal रहता है, इसे तार प्रारूप में क्रमबद्ध नहीं किया जा रहा है।
साझा परिणाम model। प्रत्येक अवधारणा में परिणाम प्रकारों को फिर से परिभाषित करने के बजाय, पाठ्यक्रम एक बार परिणाम models के एक छोटे सेट को परिभाषित करता है। नीचे दिया गया प्रत्येक code ब्लॉक उन्हें नाम से आयात करता है। इन्हें अपने 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
ये models भाग 3 और भाग 6 के माध्यम से दोहराए जाते हैं। नीचे दिए गए code ब्लॉक उन्हें नाम से आयात करते हैं और उन्हें कभी भी दोबारा परिभाषित नहीं करते हैं। आप प्रत्येक अवधारणा में आयात पैटर्न को दोहराया हुआ देखेंगे; यह साइडबार दोहराता नहीं है.
संकल्पना 8: ACP (Agentic Commerce Protocol), consumer-shopping protocol
एक पंक्ति में: ACP इस प्रकार है कि कैसे एक agent एक व्यक्ति की ओर से एक वास्तविक merchant पर एक वास्तविक checkout को पूरा करता है, जबकि merchant अभी भी बिक्री के लिए तैयार है।
यह क्या है। ACP, OpenAI और Stripe द्वारा निर्मित एक खुला विनिर्देश है, जिसे 29 सितंबर, 2025 को लॉन्च पार्टनर के रूप में Etsy और Shopify के साथ लॉन्च किया गया था। 2026 की शुरुआत तक यह Shopify-एकीकृत merchants और कई बड़े retail ब्रांडों को ChatGPT Instant Checkout को शक्ति प्रदान करता है। Merchant की गिनती और ब्रांड सूचियां स्रोत के अनुसार अलग-अलग होती हैं, इसलिए वर्तमान अपनाने के लिए ACP एकीकरण निर्देशिका के विरुद्ध सत्यापित करें। protocol Apache 2.0 है, जो github.com/agentic-commerce-protocol/agentic-commerce-protocol पर एक विशिष्टता संवर्धन प्रस्ताव प्रक्रिया के माध्यम से नियंत्रित होता है। repository spec को beta के रूप में चिह्नित करता है, इसलिए पाठ्यक्रम के उदाहरणों और लाइव स्पेक के बीच अंतर की उम्मीद करें।
यह कहां बैठता है। ACP ज्यादातर Layer 3 (Commerce) पर रहता है और अपने टोकन तंत्र के माध्यम से Layer 2 (Authorization) तक पहुंचता है। इसमें cart गठन, checkout, ऑर्डर प्रबंधन, fulfillment स्थिति और refund यांत्रिकी शामिल हैं। merchant रिकॉर्ड का merchant रहता है: chargebacks, रिटर्न और ग्राहक सेवा सभी merchant के मौजूदा सिस्टम के माध्यम से प्रवाहित होती है। (रिकॉर्ड का Merchant व्यवसाय कानूनी रूप से लेनदेन के लिए हुक पर है।)
दो primitives जो मायने रखते हैं।
- Shared Payment Token (SPT)। payment processor (संदर्भ बिल्ड में Stripe) से एक बार का टोकन, एक merchant, एक राशि सीमा, एक छोटी समय विंडो और आमतौर पर एक ही उपयोग के लिए लॉक किया जाता है। यदि $50 के लिए स्वीकृत कोई agent $1,000 खर्च करने का प्रयास करता है, तो SPT protocol स्तर पर विफल हो जाता है। SPT इस प्रकार है कि ACP agent को उपयोगकर्ता के अधिकृत दायरे में रखता है।
- Cart Mandate (AP2 एक्सटेंशन के माध्यम से)। ACP अतिरिक्त ऑडिट कठोरता के लिए AP2 के साथ compose कर सकता है: agent SPT सबमिट करने से पहले उपयोगकर्ता Cart Mandate पर हस्ताक्षर करता है। यह ACP में वैकल्पिक है लेकिन विनियमित प्रवाह में आम होता जा रहा है। (mandate एक signed प्रमाण है कि एक मानव ने एक विशिष्ट प्रकार के खर्च को अधिकृत किया है।)
OpenAI Agents SDK एकीकरण। ACP, SDK के लिए सबसे अधिक उत्पादन के लिए तैयार protocol है, क्योंकि OpenAI ने इसे सह-निर्मित किया है। Stripe Python SDK प्लस एक पतला ACP client रैपर आपको पूर्ण एकीकरण देता है।
नीचे दिए गए
acp_clientकॉल औरstripe.PaymentTokens.create(...)उदाहरणात्मक हैं: वे ACP एकीकरण के आकार को दर्शाते हैं। असली SPT ढलाई लाइव Stripe ACP endpoints से होती है,stripe.PaymentTokensविधि से नहीं। agent वायरिंग, guardrail, और परिणाम models वास्तविक हैं और आज भी चलते हैं। ब्लॉक के बाद नोट देखें.
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 मचान, साथ ही टाइप किए गए परिणाम model। यह वह हिस्सा है जिसे आप प्रत्येक protocol के लिए पुन: उपयोग करते हैं। स्टैंड-इन क्या है: acp_client और stripe.PaymentTokens.create कॉल, जो एसीपी-Stripe बैकएंड का प्रतिनिधित्व करते हैं। production में आप उस बैकएंड को लाइव Stripe ACP endpoints के लिए स्वैप करते हैं और बाकी वहीं रहता है। यहां चलाने योग्य मॉक के साथ वही आकृति दी गई है ताकि आप इसे काम करते हुए देख सकें:
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 FastAPI हैंडलर के अंदर चलता है; ACP कॉल आउटबाउंड हैं HTTPS; SPTs agent के रन-स्कोप संदर्भ में रहते हैं, RunContextWrapper से होकर गुजरते हैं। एक नियम: Stripe API कुंजियों को एक गुप्त स्टोर (key vault) में रखें, पर्यावरण चर में नहीं, और उन्हें Stripe के शेड्यूल पर घुमाएँ। किसी सैंडबॉक्स की आवश्यकता नहीं है (ACP बिना code चलता है) और किसी विशेष भंडारण की आवश्यकता नहीं है (ऑर्डर Stripe और merchant के सिस्टम में बने रहते हैं, ऑडिट के लिए वैकल्पिक छाया रिकॉर्ड के साथ)। यह परिनियोजन बेसलाइन AP2, x402 और MPP के लिए समान है। अगली तीन अवधारणाएँ वही कहती हैं जो प्रत्येक जोड़ती है। क्लाउड परिनियोजन को परिनियोजन-agent क्रैश कोर्स (प्रगति पर) में शामिल किया गया है।
इसे टिकाऊ ढंग से चलाना (Inngest)। ACP लेनदेन छोटे होते हैं, आमतौर पर शुरू से अंत तक 5 से 30 सेकंड। वे Inngest step.run ब्लॉकों में साफ-साफ फिट हो जाते हैं। step.wait_for_event primitive अपना स्थान तब अर्जित करता है जब agent को उपयोगकर्ता को cart निर्माण और checkout (human-in-the-loop पैटर्न) के बीच cart की पुष्टि करने के लिए रोकना होगा। Production Worker क्रैश कोर्स इस स्थायित्व layer को गहराई से कवर करता है; यहाँ आकृति है:
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 आने वाले payload को if_exp (एक छोटी अभिव्यक्ति) के साथ मेल खाता है, और प्रतीक्षित फ़ील्ड async. उपसर्ग के अंतर्गत रहते हैं। एक टाइमआउट None लौटाता है, इसलिए जारी रखने से पहले इसकी जांच कर लें।
जहां टीमों को यह गलती मिलती है। वे उपयोगकर्ता-पुष्टि चरण को छोड़ देते हैं। ACP "उपयोगकर्ता प्रत्येक cart की पुष्टि करता है" और "उपयोगकर्ता pre-authorized इस प्रकार की खरीदारी" दोनों का समर्थन करता है। टीमें अक्सर गति के लिए दूसरे को चुनती हैं, फिर पाती हैं कि एक छोटा SPT गलत कॉन्फ़िगरेशन agent को थोड़ा गलत आइटम खरीदने देता है और उसे पुनर्प्राप्त करने का कोई रास्ता नहीं है। उत्पादन के पहले महीने के लिए cart की पुष्टि करने में डिफ़ॉल्ट। इसे केवल एक बार आराम दें जब आप माप लें कि agent कितनी बार cart सही हो जाता है।
कॉन्सेप्ट 8 की निचली पंक्ति: ACP consumer shopping के लिए OpenAI Agents SDK के साथ उत्पादन के लिए तैयार commerce protocol है। SPT agent के खर्च का दायरा बढ़ाता है; merchant रिकॉर्ड का merchant बना हुआ है। आप इसे Stripe SDK और एक पतले ACP client पर चार
@function_toolfunctions (ब्राउज़ करें, checkout, स्थिति, refund) के रूप में एकीकृत करते हैं। Inngest काstep.wait_for_eventउपयोगकर्ता-पुष्टि द्वार बनाता है, और सादा क्लाउड हार्नेस पर्याप्त है। जब तक आप agent के cart सटीकता को माप नहीं लेते, तब तक cart की पुष्टि करना डिफ़ॉल्ट है।
अवधारणा 9: AP2 (Agent Payments Protocol), authorization layer
एक पंक्ति में: AP2 signed सबूत पेश करता है कि एक इंसान ने खर्च की अनुमति दी; यह पैसे को स्वयं स्थानांतरित नहीं करता है, यह साबित करता है कि पैसे को स्थानांतरित करने की अनुमति दी गई थी।
यह क्या है। AP2 60+ भागीदारों के साथ Google का एक खुला विनिर्देश है, जिसे सितंबर 2025 में लॉन्च किया गया (नवीनतम version v0.2.0, अप्रैल 2026)। Apache 2.0, github.com/google-agentic-commerce/AP2 पर बनाए रखा गया है, Python, TypeScript, Kotlin और Go में संदर्भ कार्यान्वयन के साथ। AP2 authorization layer है, commerce या settlement protocol नहीं है। यह signed mandates का उत्पादन करता है जो साबित करता है कि agent खर्च करने के लिए अधिकृत है, फिर वास्तविक settlement को rail में फिट बैठता है (कार्ड, बैंक, या a2a-x402 एक्सटेंशन के माध्यम से x402) छोड़ देता है।
यह कहाँ बैठता है। AP2 Layer 2 (Identity और Authorization) पर रहता है। यह नीचे दो protocols पर निर्मित होता है: A2A (Agent2Agent, agent-टू-agent मैसेजिंग के लिए) और MCP (tool एक्सपोज़र के लिए)। एक AP2 mandate A2A पर signed क्रेडेंशियल के रूप में यात्रा करता है या MCP tool कॉल से जुड़ा होता है।
तीन primitives जो मायने रखते हैं, तीन mandate प्रकार।
| Mandate | जब यह बनाया गया है | इससे क्या सिद्ध होता है |
|---|---|---|
| Intent Mandate | कार्य के प्रारंभ में, signed उपयोगकर्ता द्वारा अपने UI में | उपयोगकर्ता ने agent को निर्धारित नियमों (मूल्य सीमा, समय विंडो, merchants की अनुमति) के भीतर कार्य करने की अनुमति दी |
| Cart Mandate | agent के बाद उपयोगकर्ता द्वारा checkout (मानव-वर्तमान प्रवाह) से पहले एक विशिष्ट cart, signed बनाया गया है | उपयोगकर्ता ने इसी सटीक कीमत पर cart को मंजूरी दी |
| Payment Mandate | भुगतान के समय, उपयोगकर्ता द्वारा signed या Intent Mandate के विरुद्ध स्वतः जेनरेट किया गया | उपयोगकर्ता ने इस सटीक भुगतान को इसी rail पर अधिकृत किया है |
ऑडिट ट्रेल। तीन mandates एक श्रृंखला बनाते हैं जिसे हस्ताक्षरकर्ता बाद में अस्वीकार नहीं कर सकता है: इरादा ("$120 के तहत जूते खरीदें") Cart ("ये जूते $110 में") की ओर ले जाता है जिससे भुगतान होता है ("इस stablecoin wallet को चार्ज करें")। प्रत्येक mandate अपने से पहले वाले की ओर इशारा करता है। यदि किसी कदम को बाद में dispute या धोखाधड़ी के दावे में चुनौती दी जाती है, तो पूरी श्रृंखला ऑडिट योग्य है। वह संपत्ति non-repudiable है: "मैंने इसे कभी अधिकृत नहीं किया" उपयोगकर्ता के स्वयं के हस्ताक्षर के विरुद्ध नहीं है। यही कारण है कि AP2 स्वास्थ्य देखभाल और वित्तीय सेवाओं जैसे विनियमित उद्योगों में फिट बैठता है, जहां "उपयोगकर्ता ने वास्तव में इसे अधिकृत किया है?" कानूनी भार वहन करता है।
SDK के लिए क्या परिवर्तन। AP2 का OpenAI Agents SDK में कोई प्रथम श्रेणी स्थान नहीं है; इसका संदर्भ Google का Agent डेवलपमेंट किट का उपयोग करता है। आप इसे @function_tool functions के रूप में वायर करते हैं जो जनादेश बनाता है, हस्ताक्षर करता है, मान्य करता है और भेजता है। हार्नेस कॉन्सेप्ट 8 जैसा ही है। एक चीज जो AP2 जोड़ता है: एक signing सतह जहां उपयोगकर्ता वास्तव में प्रत्येक जनादेश पर हस्ताक्षर करता है।
नीचे दिए गए
from ap2 import ...आयात,MandateSigner, औरap2_x402कॉल उदाहरणात्मक हैं। AP2 का वास्तविक Python पैकेजap2है, mandate models के अंतर्गतap2.types.mandateहै, और इसके वास्तविक फ़ील्ड यहां दिखाए गए सरलीकृतprincipal_did/agent_did/rulesसे भिन्न हैं। कोईMandateSignerवर्ग नहीं है; वास्तविक signing A2A पर सत्यापन योग्य क्रेडेंशियल्स का उपयोग करता है। अधिदेश-श्रृंखला की अवधारणा वास्तविक है; यह सटीक code एक शिक्षण स्टैंड-इन है। 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 mandate कक्षाएं, MandateSigner, और ap2_x402 एक्सटेंशन। mandate श्रृंखला अपने आप में एक वास्तविक विचार है जिसे आप बना सकते हैं; यहां सटीक API को शिक्षण के लिए सरल बनाया गया है। यहां एक चलने योग्य मॉक है ताकि पैटर्न निष्पादित हो:
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 बेसलाइन से परे दो चीजें: उपयोगकर्ता के लिए mandates (एक वेब ऐप, एक मोबाइल ऐप, या अधिसूचना-आधारित signing tool) पर हस्ताक्षर करने के लिए एक signing सतह, और signed mandates के लिए durable स्टोरेज यह आपकी dispute विंडो तक चलता है (वित्तीय mandates के लिए 7-वर्षीय प्रतिधारण मानक है)। signing सतह ACP से वास्तविक डेल्टा है: ACP मौजूदा लॉगिन sessions का पुन: उपयोग कर सकता है, लेकिन AP2 को एक समर्पित signature प्रवाह की आवश्यकता है।
इसे टिकाऊ ढंग से चलाना (Inngest)। Mandate signing step.wait_for_event का पाठ्यपुस्तक उपयोग है। agent के function एक "signing अनुरोधित" ईवेंट सक्रिय करता है, function निलंबित हो जाता है, उपयोगकर्ता UI में हस्ताक्षर करता है जो "signing signed" सक्रिय करता है और function फिर से शुरू हो जाता है। प्रतीक्षा करते समय कोई भी गणना नहीं जलती है, जो मायने रखती है क्योंकि enterprise signature में घंटों लग सकते हैं। Production Worker क्रैश कोर्स इस resume pattern पर गहराई से जाता है।
जहां टीमों को यह गलती मिलती है। वे mandate निर्माण को checkout-टाइम चिंता के रूप में मानते हैं और mandate पर हस्ताक्षर करते हैं जब agent पहले ही बहुत काम कर चुका होता है। agent दुकानों से पहले, सबसे पहले Intent Mandate बनाएं। यह एक स्कोप बेमेल को जल्दी पकड़ लेता है (उपयोगकर्ता जूते चाहता था लेकिन Intent Mandate केवल कार्यालय की आपूर्ति की अनुमति देता है) इसके बजाय agent ने cart के निर्माण पर गणना खर्च करने के बाद इसे कभी भी वित्त पोषित नहीं किया जा सकता है।
अवधारणा 9 की निचली पंक्ति: AP2 ऑडिट-भारी agent वाणिज्य के लिए authorization layer है। तीन mandate प्रकार (इरादा, Cart, भुगतान) एक श्रृंखला बनाते हैं जिसे उपयोगकर्ता बाद में अस्वीकार नहीं कर सकता है, हर कदम पर सहमति साबित करता है। संदर्भ कार्यान्वयन Python, TypeScript, Kotlin, और Go में Google के Agent विकास किट के माध्यम से भेजा जाता है; आप OpenAI Agents SDK के साथ
@function_toolfunctions के रूप में एकीकृत होते हैं जो जनादेश बनाते हैं, हस्ताक्षर करते हैं और मान्य करते हैं। Inngest काstep.wait_for_eventsigning प्रतीक्षा के लिए स्वाभाविक रूप से फिट है। shopping शुरू होने से पहले, पहले इरादा Mandates बनाएं, बाद में checkout के रूप में कभी नहीं।
अवधारणा 10: x402, HTTP-मूल settlement protocol
एक पंक्ति में: x402 पुराने HTTP 402 "Payment Required" स्थिति code को पुनर्जीवित करके, एक agent को stablecoin के साथ एक से दो सेकंड में API कॉल के लिए भुगतान करने देता है।
यह क्या है। x402 निष्क्रिय HTTP 402 status code को APIs और machine-to-machine वाणिज्य के लिए एक कार्यशील payment layer में बदल देता है। इसे Coinbase (मई 2025) द्वारा बनाया गया था, V2 को दिसंबर 2025 में लॉन्च किया गया था, और अब इसे Linux Foundation के x402 फाउंडेशन (अप्रैल 2026) के तहत Cloudflare, Stripe के साथ संचालित किया गया है। AWS, Google, और अन्य सदस्य के रूप में। Apache 2.0. 2026 की शुरुआत में, x402 ने बढ़ते facilitator पारिस्थितिकी तंत्र के साथ, Base और Solana पर अब तक 100 मिलियन से अधिक भुगतान की रिपोर्ट दी है; संख्याएँ तेजी से आगे बढ़ती हैं, इसलिए x402.org और Coinbase का x402 लॉन्च पेज पर वर्तमान आंकड़ों को सत्यापित करें।
यह कहां बैठता है। machine-to-machine प्रवाह के लिए x402 ज्यादातर Layer 4 (Settlement) पर रहता है, लेकिन यह Layer 1 (agent.मार्केट और समान निर्देशिकाओं के माध्यम से) और Layer 3 तक पहुंचता है (यह पूर्ण commerce के रूप में काम करता है) सादे API पहुंच के लिए layer जहां कोई वास्तविक purchase lifecycle नहीं है)। शुद्ध machine-to-machine प्रवाह के लिए, x402 अक्सर एकमात्र protocol होता है जिसकी आपको आवश्यकता होती है।
चार primitives जो मायने रखते हैं।
- HTTP 402 स्थिति code। जब एक अवैतनिक client भुगतान किए गए संसाधन का अनुरोध करता है, तो server भुगतान आवश्यकताओं को लेकर
402 Payment Requiredप्लस एक header लौटाता है: योजना (एक निश्चित राशि के लिएexact), नेटवर्क (CAIP-2 फॉर्म में जैसेeip155:8453, जिसका सीधा अर्थ है "Base"), संपत्ति (USDC), प्राप्तकर्ता का पता, अधिकतम राशि और एक समाप्ति। (CAIP-2, blockchain को नाम देने का एक मानक तरीका है ताकि protocol chain-agnostic रहे।) - भुगतान authorization हेडर। client retries header के साथ signed भुगतान प्राधिकरण ले जा रहा है। signature off-chain से बना है, इसलिए buyer कोई गैस भुगतान नहीं करता है।
- EIP-3009 (transferWithAuthorization). Ethereum मानक x402 पर बनाया गया है। यह buyer को एक भुगतान off-chain पर हस्ताक्षर करने देता है जिसे कोई अन्य व्यक्ति on-chain सबमिट करता है, इसलिए buyer कभी भी blockchain को सीधे नहीं छूता है या गैस का भुगतान नहीं करता है।
- सुविधाकर्ता। एक वैकल्पिक तृतीय पक्ष जो signature की जाँच करता है और merchant के लिए भुगतान on-chain जमा करता है, इसलिए merchant कोई blockchain प्लंबिंग नहीं चलाता है। Coinbase और Cloudflare दोनों facilitator चलाते हैं।
x402 V1 और V2 से गुजरा, और header नाम spec versions, facilitators और SDK में भिन्न हैं। Cloudflare का वर्तमान docs 402 response पर PAYMENT-REQUIRED, client के retry पर PAYMENT-SIGNATURE और सफल उत्तर पर PAYMENT-RESPONSE का उपयोग करें। पहले के कुछ उदाहरण X-PAYMENT और X-PAYMENT-PROOF का उपयोग करते हैं। प्रवाह समान है; केवल तार के नाम भिन्न हैं। code लिखने से पहले x402.gitbook.io और अपने facilitator के docs के सामने सटीक नामों की जांच करें। नीचे दिया गया trace एक नामकरण परंपरा को चुने बिना भूमिकाओं (request, आवश्यकताओं के साथ 402, signed retry, प्रमाण के साथ सफलता) का उपयोग करता है।
एक ट्रेस में प्रवाह.
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: ... }
पूरे लेन-देन में एक से दो सेकंड का समय लगता है। कोई account creation, कोई API कुंजी, कोई session, लूप में कोई इंसान नहीं।
SDK के लिए क्या परिवर्तन। x402 में चारों में से सबसे सरल कहानी है। Cloudflare एक सहायक भेजता है जो MCP client को x402 भुगतान क्षमता के साथ लपेटता है; गैर-MCP उपयोग के लिए, एक Python buyer-side library प्लस नीचे विहित पैटर्न इसे कवर करता है। हार्नेस वही कॉन्सेप्ट 8 बेसलाइन है।
यहां दिखाया गया
from x402_client import ...कंस्ट्रक्टर,from cloudflare_agents import withX402Clientआयात, औरresponse.amount_paid_usdcफ़ील्ड उदाहरणात्मक हैं। वास्तविक buyer-side पैकेजx402-clientहै (from x402_client import X402Client, वास्तविक कंस्ट्रक्टरX402Client(account=...),.get(url)एकhttpx.Responseलौटाता है)। यहां दिखाया गया समृद्ध wallet कंस्ट्रक्टर एक शिक्षण स्टैंड-इन है, और लाइव कॉल के लिए एक वित्त पोषित account और एक वास्तविक 402 endpoint की आवश्यकता होती है, जो यह कोर्स नहीं करता है। Cloudflare काwithX402Clientएक JavaScript सहायक है; कोई Pythoncloudflare_agentsपैकेज नहीं है। MCP server (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 server वास्तविक Python है)। स्टैंड-इन क्या है: buyer-side x402 client जैसा कि यहां लिखा गया है, withX402Client रैपर (JavaScript केवल वास्तविकता में), और agent_market_client। यहां चलने योग्य मॉक हैं ताकि हार्नेस पैटर्न वास्तविक फंड के बिना निष्पादित हो:
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 बेसलाइन से परे किसी अतिरिक्त बुनियादी ढांचे की आवश्यकता नहीं है। agent के smart-contract wallet उस श्रृंखला के एक पते पर रहता है जिस पर यह लेनदेन करता है (ज्यादातर मामलों में Base), wallet की signing कुंजी key vault में बैठती है, और buyer-side library हैंडल signing और HTTP पुनः प्रयास करें। (एक smart-contract wallet एक crypto wallet है जिसकी खर्च सीमा code द्वारा blockchain पर ही लागू की जाती है, इसलिए यदि agent के code खराब हो जाए तो भी वे खर्च करते हैं।)
इसे टिकाऊ ढंग से चलाना (Inngest)। x402 कॉल छोटी (एक से दो सेकंड) और निष्क्रिय हैं: समान request और signature हमेशा एक ही परिणाम देते हैं। वे step.run ब्लॉकों में साफ-सुथरे ढंग से फिट होते हैं, और यहां संस्मरण से लाभ मिलता है। यदि 10 API कॉलों में से 5 के लिए भुगतान करने के बाद रन क्रैश हो जाता है, तो 5 भुगतान की गई कॉलों को याद किया जाता है और retry केवल शेष 5 के लिए भुगतान करता है। इसके बिना, retry फिर से सभी 10 के लिए भुगतान करेगा।
जाल x402 के साथ agent को क्रेडिट कार्ड सौंपने जैसा व्यवहार कर रहा है। जो सुरक्षा वास्तव में आपकी सुरक्षा करती है वह wallet की on-chain खर्च सीमा है, न कि per-request max_payment_usdc। on-chain सीमा को छोड़ें और बिना कैप वाले गर्म wallet का उपयोग करें, और एक अटका हुआ agent loop इसे ख़त्म कर सकता है। on-chain spend limits प्रति agent identity, प्रति session, और प्रति merchant, तीन स्वतंत्र layers कॉन्फ़िगर करें, ताकि एक में बग wallet को खाली न करे।
अवधारणा 10 की निचली पंक्ति: x402, machine-to-machine micropayment के लिए उत्पादन-तैयार HTTP-मूल settlement protocol है। 402 status code, एक signed भुगतान-प्राधिकरण header, और EIP-3009 signature प्रवाह बिना किसी account निर्माण के एक से दो सेकंड में व्यवस्थित हो जाता है। Cloudflare का सहायक भुगतान क्षमता के साथ MCP servers को लपेटता है; प्रत्यक्ष कॉल Python buyer-side library के माध्यम से काम करती हैं। Inngest का
step.runमेमोइज़ेशन पुनः प्रयास करने पर डुप्लिकेट भुगतान सहेजता है। wallet की on-chain खर्च सीमा वह सुरक्षा है जो आपकी सुरक्षा करती है, per-request सीमा नहीं। आप जिन spec version और facilitator के साथ एकीकृत हैं, उनके विरुद्ध header नाम सत्यापित करें।
संकल्पना 11: MPP (Machine Payments Protocol), sessions-based settlement protocol
एक पंक्ति में: MPP agent को खर्च सीमा के साथ एक प्रीपेड टैब खोलने देता है, फिर इसके विरुद्ध कई rails पर कई छोटे भुगतान स्ट्रीम करता है जब तक कि यह टैब बंद नहीं हो जाता।
यह क्या है। MPP को Stripe और Tempo द्वारा बनाया गया है, मार्च 2026 में सार्वजनिक लॉन्च की घोषणा के साथ। Tempo एक परत-1 blockchain है जिसे उच्च आवृत्ति मशीन भुगतान के लिए Stripe और Paradigm द्वारा इनक्यूबेट किया गया है। MPP को Stripe, Visa, Lightspark (Lightning Network), और अन्य पारिस्थितिकी तंत्र खिलाड़ियों के भागीदारों के साथ लॉन्च किया गया; भागीदार सूची बढ़ती है, इसलिए वर्तमान प्रतिभागियों के लिए mpp.dev और Cloudflare का MPP docs के विरुद्ध सत्यापन करें। Apache 2.0. MPP, Stripe है और x402 का settlement-layer उत्तर है: ओवरलैपिंग उपयोग का मामला, अलग दर्शन।
यह कहां बैठता है। MPP Layer 4 (Settlement) पर रहता है और machine-to-machine भुगतान के लिए सीधे x402 के साथ प्रतिस्पर्धा करता है। मुख्य अंतर: MPP multi-rail है और प्रति-चार्ज और session-based प्रमाणीकरण दोनों का समर्थन करता है, जबकि x402 केवल stablecoin और प्रति-अनुरोध है।
HTTP आकार। जहां x402 402 code और कस्टम headers का उपयोग करता है, MPP layers मानक HTTP प्रमाणीकरण पर भुगतान। server आवश्यकताओं के साथ WWW-Authenticate: Payment लौटाता है, client retries Authorization: Payment <signed-payload> के साथ देता है, और server settlement प्रमाण के साथ Payment-Receipt के साथ उत्तर देता है। यह MPP को एक कस्टम protocol के बजाय एक परिचित HTTP प्रमाणीकरण प्रवाह जैसा महसूस कराता है।
दो इरादे प्रकार।
| इरादा | जीवनचक्र | के लिए सर्वोत्तम |
|---|---|---|
charge | एक one-off स्थानांतरण, एक राउंड-ट्रिप में अधिकृत और व्यवस्थित | एकल खरीदारी, एक बार API एक्सेस, जब आपको multi-rail की आवश्यकता हो तो व्यक्तिगत x402 कॉल को बदलना |
session | agent एक सीमा और एक अवधि को पूर्व-अधिकृत करता है, फिर बंद होने तक मीटर micropayments स्ट्रीम करता है | उच्च आवृत्ति micropayments जहां signing प्रत्येक request महंगा है; आवर्ती सदस्यताएँ; "Stripe agents के लिए सदस्यता" model |
x402 के विरुद्ध व्यापार।
| आयाम | x402 | MPP |
|---|---|---|
| Authorization आवृत्ति | प्रति request (हर बार एक EIP-3009 signature) | प्रति charge या प्रति session (एक प्रमाणीकरण, कई मीटर्ड कॉल) |
| HTTP आकार | कस्टम 402 प्लस भुगतान headers | मानक WWW-Authenticate / Authorization / Payment-Receipt |
| Rails | केवल Stablecoin (बेस/Solana/EVM पर USDC) | Multi-rail (Tempo stablecoin, Lightning, कार्ड, ACH) |
| फीस | शून्य protocol शुल्क प्लस सब-सेंट गैस | Stripe card rails पर प्रसंस्करण शुल्क; Tempo stablecoin पर लगभग शून्य |
| आवर्ती समर्थन | सीमित (प्रति-अवधि signing की आवश्यकता) | session इरादे के माध्यम से मूल निवासी |
| सबसे उपयुक्त | One-off API कॉल, सार्वजनिक बुनियादी ढाँचा | आवर्ती सदस्यताएँ, enterprise और Stripe-एकीकृत merchants, फ़िएट फ़ॉलबैक की आवश्यकता वाले प्रवाह |
SDK के लिए क्या परिवर्तन। MPP Stripe Python SDK प्लस Stripe की MPP सतह के माध्यम से एकीकृत होता है। एकीकरण session प्रबंधन पर निर्भर है। हार्नेस वही कॉन्सेप्ट 8 बेसलाइन है।
नीचे दिए गए
from stripe.mpp import MPPSessionआयात औरstripe.MPPSessionकॉल उदाहरणात्मक हैं।stripe.MPPSessionऔरstripe.mppStripe Python SDK में नहीं हैं; MPP Stripe और Tempo मानक (mainnet मार्च 18, 2026) है, जो Stripe की MPP सतह के माध्यम से एकीकृत है। session अवधारणा (एक कैप, स्ट्रीम मीटर्ड कॉल को पूर्व-अधिकृत करें) वास्तविक है; यहां सटीक 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। session जीवनचक्र एक वास्तविक पैटर्न है; यहां सटीक Stripe API को शिक्षण के लिए सरल बनाया गया है। यहाँ एक चलने योग्य मॉक है:
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")})())})()
यह हार्नेस में क्या जोड़ता है। एक कॉन्फ़िगरेशन चरण: आपके Stripe account को MPP सक्षम करने की आवश्यकता है। Tempo blockchain एकीकरण को Stripe का MPP server द्वारा नियंत्रित किया जाता है, इसलिए agent कभी भी Tempo को सीधे नहीं छूता है। Stripe SDK और कुंजी प्रबंधन (ACP के समान) से परे, कुछ भी अतिरिक्त नहीं है।
इसे टिकाऊ ढंग से चलाना (Inngest)। MPP sessions मैप को Inngest के लंबे समय से चलने वाले function पैटर्न पर साफ-सुथरा बनाएं। session जीवनचक्र (बनाएं, उपयोग करें, बंद करें) step.run ब्लॉकों का एक क्रम बन जाता है, जिसमें step.sleep समय-आधारित समाप्ति के लिए उपलब्ध है। session model और durable निष्पादन compose अच्छी तरह से: दोनों स्टेटफुल, मल्टी-स्टेप कार्य के लिए बनाए गए हैं।
जहां टीमें यह गलती करती हैं। वे sessions बनाते हैं जो बहुत बड़े या बहुत लंबे होते हैं। यदि कुछ भी गलत होता है तो session कैप आपकी हानि सीमा है। "सुविधा के लिए" $1,000 का session सेट आपको $1,000 का agent-लूप-ग़ॉन-गलत नुकसान का सामना कराता है। वास्तविक अपेक्षित कार्य के लिए सही आकार sessions: 30-कॉल कार्य के लिए, 5 मिनट तक चलने वाला $5 session एक घंटे तक चलने वाले $50 session से अधिक सुरक्षित है।
अवधारणा 11 की निचली पंक्ति: MPP Stripe का settlement-layer है, जो x402 का उत्तर है, sessions-based metering और multi-rail प्रेषण के लिए ट्यून किया गया है। दो इरादे, एक बार के लिए
chargeऔर pre-authorized स्ट्रीमिंग के लिएsession, एकल खरीदारी और आवर्ती मीटरिंग दोनों को कवर करते हैं। session primitive उच्च आवृत्ति कॉल के लिए x402 से सस्ता है, और multi-rail डिस्पैच एक लिफाफे में stablecoin, Lightning और कार्ड को संभालता है। HTTP आकार ZZPH0223ZZ के कस्टम headers के बजाय मानकWWW-Authenticate: PaymentऔरAuthorization: Paymentका उपयोग करता है, जो इसे परिचित प्रमाणीकरण जैसा महसूस कराता है। आप Stripe SDK और Stripe की MPP सतह के माध्यम से एकीकृत होते हैं, और Inngest का durable निष्पादन session जीवनचक्र के साथ अच्छी तरह से मेल खाता है। अपेक्षित कार्य के लिए सही आकार session कैप, "सुविधा" के लिए नहीं।
भाग 4: Composition नियम, कब कौन सा protocols एक साथ उपयोग करना है
भाग 3 में एक बार में चार protocols चले। अब हमने उन्हें वापस एक साथ रख दिया। आपको भाग 1 में यह विचार मिला: एक वास्तविक प्रणाली एक बार में कई protocols का उपयोग करती है, प्रति परत एक। भाग 4 आपको नियम देता है कि कौन सा संयोजन काम करता है, कौन सा विफल रहता है, और stack को कार्य की अनुमति के अनुसार छोटा कैसे रखा जाए।
संकल्पना 12: न्यूनतम व्यवहार्य agent-भुगतान stack
एक पंक्ति में: सही stack protocols का सबसे छोटा सेट है जो एक उपयोग के मामले के लिए मूल्य भेजता है, प्रत्येक परत पर सभी चार protocols के लिए नहीं।
इससे पहले कि आप compose कुछ भी करें, एक प्रश्न पूछें: सबसे छोटा stack क्या है जिसका मूल्य यहां है? उत्तर लगभग कभी नहीं होता है "सभी चार protocols, प्रत्येक परत।" अधिकांश production सिस्टम पूरी तरह से वायर्ड एक layer से शुरू होते हैं और बाकी को तभी जोड़ते हैं जब उपयोग का मामला इसे मजबूर करता है।
यहां प्रत्येक सामान्य उपयोग के मामले के लिए सबसे छोटा stack है। यह भाग 5 में पाँच निर्णयों का भी पूर्वावलोकन करता है।
| केस का प्रयोग करें | Layer 1 (Discovery) | Layer 2 (प्रामाणिक) | Layer 3 (Commerce) | Layer 4 (Settlement) | यह एमवीपी क्यों है? |
|---|---|---|---|---|---|
| Consumer shopping (agent एक व्यक्ति के लिए retail सामान खरीदता है) | AI shopping सतह, या merchant कैटलॉग के साथ MCP server | ACP SPT (या विनियमित क्षेत्रों में एक AP2 mandate) | ACP | Card rails Stripe के माध्यम से | अधिकांश खरीदार chargeback कवर चाहते हैं। ACP प्लस Stripe वह पथ है जो आज जहाज करता है। |
| API-paying agent (agent तृतीय-पक्ष APIs को कॉल करता है जो चार्ज करता है) | MCP server x402 समर्थन या agent.मार्केट निर्देशिका के साथ | EIP-3009 signature (x402 डिफ़ॉल्ट) | कोई नहीं: सीधा API कॉल | x402 Base या Solana पर | machine-to-machine, Layers 2 और 4 पतन के लिए। कोई खरीद जीवनचक्र नहीं है. |
| Enterprise procurement (agent नियमों के तहत अनुमोदित आपूर्तिकर्ताओं से खरीदता है) | पार्टनर नेटवर्क के अंदर A2A discovery | AP2 Intent Mandate (ऑडिट के लिए आवश्यक) | कैटलॉग आपूर्तिकर्ताओं के लिए ACP या UCP; सेवा खरीद के लिए सीधे API | आवर्ती के लिए MPP sessions; ACP SPT one-off के लिए card rails के माध्यम से | ऑडिट ट्रेल वह हिस्सा है जिसे आप छोड़ नहीं सकते। AP2 mandates आवश्यक हैं। |
| Multi-agent marketplace (agent अन्य agents को काम पर रखता है) | A2A या agent directory | AP2 mandate प्लस एक ERC-8004 प्रतिष्ठा जांच | कोई नहीं: प्रत्यक्ष agent-से-agent | x402 (सबसे आम), या MPP यदि Stripe पहले से ही वायर्ड है | भरोसा दोनों तरह से चलता है. प्रत्येक पक्ष को सत्यापन योग्य identity और भुगतान प्रमाण की आवश्यकता है। |
composition नियम। उपयोग के मामले की मांग के अनुसार प्रत्येक layer पर protocol चुनें। layers पर protocols न जोड़ें, उपयोग का मामला कभी नहीं छूता। शुद्ध API-paying agent को ACP की आवश्यकता नहीं है। एक consumer-shopping agent को $50 की टी-शर्ट पर x402 तक नहीं पहुंचना चाहिए, क्योंकि कार्ड पर chargeback कवर 2.9% शुल्क के लायक है।
जाल। कुछ टीमें "लचीलेपन के लिए" ACP, AP2, x402, और MPP को एक साथ तार करने का प्रयास करती हैं। आपको चार बार एकीकरण सतह मिलती है और "कौन सा protocol कब सक्रिय होता है" का कोई स्पष्ट उत्तर नहीं मिलता है। एक ढेर चुनें. इसे भेज दो। दूसरा stack तभी जोड़ें जब दूसरे उपयोग के मामले में इसकी मांग हो।
संकल्पना 12 की निचली पंक्ति: न्यूनतम व्यवहार्य stack सबसे छोटा protocol सेट है जो एक उपयोग के मामले के लिए मूल्य प्रदान करता है। चार सामान्य ढेर इसके अधिकांश हिस्से को कवर करते हैं। Consumer shopping ACP प्लस कार्ड रेल है। API-paying अकेला x402 है। Enterprise procurement AP2 प्लस ACP या UCP प्लस MPP या कार्ड है। एक multi-agent marketplace AP2 प्लस ERC-8004 प्लस x402 है। यूनिवर्सल stack का निर्माण न करें; प्रत्येक उपयोग के मामले में एक composition चुनें और इसे शिप करें।
संकल्पना 13: जब protocols compose layers के पार हो और एक के भीतर प्रतिस्पर्धा करें
एक पंक्ति में: Protocols को अलग-अलग layers पर एक साथ stack बनाया गया है; protocols एक ही layer पर एक दूसरे को बदलने के लिए बनाए गए हैं, इसलिए एकमात्र सवाल यह है कि क्या दो protocols एक ही परत पर बैठते हैं।
दो protocols दो तरीकों में से एक में संबंधित हैं। वे या तो compose हैं, क्योंकि वे अलग-अलग layers पर बैठते हैं और stack पर बनाए गए थे, या वे प्रतिस्पर्धा करते हैं, क्योंकि वे एक ही layer पर बैठते हैं और स्थानापन्न के लिए बनाए गए थे। अधिकांश वास्तु संबंधी भ्रम दूसरे मामले को पहले के रूप में पढ़ने से उत्पन्न होता है।
layers के पार, compose पर निर्मित:
| Composition | Layer मैपिंग | यह कहां भेजा जाता है |
|---|---|---|
| AP2 + ACP | AP2 पर Layer 2 (ऑडिट-ग्रेड ऑथ), ACP पर Layer 3 (commerce) | विनियमित फ़ील्ड जहां ACP के सामान्य प्रवाह को अतिरिक्त ऑडिट की आवश्यकता होती है |
| AP2 + x402 | AP2 पर Layer 2 (mandate प्रामाणिक), x402 पर Layer 4 पर (stablecoin settlement) | a2a-x402 एक्सटेंशन के माध्यम से क्रिप्टो-देशी प्रवाह जिन्हें अभी भी ऑडिट की आवश्यकता है |
| ACP + x402 | ACP Layer 3 पर (commerce), x402 Layer 4 पर machine-to-machine खरीद के अंदर उप-प्रवाह के लिए | हाइब्रिड प्लेटफ़ॉर्म जहां consumer खरीदारी में कुछ API खर्च शामिल हैं |
MCP + x402 (withX402Client के माध्यम से) | MCP पर Layer 1 (discovery), x402 पर Layer 4 (settlement) | Cloudflare भुगतान के लिए मानक पैटर्न MCP tools |
एक layer के भीतर, प्रतिस्पर्धा के लिए बनाया गया:
| प्रतियोगिता | Layer | जब प्रत्येक जीतता है |
|---|---|---|
| AP2 बनाम ACP SPT बनाम TAP | Layer 2 | ऑडिट-ग्रेड प्रवाह के लिए AP2; Stripe-वायर्ड consumer प्रवाह के लिए ACP SPT; केवल पहचान जांच के लिए TAP |
| ACP बनाम UCP | Layer 3 | ChatGPT पहुंच के लिए ACP; मिथुन पहुंच के लिए UCP; दोनों क्रॉस-सरफेस विक्रेताओं के लिए |
| x402 बनाम MPP | Layer 4 | one-off micropayments और शुद्ध stablecoin प्रवाह के लिए x402; sessions, सदस्यता और multi-rail प्रवाह के लिए MPP |
परीक्षण। जब आप दो protocols के बीच फंस गए हों, तो एक बात पूछें: क्या वे एक ही layer पर हैं? यदि हां, तो आप एक को चुनते हैं, या आप अलग-अलग उप-प्रवाहों के लिए दोनों का समर्थन करने के लिए भुगतान करते हैं। यदि नहीं, तो संभवतः वे compose हैं, और सही डिज़ाइन अक्सर दोनों का उपयोग करता है।
एक काम किया हुआ composition: AP2 + x402 स्टैक। यह क्रिप्टो-नेटिव पैटर्न है, जो अब B2B और agent-टू-agent प्रवाह में आम है:
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 से प्रति-protocol tools बनाती है। ये tools (a2a_discover_partners, ap2_create_intent_mandate, और बाकी) अवधारणा 8 से 11 में परिभाषित हैं; यहां आप उन्हें केवल एक agent पर तार देते हैं।
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 की निचली पंक्ति: Protocols विभिन्न layers compose पर: AP2 प्लस x402, ACP प्लस x402, MCP प्लस x402। Protocols उसी layer पर प्रतिस्पर्धा करें: AP2 बनाम ACP SPT, ACP बनाम UCP, x402 बनाम MPP। परीक्षण है "क्या ये एक ही layer पर हैं?" यदि हां, तो एक चुनें. यदि नहीं, तो संभवतः वे रचना करेंगे। AP2 प्लस x402 stack मानक क्रिप्टो-देशी B2B संरचना है।
संकल्पना 14: लागत और विलंबता, जो चुनाव को बाध्य करती है
एक पंक्ति में: लेन-देन का आकार और आपके द्वारा स्वीकार किया जाने वाला इंतजार settlement protocol तय करता है, क्योंकि कार्ड शुल्क छोटे भुगतानों को कुचल देता है और धीमी गति से checkout तंग लूप को तोड़ देता है।
प्रत्येक composition की एक कीमत और एक गति होती है। ACP प्लस card rails पर एक consumer-shopping प्रवाह की लागत लगभग 2.9% + $0.30 प्रति लेनदेन है और शुरू से अंत तक 5 से 30 सेकंड लगते हैं। x402 पर एक API-paying agent की लागत एक सेंट से कम है और इसमें 1 से 2 सेकंड का समय लगता है। सही composition आंशिक रूप से इस बात पर निर्भर करता है कि आपका उपयोग केस कितनी लागत और कितना इंतजार कर सकता है।
रचना के अनुसार प्रति लेनदेन लागत।
| Composition | प्रति लेनदेन विशिष्ट लागत | विशिष्ट विलंबता |
|---|---|---|
| ACP + card rails (consumer shopping) | 2.9% + $0.30 (Stripe दर) | 5 से 30 सेकंड |
| ACP + MPP sessions (सदस्यता) | कार्ड पर 2.9%, या Tempo stablecoin, प्रति session पर लगभग 0.5% | प्रति मीटर कॉल 1 से 3 सेकंड |
| AP2 + x402 (B2B stablecoin) | सब-सेंट गैस, शून्य protocol शुल्क | 2 से 5 सेकंड (mandate signing 1 से 3 जोड़ता है) |
| केवल x402 (API-paying) | सब-सेंट गैस, शून्य protocol शुल्क | 1 से 2 सेकंड |
| केवल MPP sessions (आवर्ती API) | Tempo stablecoin पर शून्य के करीब; कार्ड पर Stripe दर | सक्रिय session के अंदर प्रति मीटर कॉल 50 से 500 एमएस |
पैसा क्या मजबूर करता है। लेनदेन के लगभग 5% से अधिक शुल्क एक समस्या है। $0.05 API कॉल जिसमें कार्ड शुल्क के रूप में 2.9% + $0.30 का भुगतान किया जाता है, उसकी लागत कॉल के मूल्य से अधिक होती है, जो इसके बजाय x402 या MPP stablecoin का उपयोग करने के लिए एक स्पष्ट संकेत है। समान 2.9% + $0.30 का भुगतान करने वाली $50 की टी-शर्ट ठीक है। डॉलर लाइन जहां card rails समझ में आना बंद हो जाती है, वह $ 5 से $ 10 के आसपास है। इसके नीचे, मशीन-भुगतान rails जीत; इसके ऊपर, कार्ड पर chargeback कवर आमतौर पर शुल्क के लायक है।
विलंबता क्या बाध्य करती है। प्रत्येक उपयोगकर्ता-सामना वाले चरण के लिए 5 सेकंड से अधिक प्रतीक्षा करना एक समस्या है। AP2 mandate signing 1 से 3 सेकंड जोड़ सकता है, अगर यह मानव signature पर प्रतीक्षा करता है तो इससे भी अधिक समय; ACP checkout 5 से 30 जोड़ता है। लूप में किसी भी मानव के साथ agent-टू-agent प्रवाह के लिए, बजट अभी भी सख्त है, अक्सर उप-सेकेंड, जो Base पर x402 और Tempo पर MPP को डिफ़ॉल्ट चयन बनाता है।
decision tree, संपीड़ित।
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 की निचली पंक्ति: Composition विकल्पों की वास्तविक लागत और विलंबता है। Card rails की कीमत 2.9% + $0.30 है लेकिन आपको chargeback कवर मिलता है; stablecoin rails की लागत एक सेंट से कम है लेकिन क्रिप्टो-देशी प्लंबिंग की आवश्यकता है। Card rails प्रति लेनदेन $5 से $10 के आसपास अर्थ निकालना बंद करें। ACP checkout उपयोगकर्ता-सामना वाले प्रवाह के लिए लगभग 5 सेकंड में बहुत धीमा हो जाता है। लागत और विलंबता को composition को बाध्य करने दें, स्वाद को नहीं।
भाग 5: decision lab, पाँच कार्यशील उदाहरण
भाग 2 से 4 ने आपको framework दिया: चार layers, कुछ protocols प्रति layer, composition परतों में। भाग 5 पाँच वास्तविक निर्णयों पर आधारित है। प्रत्येक पूर्ण तर्क दिखाता है: layers उपयोग का मामला क्या छूता है, प्रत्येक layer पर कौन सा protocol, क्यों, और agent code कैसा दिखता है।
एक उपयोग के मामले का पूरा स्टैक देखने के लिए एक पंक्ति में पढ़ें। उपयोग के मामले में परिवर्तन होने पर एक layer में क्या परिवर्तन होता है यह देखने के लिए एक कॉलम पढ़ें। नीचे दिए गए पाँच निर्णय पंक्तियों में विस्तार से दिए गए हैं। पहले चार मैट्रिक्स को कवर करते हैं; पांचवां उनमें से एक को पूरी तरह से अलग toolचेन में पुनर्निर्माण करता है ताकि यह साबित हो सके कि framework किसी एक विक्रेता से बंधा नहीं है।
निर्णय 1: Consumer shopping agent (ChatGPT Instant Checkout पैटर्न)
उपयोग का मामला। आप एक agent बना रहे हैं जो लोगों को वॉलमार्ट, Etsy और Shopify विक्रेताओं जैसे ACP-सक्षम merchants पर खरीदारी करने में मदद करता है। उपयोगकर्ता कहता है कि वे क्या चाहते हैं; agent कैटलॉग खोजता है, विकल्प दिखाता है, और पुष्टि पर जाँच करता है। सिंगल buyer से सिंगल merchant, $5 से $500 प्रति ऑर्डर, refunds और chargebacks आवश्यक।
चार परतों पर चलना।
- layer 1 (Discovery). agent को कई व्यापारियों के पास उत्पाद ढूंढने होंगे। आप प्रत्येक merchant के MCP कैटलॉग को एकीकृत कर सकते हैं, या ChatGPT Shopping सतह का उपयोग कर सकते हैं जो पहले से ही ACP व्यापारियों को एकत्रित करता है। विकल्प: AI shopping सतह, क्योंकि discovery का काम पहले ही हो चुका है और एक लाख कैटलॉग को स्वयं वायर करना व्यवहार्य नहीं है।
- परत 2 (Authorization). उपयोगकर्ता सतह में signed है और प्रत्येक खरीद की पुष्टि करता है, इसलिए authorization सरल है। विकल्प: ACP SPT, प्रति खरीदारी Stripe द्वारा निर्धारित, एक merchant, एक राशि और 10 मिनट की विंडो तक सीमित।
- layer 3 (Commerce). पूरा जीवनचक्र मायने रखता है: cart, checkout, fulfillment, disputes, refund। विकल्प: ACP, protocol बिल्कुल इसी के लिए बनाया गया है।
- layer 4 (Settlement). $5 से $500 का मान कार्ड-रेल स्वीट स्पॉट में सही बैठता है, और chargeback कवर शुल्क के लायक है। विकल्प: card rails Stripe के माध्यम से, rail ACP डिफ़ॉल्ट रूप से मानता है।
कार्यान्वयन। यह संकल्पना 8 का code है; tools कॉन्सेप्ट 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",
)
उत्पादन में विफलता की सबसे अधिक संभावना है। Cart बेमेल: agent एक cart बनाता है जो request से मेल नहीं खाता है ("मैंने लाल मांगा, गुलाबी मिला")। ठीक करें: SPT को ढालने से पहले उपयोगकर्ता को cart की पुष्टि करने, cart-सटीकता लॉग करने और सटीकता 95% से कम होने पर निर्देशों को ट्यून करने की आवश्यकता होती है।
इसे टिकाऊ ढंग से चलाना (Inngest)। cart-पुष्टि गेट के लिए कॉन्सेप्ट 8 से step.wait_for_event पैटर्न का उपयोग करें, साथ ही प्रति-उपयोगकर्ता समवर्ती कैप भी।
पहले इसे चुनें। यह आज का लाइव उपयोग मामला है: ChatGPT Instant Checkout, ACP पारिस्थितिकी तंत्र, ACP चालू होने के साथ प्रत्येक Shopify merchant। यदि आप केवल एक composition भेज सकते हैं, तो इसे भेजें।
निर्णय 2: API-paying अनुसंधान agent (केवल x402 पैटर्न)
उपयोग का मामला। आप एक शोध agent का निर्माण कर रहे हैं जो data के लिए तीसरे पक्ष को APIs का भुगतान करता है: वित्तीय फ़ीड, समाचार, विशेष खोज। यह Agent.market जैसी निर्देशिका के माध्यम से runtime पर भुगतान किए गए APIs का पता लगाता है, मूल्य के मुकाबले लागत का वजन करता है, और प्रति कॉल भुगतान करता है। $0.001 से $0.50 की उच्च-आवृत्ति micropayments, कार्य शुरू होने के बाद लूप में कोई मानव नहीं, कोई commerce जीवनचक्र नहीं।
चार परतों पर चलना।
- layer 1 (Discovery). Agent.market और समान x402-paywalled निर्देशिकाएं agent को runtime पर सेवाएं ढूंढने देती हैं; MCP servers x402 समर्थन हैंडल के साथ पूर्व-एकीकृत। विकल्प: agent.मार्केट प्लस MCP-वाया-क्लाउडफ्layer, runtime discovery प्री-वायर्ड फ़ॉलबैक सेट के साथ।
- परतें 2 और 4 (Authorization और Settlement, ढह गईं)। कार्य शुरू होने के बाद कोई मानव नहीं। wallet की on-chain प्रति-लेन-देन खर्च सीमाबद्ध है; उपयोगकर्ता-स्तरीय कैप प्रत्येक भुगतान tool पर SDK
tool_input_guardrailके माध्यम से चलते हैं। EIP-3009 signature authorization और निपटान दोनों है। विकल्प: x402 Base (USDC) पर, बिना किसी अलग mandate protocol के। - परत 3 (Commerce). "खरीदारी" केवल एक API कॉल है। विकल्प: कोई नहीं, x402 के माध्यम से सीधे API पहुंच।
कार्यान्वयन। यह संकल्पना 10 का code है; tools कॉन्सेप्ट 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.
)
उत्पादन में विफलता की सबसे अधिक संभावना है। अटके हुए चक्र से अत्यधिक खर्च: agent उसी data को फिर से लाता है और बजट को ख़त्म कर देता है। ठीक करें: wallet के on-chain कैप (सुरक्षा जो वास्तव में आपकी रक्षा करती है), SDK सत्र-व्यय guardrails, और एक डिडअप कैश ताकि समान फ़ेच दोबारा भुगतान न करें।
इसे टिकाऊ ढंग से चलाना (Inngest)। step.run मेमोइज़ेशन से यहां लाभ मिलता है। सत्र के मध्य में क्रैश हो गया और retry पहले से भुगतान किए गए data के साथ फिर से शुरू हो गया। एक प्रति-उपयोगकर्ता समवर्ती सीमा एक बर्स्ट को कार्यभार संभालने से रोकती है।
शुद्ध मशीन-टू-मशीन। Layers 2 और 4 एक signature में ढह जाते हैं, और Layer 3 खाली है। यह stack निर्णय 1 की तुलना में संरचनात्मक रूप से सरल है: कम protocols, कम एकीकरण बिंदु, प्रति कॉल कम लागत। व्यापार में कोई chargeback कवर नहीं है और कोई commerce शब्दार्थ नहीं है, जो ठीक है क्योंकि उपयोग के मामले में इसकी आवश्यकता नहीं है।
निर्णय 3: Enterprise procurement agent (AP2 प्लस कंपोज्ड-स्टैक पैटर्न)
उपयोग का मामला। आप वित्तीय सेवाओं में विनियमित enterprise के लिए procurement agent का निर्माण कर रहे हैं। खरीदार कार्य सौंपते हैं: "शुक्रवार तक हमारे अनुमोदित आपूर्तिकर्ताओं से $5,000 से कम कीमत में 50 एर्गोनोमिक कीबोर्ड खरीदें।" ऑडिट ट्रेल कानूनी रूप से आवश्यक है, खर्च सीमा कई स्तरों पर चलती है, और आपूर्तिकर्ता पूर्व-अनुमोदित होते हैं, इसलिए कोई runtime खोज नहीं होती है।
चार परतों पर चलना।
- परत 1 (Discovery). आपूर्तिकर्ता सूची पहले से ज्ञात है। विकल्प: आपूर्तिकर्ता कैटलॉग के साथ एक आंतरिक MCP server, क्योंकि discovery का दायरा सीमित है।
- layer 2 (Authorization). non-repudiable ऑडिट ट्रेल वह हिस्सा है जिसे आप छोड़ नहीं सकते हैं; non-repudiable रिकॉर्ड वह है जिसे हस्ताक्षरकर्ता बाद में अस्वीकार नहीं कर सकता है। AP2 mandates बिल्कुल वैसा ही दीजिए। विकल्प: AP2, कार्य निर्माण पर एक Intent Mandate के साथ, checkout से पहले एक Cart Mandate, और settlement पर एक Payment Mandate, प्रत्येक signed procurement अधिकारी द्वारा।
- परत 3 (Commerce). बड़े आपूर्तिकर्ता ACP या UCP का खुलासा करते हैं; छोटे वाले सीधे B2B API को उजागर करते हैं। विकल्प: एसीपी-सक्षम आपूर्तिकर्ताओं के लिए ACP, बाकी के लिए सीधे API; agent दोनों को संभालता है।
- परत 4 (Settlement). आवर्ती आपूर्तिकर्ता MPP sessions का पक्ष लेते हैं; one-off उच्च मूल्यों पर chargeback कवर के लिए card rails खरीदता है। विकल्प: आवर्ती के लिए MPP sessions, one-off के लिए ACP SPT प्लस card rails, आपूर्तिकर्ता इतिहास द्वारा चुना गया।
कार्यान्वयन। यह अवधारणाओं 8, 9, और 11 से tools की रचना करता है।
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 का दायरा बेमेल है: अधिकारी mandate पर हस्ताक्षर करता है, agent काम करता है, तो cart जनादेश में फिट नहीं बैठता है। ठीक करें: agent शुरू होने से पहले mandate स्कोप को मान्य करें shopping (कॉन्सेप्ट 9 का "पहले इरादा Mandates बनाएं"), और उन कार्यों को अस्वीकार करें जिनका दायरा उपयोगकर्ता द्वारा अधिकृत सीमा से अधिक है।
इसे टिकाऊ ढंग से चलाना (Inngest)। AP2 mandate signing step.wait_for_event के लिए प्राकृतिक फिट है। मल्टी-स्टेज कार्य प्रति-उपयोगकर्ता समवर्ती सीमा के साथ, प्रति चरण step.run का उपयोग करते हैं।
विनियमित उद्योग। ऑडिट नियम AP2 को Layer 2 पर लागू करते हैं; कई आपूर्तिकर्ता ACP को बाध्य करते हैं और APIs को Layer 3 पर एक साथ निर्देशित करते हैं; आवर्ती बनाम one-off MPP और कार्डों को Layer 4 पर एक साथ मजबूर करता है। यह composition निर्णय 1 और 2 से भारी है, और ऑडिट आवश्यकता ही वजन को उचित ठहराती है।
निर्णय 4: Multi-agent marketplace (AP2 प्लस x402 प्लस ERC-8004 पैटर्न)
उपयोग का मामला। आप एक ऐसा प्लेटफ़ॉर्म बना रहे हैं जहां agents अन्य agents को नियुक्त करता है। Agent A को शोध की आवश्यकता है; Agent B अनुसंधान को x402 सेवा के रूप में बेचता है। कोई भी अभी तक दूसरे पर भरोसा नहीं करता है, लेन-देन सत्यापन योग्य होना चाहिए, और भुगतान बिना किसी कार्ड के शुद्ध क्रिप्टो-मूल है। Agent से agent, $0.10 से $100 प्रति लेनदेन, दोनों पक्षों को सत्यापन योग्य पहचान की आवश्यकता है।
चार परतों पर चलना।
- परत 1 (Discovery). Agent B अपनी क्षमता को A2A पर प्रकाशित करता है; Agent A इसे ढूंढता है। विकल्प: A2A, इसके लिए बनाया गया protocol।
- परत 2 (Authorization). लेन-देन के समय कोई मानव नहीं, लेकिन विश्वास दोनों तरीकों से सत्यापन योग्य होना चाहिए। AP2 mandates उपयोगकर्ता की सहमति साबित करें; ERC-8004 Agent B को on-chain प्रतिष्ठा देता है Agent A पहले जांच कर सकता है। विकल्प: पूर्ण द्विपक्षीय सत्यापन के लिए AP2 प्लस ERC-8004, composed।
- परत 3 (Commerce). कोई cart नहीं, कोई refunds, बस "यह कार्य करें और रिपोर्ट वितरित करें।" विकल्प: कोई नहीं, सीधा A2A request और प्रतिक्रिया।
- परत 4 (Settlement). क्रिप्टो-मूल, उप-सेकंड, कोई chargeback कवर की आवश्यकता नहीं है। विकल्प: x402
a2a-x402एक्सटेंशन के माध्यम से AP2 तक।
कार्यान्वयन। यह A2A खोज के साथ अवधारणा 9 और 10 से tools बनाता है।
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 स्कोर श्रव्य हैं लेकिन एक ऑपरेटर छोटी सफल नौकरियों के साथ इसे बढ़ा सकता है। ठीक करें: प्रतिष्ठा को अन्य संकेतों (ऑपरेटर identity, लेन-देन-मात्रा सीमा, dispute इतिहास) के साथ संयोजित करें, और पहली बार प्रतिपक्षियों के लिए एक निर्धारित राशि से ऊपर मानव समीक्षा जोड़ें।
इसे टिकाऊ ढंग से चलाना (Inngest)। एक साथ कई विशेषज्ञों को काम पर रखने पर फैन आउट; प्रत्येक परिणाम के लिए step.wait_for_event और प्रति चरण step.run का उपयोग करें। यह निर्णय प्रत्येक Inngest आदिम को छूता है।
शुद्ध बहु-agent अर्थव्यवस्था। लेन-देन के समय लूप में कोई भी इंसान नहीं; दोनों agents pre-authorized दायरे के अंदर कार्य करते हैं। agent अर्थव्यवस्था इसी आकार के आसपास बनाई जा रही है, और इसमें सबसे अधिक विफलता के तरीके हैं, क्योंकि बिना किसी पूर्व संबंध के द्विपक्षीय विश्वास कठिन है और protocol stack केवल आंशिक रूप से ही इसका समाधान करता है।
निर्णय 5: एक गैर-Stripe, गैर-ओपनAI stack (framework यात्रा को साबित करना)
अब तक प्रत्येक code नमूने में stripe.PaymentTokens.create(...) और OpenAI Agents SDK का उपयोग किया गया है। वे ACP के लिए सबसे परिपक्व एकीकरण हैं और SDK इस कोर्स का runtime है, लेकिन चार-परत वास्तुकला डिजाइन द्वारा स्टैक-अज्ञेयवादी है, और एक कोर्स जो केवल एक stack दिखाता है, उसने यह साबित नहीं किया है। तो यह निर्णय निर्णय 2, API-paying अनुसंधान agent को एक पूरी तरह से अलग toolचेन पर पुनर्निर्माण करता है: Google का Agent डेवलपमेंट किट (ADK) runtime के लिए, एक Coinbase smart-contract wallet on-chain identity, AP2 mandates authorization के लिए, और निपटान के लिए सीधे x402। शून्य Stripe, शून्य OpenAI।
उपयोग का मामला निर्णय 2 पर कायम है। एक शोध agent प्रति कॉल $0.001 से $0.10 का भुगतान करता है, जिसकी सीमा प्रति सत्र $10 है। उप-डॉलर, authorization, machine-to-machine निपटान के बाद कोई मानव नहीं। आर्किटेक्चर निर्णय 2 का भी बना रहता है: x402 Layers 2 और 4 को ध्वस्त कर देता है, खोज के लिए कोई commerce layer, MCP नहीं है। केवल library बदलता है।
नीचे दिया गया ब्लॉक उदाहरणात्मक है। Google ADK संरचना (
Agent, tool डेकोरेटर) वास्तविक है औरgoogle-adkएक वास्तविक पैकेज है। भुगतान टुकड़े स्टैंड-इन हैं: AP2 का वास्तविक पैकेजap2है जिसमें बहुत अलग mandate फ़ील्ड हैं और कोईMandateSignerवर्ग नहीं है, Coinbase wallet कोcoinbase_agentkitकेSmartWalletProviderऔर एक लाइव के माध्यम से कॉन्फ़िगर किया गया है x402 कॉल के लिए एक वित्त पोषित account और एक वास्तविक 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 code, दाईं ओर निर्णय 5 का Google ADK प्लस Coinbase code। यह तालिका लाभप्रद है: प्रत्येक पंक्ति एक अलग नाम के तहत एक ही अवधारणा है।
| निर्णय 2 (OpenAI + Stripe) | निर्णय 5 (Google ADK + Coinbase) | समान अवधारणा, भिन्न library |
|---|---|---|
from agents import Agent, function_tool | from google.adk import Agent + from google.adk.tools import function_tool | Agent runtime |
@function_tool (OpenAI Agents SDK) | @function_tool (Google ADK) | Tool डेकोरेटर |
RunContextWrapper | context={...} क्वार्ग से run_async | प्रति-रन अवस्था |
कैप के लिए stripe.Customer.modify(...) | SmartWalletProvider(spend_limits={...}) | खर्च कैप्स, चेन-देशी |
tool_input_guardrail डेकोरेटर | इन-tool चेक + wallet कैप्स | निष्पादन पूर्व सत्यापन |
Runner.run(agent, ...) | agent.run_async(...) | Agent निष्पादन |
क्या समान रहता है। आर्किटेक्चर: Layer 1 MCP या एक निर्देशिका है, Layer 2 एक mandate प्लस wallet कैप्स है, Layer 3 कोई नहीं है (machine-to-machine ढह जाता है commerce), Layer 4 x402 है। primitives: Intent Mandate, EIP-3009 signatures, 402 प्रतिक्रियाएं, भुगतान-हस्ताक्षर headers, on-chain खर्च सीमा। framework वह है जो library स्वैप से बचता है।
दो वास्तविक परिचालन अंतर।
- Google ADK में कोई प्रथम श्रेणी tool input guardrail नहीं है (2026 के मध्य तक)। SDK का
tool_input_guardrailवास्तव में पूर्व-निष्पादन जांच के लिए उपयोगी है; ADK के tool डेकोरेटर का अभी तक कोई प्रत्यक्ष समकक्ष नहीं है। समाधान wallet के on-chain कैप्स द्वारा समर्थित इन-tool सत्यापन है। टोपियाँ अभी भी आपकी रक्षा करती हैं; इन-tool जांच तेजी से विफल हो जाती है। ADK चुनें और आप एक अलग मल्टी-agent कहानी के लिए guardrail सुविधा का व्यापार करते हैं। - AP2 mandate signing यहां अधिक मूल है। Google ने AP2 बनाया है, इसलिए ADK पारिस्थितिकी तंत्र जनादेश-हस्ताक्षर UI प्रवाह को अधिक स्पष्ट रूप से एकीकृत करता है। यदि आपका उपयोग मामला अनिवार्य-कठोर authorization (निर्णय 3 और 4) पर निर्भर करता है, तो ADK प्लस AP2 एक वास्तविक विकल्प है, न कि केवल एक विकल्प।
निर्णय 5 की निचली पंक्ति: चार-परत वास्तुकला छिपी हुई Stripe-एंड-ओपनAI कहानी नहीं है। Discovery, Authorization, Commerce, Settlement, प्रति layer एक protocol चुनें, इसे उपयोग के मामले में उचित ठहराएं: जो किसी भी library स्वैप से बचता है। निर्णय 5 ने निर्णय 2 के समान ही composition बनाने के लिए Google ADK और एक Coinbase wallet का उपयोग किया; केवल आयात बदल गया। यदि एक framework को एक अलग stack में व्यक्त नहीं किया जा सकता है, तो यह एक पोशाक पहने हुए library ट्यूटोरियल है। ये वाला नहीं है.
भाग 6: Production चिंताएँ: जब सिस्टम लाइव होता है तो आपको क्या मारता है
भाग 1 से 5 तक framework का निर्माण किया और वास्तविक निर्णय लिए। भाग 6 उन चीज़ों को शामिल करता है जो यह तय करती हैं कि आपका stack वास्तविक उपयोगकर्ताओं तक जीवित रहेगा या नहीं। ये वे विफलताएं हैं जो डेमो में दिखाई नहीं देतीं और रात 2 बजे दिखाई देती हैं।
यदि आप समझने के लिए पढ़ रहे हैं, भेजने के लिए नहीं, तो आप भाग 6 को पढ़ सकते हैं। यदि आप इसमें से कुछ भी वास्तविक रूप से बना रहे हैं, तो यह वह जगह है जहाँ यह वास्तविक हो जाता है। यहां चार अवधारणाएं काम करने वाली प्रणाली और बटुए को खत्म करने वाली प्रणाली के बीच अंतर हैं।
संकल्पना 15: Spend-limit तीन वास्तुशिल्प स्तरों पर प्रवर्तन
एक पंक्ति में: तीन स्वतंत्र स्थानों पर सीमा लागू करके एक agent को अधिक खर्च करने से रोकें, ताकि एक में एक बग अन्य दो द्वारा पकड़ा जा सके।
एक agent-commerce प्रणाली के बुरी तरह विफल होने का सबसे बड़ा तरीका सरल है: agent अनुमति से अधिक खर्च करता है। एक अटका हुआ agent loop सेकंड में wallet को खत्म कर सकता है। प्रत्येक protocol की अपनी सीमा होती है (ACP की SPT राशि, MPP की session टोपी, x402 की per-request अधिकतम), लेकिन उनमें से कोई भी अपने आप में पर्याप्त नहीं है। Production सिस्टम तीन अलग-अलग स्तरों पर spend limits लागू करते हैं।
स्तर 1: wallet और payment-method सीमाएं। यह वह टोपी है जो वास्तव में आपकी सुरक्षा करती है। agent के smart-contract wallet (x402 के लिए) या इसके Stripe ग्राहक account (ACP और MPP के लिए) बुनियादी ढांचे के स्तर पर निर्धारित खर्च सीमा रखता है। श्रृंखला या Stripe उन्हें लागू करती है चाहे agent code कुछ भी करे। यह एकमात्र स्तर है जो तब कायम रहता है जब agent loop पूरी तरह से विफल हो जाता है।
x402 के लिए smart-contract wallet के साथ:
नीचे दिया गया
SmartContractWallet.deploy(...)कॉल उदाहरणात्मक है। यह दिखाता है कि लेवल 1 कैप कहां रहते हैं, वास्तविक पिप पैकेज नहीं। व्यवहार में आप इन कैप्स को वास्तविक smart-contract wallet पर सेट करते हैं (उदाहरण के लिए Coinbase AgentKit केSmartWalletProviderके माध्यम से)। त्रिस्तरीय अनुशासन ही वास्तविक पाठ है।
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 guardrail। OpenAI Agents SDK का tool_input_guardrail प्रत्येक भुगतान tool निष्पादित होने से पहले चलता है और कॉल को अस्वीकार कर सकता है। आप इसे अवधारणा 5 में देख चुके हैं: यह किसी भुगतान को होने से पहले रोकने का SDK-देशी तरीका है, और परिवार समय पर चलता है। यहां इसका पूरा इलाज होता है, क्योंकि यह पूरे कोर्स के लिए विहित guardrail ब्लॉक है। नीचे दिया गया code असली है और चलता है।
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
)
SDK में तीन guardrail परिवार हैं। agent को उपयोगकर्ता के पहले संदेश पर इनपुट guardrails चलता है। आउटपुट guardrails अंतिम उत्तर agent पर चलता है। Tool guardrails (tool_input_guardrail और tool_output_guardrail) प्रत्येक कस्टम tool कॉल पर चलते हैं। भुगतान सुरक्षा के लिए आप विशेष रूप से tool_input_guardrail चाहते हैं: यह एकमात्र परिवार है जो भुगतान tool चलने से पहले सक्रिय हो जाता है और इसे ब्लॉक कर सकता है। खर्च को नियंत्रित करने के लिए output_guardrail तक पहुंचना agent-commerce code में सबसे आम गलती है। जब तक आग लगती है, पैसा खत्म हो जाता है।
स्तर 3: एप्लिकेशन और व्यवसाय-तर्क सीमाएं। आपका अपना code उपयोगकर्ता-विशिष्ट नियमों को लागू करता है: प्रति-उपयोगकर्ता दैनिक सीमा, प्रति-श्रेणी सीमा, अनुमत व्यापारी। यहीं पर व्यावसायिक नियम रहते हैं। "यह उपयोगकर्ता किसी भी merchant पर प्रति दिन $500 खर्च कर सकता है, लेकिन असत्यापित पर केवल $50 प्रति दिन।" वह नियम यहीं है, किसी protocol में नहीं। यह code सादा 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 agent SDK में है। लेवल 3 आपके एप्लिकेशन code में है। एक में मौजूद बग को अन्य दो द्वारा पकड़ लिया जाता है। लेवल 1 छोड़ें और एक agent-लूप बग पूरे wallet को खत्म कर सकता है। स्तर 2 को छोड़ें और आप उड़ान के बीच में दौड़ को रद्द करने की शक्ति खो देंगे। स्तर 3 छोड़ें और आप प्रति-उपयोगकर्ता या प्रति-श्रेणी नीति लागू नहीं कर सकते।
जाल केवल protocol कैप्स पर भरोसा कर रहा है। ACP की SPT कैप, MPP की session कैप, और x402 की per-request अधिकतम protocol-स्तर की सीमाएँ हैं। वे विशिष्ट protocol दुरुपयोग को रोकते हैं, लेकिन वे सभी protocol में शामिल नहीं होते हैं। केवल $50 की सीमा वाले ACP SPT का उपयोग करने वाली टीम को कुल $5,000 के लिए लगातार 100 agent बनाने से कोई सुरक्षा नहीं मिलती है। उपरोक्त तीन स्तर सटीक रूप से मौजूद हैं क्योंकि protocol कैप एकत्र नहीं होते हैं।
अवधारणा 15 की निचली पंक्ति: spend limits को तीन स्वतंत्र स्तरों पर लागू करें: wallet या payment-method बुनियादी ढांचा, SDK tool guardrails (
tool_input_guardrailविशेष रूप से, क्योंकि यह प्रत्येक tool से पहले चलता है और इसे ब्लॉक कर सकता है), और एप्लिकेशन बिजनेस लॉजिक। प्रत्येक स्तर अलग-अलग बुनियादी ढांचे का उपयोग करता है, इसलिए एक में बग दूसरे द्वारा पकड़ लिया जाता है। खर्च नियंत्रण के लिए agent-स्तरoutput_guardrailका उपयोग करना सबसे आम गलती है। यह अंतिम उत्तर पर चलता है, बहुत देर हो चुकी है, भुगतान पहले ही हो चुका है। protocol-स्तरीय कैप (SPT, MPP session, x402 per-request) आवश्यक हैं लेकिन पर्याप्त नहीं हैं; वे protocols या रनों में एकत्रित नहीं होते हैं। Production सिस्टम तीनों पर लागू होते हैं।
अवधारणा 16: Agent identity स्वच्छता: कुंजियाँ, wallets, और audit logs
एक पंक्ति में: agent के signing कुंजी अधिकृत खर्च को धोखाधड़ी से अलग करने वाली एकमात्र चीज है, इसलिए आप कुंजी की रक्षा करते हैं, इसे agent के अनुसार अलग करते हैं, इसे घुमाते हैं, और प्रत्येक खर्च को durable स्टोरेज में लॉग करते हैं।
Agent commerce एक विफलता लाता है जो स्वायत्त प्रणालियों के लिए अद्वितीय है: agent का क्रिप्टोग्राफिक identity वह सब है जो वास्तविक खर्च और धोखाधड़ी के बीच खड़ा है। यदि signing कुंजी लीक हो जाती है, तो wallet (या Stripe ग्राहक, या AP2 mandate हस्ताक्षरकर्ता) को तब तक खाली या प्रतिरूपित किया जा सकता है जब तक आप कुंजी को घुमाते नहीं। Identity स्वच्छता आदतों का समूह है जो इसे रोकता है। वहाँ चार हैं।
1. प्रति-agent wallet पृथक्करण। प्रत्येक agent, या agent के प्रत्येक वर्ग को अपना स्वयं का wallet या भुगतान हैंडल मिलता है। विभिन्न नौकरियों के साथ कभी भी agents में signing कुंजियाँ साझा न करें। यदि आपका shopping agent और आपका procurement agent एक wallet साझा करते हैं, तो दोनों में से किसी एक का समझौता समाप्त हो जाता है। अलग wallets लागत लगभग कुछ भी नहीं (एक बार की तैनाती लागत) और सुरक्षा लाभ वास्तविक है।
SmartContractWallet.deploy(...)उदाहरणात्मक है, जैसा कि संकल्पना 15 में है। पैटर्न ही मायने रखता है: प्रति agent वर्ग में एक wallet, कभी साझा नहीं किया गया।
# 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. Key rotation, एक शेड्यूल पर और मांग पर। signing कुंजियों को आधार रेखा के रूप में हर 90 दिनों में घुमाएँ (API कुंजियों के लिए Stripe की सलाह से मेल खाते हुए)। जब कोई agent ऑपरेटर टीम छोड़ता है, जब कोई परिनियोजन signing सतह को छूता है, या जब कुछ गलत दिखता है, तो उन्हें तुरंत घुमाएँ। घूमने की आदत दिनों की सटीक संख्या से अधिक मायने रखती है।
नीचे दिया गया पैटर्न वास्तविक है. client नाम
azure_key_vaultउदाहरणात्मक है; अपने प्रदाता के वॉल्ट SDK का उपयोग करें। मुद्दा यह है कि चाबी तिजोरी में रहती है और आप उपयोग के समय वर्तमान version पढ़ते हैं।
# 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. Audit logs जो दुर्घटना से बच जाता है। प्रत्येक authorization निर्णय durable स्टोरेज में लॉग हो जाता है जो agent के runtime से अलग रहता है: प्रत्येक SPT खनन, प्रत्येक mandate signed, प्रत्येक x402 signature, प्रत्येक MPP session खोला गया। यदि agent क्रैश हो जाता है, तो ऑडिट लॉग अभी भी वहां होना चाहिए। Neon Postgres प्लस Inngest का चरणबद्ध संस्मरण आपको यह देता है; आप अधिकतम स्थायित्व के लिए सीधे ऑब्जेक्ट स्टोरेज (S3 या समकक्ष) पर भी लिख सकते हैं।
ऑडिट-लॉग पैटर्न शिक्षण है। client नाम
neon_clientउदाहरणात्मक है; अपने स्वयं के database 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 वितरित किया गया। ऑडिट लॉग आपको बताता है कि क्या सफल हुआ। Traces आपको बताता है कि क्या हुआ, जिसमें विफल, पुन: प्रयास या रुकी हुई कॉल भी शामिल हैं। agent commerce में पूर्ण trace अक्सर विफल लेनदेन को डीबग करने का एकमात्र तरीका होता है, क्योंकि एक उपयोगकर्ता request एक SDK रन, 5 से 10 tool calls, 2 या 3 protocol HTTP अनुरोधों को पूरा कर सकता है। Stripe webhook जो बाद में आता है, और एक Inngest function जो घंटों बाद फिर से शुरू होता है। एक trace ID के बिना इन सबको एक साथ जोड़े बिना, पोस्टमार्टम असंभव है। नीचे दिया गया OpenTelemetry code वास्तविक, स्थिर OTel API है।
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 के माध्यम से स्वचालित रूप से प्रवाहित होता है। जब इस ऑर्डर पर dispute के लिए Stripe webhook 20 मिनट बाद आता है, तो webhook handler order के metadata में मौजूद trace_id के माध्यम से उसी trace से जुड़ जाता है। एक trace ID, पहले request से dispute रिज़ॉल्यूशन तक, लेनदेन के पूरे जीवन को कवर करता है।
Audit logs और traces अलग-अलग प्रश्नों के उत्तर देते हैं, और आपको दोनों की आवश्यकता है। Audit logs व्यावसायिक प्रश्नों का उत्तर दें ("इस उपयोगकर्ता ने मंगलवार को कितना खर्च किया?")। Traces डिबगिंग प्रश्नों का उत्तर दें ("आदेश abc123 के लिए checkout विफल क्यों हुआ?")। ऑडिट लॉग केवल सफल पथ को रिकॉर्ड करता है; यह कभी भी उस कॉल को कैप्चर नहीं करता है जो काम करने से पहले पांच बार पुनः प्रयास किया गया था, या protocol कॉल जो समय समाप्त होने से पहले 30 सेकंड के लिए रुका हुआ था। वे विफलता आकृतियाँ केवल अंशों में दिखाई देती हैं। traces को छोड़ना क्योंकि आपके पास audit logs है, यह एक गलती है कि प्रत्येक tool किस लिए है।
सबसे आम identity गलती wallet के पते को agent की पहचान के रूप में मानना है। पता सार्वजनिक है: कोई भी इसे भेज सकता है और कोई भी यह सत्यापित कर सकता है कि इससे कोई लेनदेन हुआ है। निजी signing कुंजी identity है, और आप इसे एक कुंजी के रूप में सुरक्षित रखते हैं। जो टीमें signing कुंजियों को पर्यावरण चर (या इससे भी बदतर, स्रोत code में) में रखती हैं, उन्होंने agent के identity को उन रहस्यों तक पहुंच रखने वाले किसी भी व्यक्ति को सौंप दिया है। चाबियाँ तिजोरी में जाती हैं, कभी भी env vars में नहीं।
संकल्पना 16 की निचली पंक्ति: Agent identity क्रिप्टोग्राफ़िक है; signing कुंजी अधिकृत खर्च को धोखाधड़ी से अलग करने वाली एकमात्र चीज़ है। चार आदतें इसकी रक्षा करती हैं। प्रति-agent wallet पृथक्करण, इसलिए एक समझौता प्रत्येक agent को खत्म नहीं करता है। Key rotation एक शेड्यूल पर और मांग पर (90-दिन की बेसलाइन, ट्रिगर पर तत्काल)। Audit logs से durable स्टोरेज जो runtime (Neon Postgres या ऑब्जेक्ट स्टोरेज) से अलग रहता है। पूरे लेन-देन (SDK, httpx, Inngest, और FastAPI के माध्यम से OpenTelemetry) को एक trace ID के साथ वितरित किया गया। Signing कुंजियाँ key vault में जाती हैं, पर्यावरण चर या स्रोत code में कभी नहीं। Audit logs व्यावसायिक प्रश्नों के उत्तर दें; traces डिबगिंग प्रश्नों का उत्तर दें; आपको दोनों की जरूरत है.
अवधारणा 17: चार protocols में Dispute और refund यांत्रिकी
एक पंक्ति में: प्रत्येक protocol, disputes और refunds को अलग-अलग तरीके से संभालता है, और आपके उपयोग के मामले में dispute model अक्सर सबसे मजबूत चीज होती है जो यह तय करती है कि आप कौन सा protocols बनाते हैं।
चार protocols प्रत्येक disputes और refunds को अपने तरीके से व्यवहार करते हैं, और यह अंतर अक्सर उपयोग के मामले के लिए protocol विकल्प तय करता है। एक उपयोग मामला जिसे chargeback सुरक्षा की आवश्यकता है वह शुद्ध x402 पर नहीं चल सकता है। ऐसा उपयोग मामला जहां seller में कोई ग्राहक-सेवा सेटअप नहीं है, एसीपी का उपयोग नहीं किया जा सकता है। यहां बताया गया है कि प्रत्येक व्यक्ति dispute को कैसे संभालता है, इसलिए आप protocol को उस dispute model से मिला सकते हैं जिसकी आपको वास्तव में आवश्यकता है।
ACP: कार्ड नेटवर्क के माध्यम से disputes। क्योंकि merchant ACP में रिकॉर्ड का merchant रहता है, प्रत्येक मानक card-network dispute पथ काम करता है। buyer का बैंक chargeback प्रारंभ करता है; Stripe (या जो भी प्रोसेसर) merchant की सुरक्षा संभालता है; merchant अपनी मौजूदा refund नीति का पालन करता है। यह ACP का सबसे बड़ा व्यावहारिक लाभ है। प्रत्येक retail buyer की रिटर्न के बारे में अपेक्षा बस काम करती है।
ACP refund के लिए agent प्रारंभ होता है:
acp_client.refunds.create(...)इस पाठ्यक्रम में अन्य ACP client कॉल की तरह उदाहरणात्मक है। परिणाम model और tool वायरिंग वास्तविक हैं।
@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: disputes ऑडिट ट्रेल के माध्यम से तय हुआ। dispute में AP2 का योगदान mandate श्रृंखला (इरादा, फिर Cart, फिर भुगतान) है। जब एक dispute सामने आता है, तो वह श्रृंखला इस बात का प्रमाण होती है कि उपयोगकर्ता ने वास्तव में क्या अधिकृत किया है, और यह कानूनी रूप से कायम है। यह अंतर्निहित rail के dispute पथ को प्रतिस्थापित नहीं करता है: यदि AP2 mandate ने Stripe के माध्यम से कार्ड भुगतान को अधिकृत किया है, तो Stripe की dispute प्रक्रिया अभी भी लागू होती है। AP2 इस बात का प्रमाण जोड़ता है कि उपयोगकर्ता किस बात पर सहमत हुआ।
dispute प्रवाह:
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: कोई औपचारिक dispute तंत्र नहीं। शुद्ध x402 भुगतान डिजाइन के अनुसार गैर-वापसी योग्य हैं। भुगतान एक से दो सेकंड में on-chain का निपटान हो जाता है; कोई chargeback नहीं है. यह x402 की सबसे बड़ी व्यावहारिक सीमा है। यह $0.001 API कॉल के लिए ठीक है (dispute की कीमत भुगतान से अधिक होगी) और किसी भी चीज़ के लिए गलत है जहां buyer उचित रूप से refund चाहता है।
x402 की नो-refund संपत्ति को नरम करने के तीन तरीके:
- एस्क्रो। उच्च-मूल्य वाले x402 भुगतान के लिए, एक smart-contract एस्क्रो का उपयोग करें जो buyer द्वारा स्वीकृति का संकेत मिलने तक धनराशि को अपने पास रखता है। ERC-8004 में मल्टी-agent लेनदेन के लिए एस्क्रो primitives शामिल है।
- Compose AP2 और एक अलग रेल के साथ। यदि आपको x402 की गति की आवश्यकता है लेकिन dispute समर्थन की भी आवश्यकता है, तो AP2 प्लस x402 composition आपको सबूत के रूप में mandate श्रृंखला देता है। x402 settlement को तेज़ रखता है। settlement स्वयं अभी भी गैर-प्रतिवर्ती है; mandate बस वही साबित करता है जिस पर सहमति हुई थी।
- Seller गारंटी। भुगतान किए गए APIs के लिए, seller की शर्तों में अक्सर refund लागू off-chain नियम शामिल होते हैं (यदि सेवा विफल हो जाती है तो seller स्वेच्छा से USDC को वापस भेज देता है)। यह प्रतिष्ठित विक्रेताओं के लिए काम करता है और गुमनाम विक्रेताओं के साथ अलग हो जाता है।
MPP: Stripe के माध्यम से disputes। MPP sessions card rails पर बसे, Stripe का मानक dispute मशीनरी प्राप्त करते हैं, जो एसीपी के समान है। MPP sessions stablecoin द्वारा Tempo पर, या Lightning द्वारा तय किया गया, Stripe का seller-side dispute रिज़ॉल्यूशन से गुजरें। Stripe रेल की परवाह किए बिना परिणाम के लिए merchant को जिम्मेदार रखता है।
आपको जिस dispute model की आवश्यकता होती है वह अक्सर composition को लागत या विलंबता से अधिक चलाता है। consumer-shopping प्लेटफ़ॉर्म को chargebacks की आवश्यकता होती है, इसलिए ACP फिट बैठता है। एक शुद्ध machine-to-machine API marketplace को बिल्कुल भी disputes की आवश्यकता नहीं है, इसलिए x402 फिट बैठता है। एक enterprise procurement प्लेटफ़ॉर्म को ऑडिट-ग्रेड साक्ष्य की आवश्यकता होती है, इसलिए AP2 किसी भी settlement rail के साथ फिट बैठता है।
संकल्पना 17 की निचली पंक्ति: Dispute और refund यांत्रिकी protocol में तेजी से भिन्न हैं। ACP को card-network chargebacks विरासत में मिला है, इसलिए merchant की मौजूदा रिटर्न नीति काम करती है। AP2 कानूनी साक्ष्य के रूप में mandate श्रृंखला प्रदान करता है लेकिन अंतर्निहित rail के dispute पथ को प्रतिस्थापित नहीं करता है। x402 डिज़ाइन के अनुसार गैर-वापसी योग्य है: micropayments के लिए ठीक है, जहां refunds मायने रखता है वहां गलत है। MPP को रेल पटरियों पर Stripe से dispute मशीनरी विरासत में मिली है। आपके उपयोग के मामले में dispute model अक्सर protocol संरचना को मजबूर करने वाली सबसे मजबूत चीज है।
अवधारणा 18: FastAPI और Inngest webhook प्लंबिंग: request और response लूप को बंद करना
एक पंक्ति में: कुछ भुगतान ईवेंट अपने समय पर आते हैं (disputes, mandate signatures, seller-side भुगतान अनुरोध), इसलिए आपको उन्हें पकड़ने के लिए एक पतले FastAPI हैंडलर और काम को durable वर्कफ़्लो में ले जाने के लिए एक Inngest ईवेंट की आवश्यकता होती है।
भाग 1 से 5, और अवधारणा 15 से 17 तक, agent को buyer के रूप में माना जाता है: यह एक request भेजता है, protocol उत्तर देता है, परिणाम के बारे में SDK कारण बताता है। लेकिन agent commerce दोनों तरफ चलता है। Stripe charge.dispute.created webhook भेजता है। AP2 mandate signing आपके server से उपयोगकर्ता के डिवाइस पर होता है, और बाद में वापस पोस्ट करता है। x402 विक्रेताओं को एक server-साइड middleware की आवश्यकता होती है जो 402 Payment Required लौटाता है और X-PAYMENT हेडर की जांच करता है। इनमें से कोई भी एक Runner.run() कॉल के अंदर फिट नहीं बैठता। उन्हें HTTP सीमा के रूप में FastAPI हैंडलर और durable वर्कफ़्लो में वापस पुल के रूप में Inngest इवेंट की आवश्यकता है।
यह अवधारणा उन तीन पैटर्न पर चलती है जिनकी आपको उत्पादन में आवश्यकता होगी। उनके बिना, सिस्टम में दरारें हैं जहां एसिंक घटनाएं घटती हैं।
पैटर्न 1: एक Stripe webhook एक निलंबित Inngest function में प्रवाहित हो रहा है। जब कोई उपयोगकर्ता ACP ऑर्डर पर chargeback फाइल करता है, तो Stripe आपके endpoint पर charge.dispute.created भेजता है। यह ऑर्डर के पांच मिनट बाद या 60 दिन बाद पहुंच सकता है। ऑर्डर देने वाला वर्कफ़्लो बहुत पहले ही समाप्त हो चुका है, लेकिन agent को अभी भी प्रतिक्रिया देने की आवश्यकता है: merchant को सूचित करें, ऑडिट के लिए लॉग इन करें, शायद एक बचाव बनाएं। FastAPI हैंडलर webhook को Inngest इवेंट में बदल देता है, और एक Inngest function इसे उठाता है और विवाद को संभालने के लिए एक agent चलाता है।
stripe.Webhook.construct_event(...)औरstripe.error.SignatureVerificationErrorवास्तविक Stripe API हैं। Inngest वायरिंग असली है। फायरिंग API पर ध्यान दें: घटनाएँsend(events=[inngest.Event(...)])के रूप में सामने आती हैं, कोई स्पष्ट निर्देश नहीं।
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()}}
FastAPI हैंडलर पतला रहता है (सत्यापित करें, फिर किसी ईवेंट को सक्रिय करें)। Inngest function durable (idempotency, retries, चरण ज्ञापन) है। agent का तर्क Inngest function के अंदर होता है, webhook हैंडलर के अंदर कभी नहीं। यह विभाजन मायने रखता है क्योंकि Stripe लगभग पांच सेकंड के भीतर 2xx response की उम्मीद करता है, और agent रन में 30 या अधिक समय लग सकता है।
पैटर्न 2: एक AP2 अधिदेश-हस्ताक्षर callback जो निलंबित step.wait_for_event को फिर से शुरू करता है। संकल्पना 9 में AP2 signing tool को signature मांगते हुए और प्रतीक्षा करते हुए दिखाया गया है। production में वह signing आपके server से होता है: उपयोगकर्ता अपना फ़ोन ऐप खोलता है, mandate देखता है, स्वीकृत पर टैप करता है, और signed mandate वापस पोस्ट करता है। agent के Inngest वर्कफ़्लो को step.wait_for_event पर निलंबित कर दिया गया था; FastAPI callback उस घटना को सक्रिय करता है जो इसे जगाती है।
signing callback आपका अपना FastAPI मार्ग है। Inngest सहसंबंध
if_exp=(एक CEL अभिव्यक्ति) का उपयोग करता है, और प्रतीक्षित payloadasync.उपसर्ग के अंतर्गत है।wait_for_eventटाइमआउट परNoneलौटाता है।ap2_verify_signatureऔर दृढ़ता client उदाहरणात्मक हैं; वर्कफ़्लो का आकार वास्तविक है.
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}}
Inngest का step.wait_for_event if_exp के साथ इसके लिए बनाया गया है। FastAPI हैंडलर HTTP से Inngest की इवेंट बस तक एक तरफा पुल है। घंटों पहले निलंबित किया गया वर्कफ़्लो signed payload के साथ फिर से शुरू होता है, और agent वहीं से शुरू होता है जहां यह रुका था।
पैटर्न 3: x402 seller-side middleware (जब आप भुगतान किए गए API को उजागर करते हैं, तो न केवल एक का उपभोग करें)। multi-agent marketplace (निर्णय 4) में, आपका agent कभी-कभी buyer और कभी-कभी seller होता है, जहां अन्य agents अनुसंधान, विश्लेषण या code के लिए अपना भुगतान करें। seller पक्ष को एक FastAPI middleware की आवश्यकता है जो 402 Payment Required लौटाता है, X-PAYMENT headers की जांच करता है, और केवल एक बार facilitator द्वारा भुगतान सत्यापित करने के बाद ही संसाधन प्रदान करता है।
नीचे दिया गया seller-side
X402Middlewareउदाहरणात्मक है; कोईx402_serverPyPI पैकेज नहीं है। वास्तविक server-साइड x402x402पैकेज के server और facilitator हेल्पर्स और framework एकीकरण के माध्यम से आता है। सममित खरीदार-और-विक्रेता विचार वास्तविक है, और 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 से buyer-side code और यहां seller-side middleware एक ही protocol के दो हिस्से हैं। एक multi-agent marketplace दोनों चलाता है: इसका agents बाहरी सेवाओं से खरीदता है और बाहरी agents को बेचता है।
production में तीन विफलताएँ दोहराई जाती हैं:
- Webhook handlers बिजनेस लॉजिक इनलाइन कर रहा है। एक FastAPI हैंडलर जो webhook response के अंदर agent चलाता है, Stripe के पांच सेकंड के टाइमआउट को पार कर जाएगा। Stripe retries, agent दो बार चलता है, और आप उपयोगकर्ता से दो बार शुल्क लेते हैं। हैंडलर पतला रहता है; Inngest function टिकाऊ है।
- webhook निष्क्रियता को भूल जाना। Stripe retries उसी
event.idके साथ विफल डिलीवरी। Inngest function परidempotencyकुंजी के बिना, प्रत्येक retry एक डुप्लिकेट बनाता है।"event.data.raw_event_id"को idempotency कुंजी के रूप में उपयोग करें। - कॉलबैक पर कोई signature जाँच नहीं। AP2 अधिदेश-हस्ताक्षरित callbacks को पंजीकृत सार्वजनिक कुंजी के विरुद्ध उपयोगकर्ता के signature को सत्यापित करना होगा। अन्यथा कोई भी कॉल करने वाला व्यक्ति जनादेश-हस्ताक्षरित घटनाओं को जाली बना सकता है। एक विफल चेक 400 लौटाता है, लॉग की गई चेतावनी नहीं।
संकल्पना 18 की निचली पंक्ति: Agent commerce द्विदिशात्मक है। Protocol प्रतिक्रियाएँ समकालिक रूप से आती हैं और SDK उन्हें संभालता है, लेकिन disputes, mandate signatures, refunds, और seller-side भुगतान अनुरोध webhooks और कॉलबैक के माध्यम से अतुल्यकालिक रूप से आते हैं। तीन पैटर्न परिचालन आवश्यकता को कवर करते हैं। एक Stripe webhook handler एक Inngest ईवेंट को durable agent वर्कफ़्लो में disputes और refund के लिए सक्रिय करता है। एक AP2 अधिदेश-हस्ताक्षरित callback एक Inngest ईवेंट को सक्रिय करता है जो आउट-ऑफ-बैंड हस्ताक्षर के लिए निलंबित
step.wait_for_eventको फिर से शुरू करता है। एक x402 seller-side FastAPI middleware सत्यापित भुगतान के साथ भुगतान किए गए APIs को उजागर करता है। FastAPI हैंडलर पतले रहते हैं (सत्यापित करें और फायर करें); Inngest functions durable (निष्क्रिय और पुन: प्रयासित) हैं। भाग 1 से 5 तक buyer-side फ़्रेमिंग इन तीनों के बिना अधूरी है; production सिस्टम तीनों को चलाते हैं।
भाग 7: समापन: यह पाठ्यक्रम वास्तव में क्या सिखा रहा था
संकल्पना 19: स्तरित composition का अनुशासन
एक पंक्ति में: इस पाठ्यक्रम में सब कुछ एक काम में सिमट जाता है: उपयोग के मामले को पढ़ें, इसे चार layers में तोड़ें, और प्रत्येक परत पर सही protocol चुनें।
इस पाठ्यक्रम में 19 अवधारणाएँ और 5 निर्णय हैं। वे सभी एक दावे के लिए मंच तैयार कर रहे हैं: 2026 में agent commerce एक एकल protocol नहीं है, बल्कि एक स्तरित वास्तुकला है, और आपका काम आपके सामने उपयोग के मामले के लिए प्रत्येक layer पर सही protocol चुनना है। बाकी सब कुछ उसी से चलता है।
एक ही आकृति तीन पैमानों पर दिखाई देती है।
protocol स्केल पर, चार शीर्षक protocols अलग-अलग layers पर अलग-अलग समस्याओं का समाधान करते हैं: ACP Layer 3 पर, AP2 Layer 2 पर, x402 और MPP Layer पर 4. उन्हें एक ही layer पर प्रतिद्वंद्वी मानना सबसे आम वास्तुशिल्प गलती है। वे केवल वहीं प्रतिस्पर्धा करते हैं जहां उनका layers ओवरलैप होता है (settlement पर MPP के विरुद्ध x402; कुछ प्रवाह के लिए authorization पर ACP के SPT के विरुद्ध AP2)। बाकी हर जगह वे रचना करते हैं।
सिस्टम स्केल पर, एक production सिस्टम में प्रत्येक layer से एक protocol होता है, जो यूनिवर्सल client के रूप में OpenAI Agents SDK के माध्यम से एक साथ जुड़ा होता है। SDK का @function_tool, RunContextWrapper, और tool_input_guardrail प्रत्येक परत पर चिंताओं को स्पष्ट रूप से मैप करता है। SDK एक protocol नहीं है. यह orchestrator है जो आपको compose protocols को साफ-सुथरा रखने की सुविधा देता है।
अनुशासन पैमाने पर, आपका काम एक उपयोग के मामले को पढ़ना है, इसे चार layers में विभाजित करना है, प्रत्येक में सही protocol चुनना है, और उपयोग के मामले की वास्तविक बाधाओं के खिलाफ प्रत्येक विकल्प को उचित ठहराना है: लेनदेन मूल्य, विलंबता बजट, dispute model, ऑडिट आवश्यकताएं। काम "पसंदीदा protocol चुनना" नहीं है। यह "इस उपयोग के मामले में, प्रत्येक layer क्या मांग करता है?"
भाग 5 के पाँच निर्णयों ने इस अनुशासन के माध्यम से वास्तविक उपयोग के मामलों को आगे बढ़ाया। निर्णय 1 (consumer shopping) ACP प्लस Stripe card rails पर उतरा, क्योंकि उपयोग के मामले में chargeback सुरक्षा की आवश्यकता थी। निर्णय 2 (एक API-paying agent) केवल x402 पर उतरा, क्योंकि Layers 2 और 4 machine-to-machine प्रवाह के लिए ढह गए। निर्णय 3 (enterprise procurement) सबसे जटिल composition (AP2 प्लस ACP प्लस MPP) तक पहुंच गया, क्योंकि ऑडिट और पुनरावृत्ति आवश्यकताओं ने इसे मजबूर किया। निर्णय 4 (एक multi-agent marketplace) AP2 प्लस ERC-8004 प्लस x402 पर उतरा, क्योंकि द्विपक्षीय-विश्वास की आवश्यकता किसी अन्य तरीके से पूरी नहीं की जा सकती थी। निर्णय 5 ने निर्णय 2 को पूरी तरह से अलग stack (Google ADK प्लस एक Coinbase wallet प्लस AP2 प्लस x402) पर फिर से बनाया और उसी चार-परत आकार तक पहुंच गया, जिससे साबित हुआ कि वास्तुकला एक आवरण नहीं है। Stripe और OpenAI।
आप जिस composition तक पहुँचते हैं वह उपयोग के मामले से निर्धारित होता है, स्वाद से नहीं। एक टीम जो x402 को चुनती है क्योंकि "stablecoins भविष्य है" लेकिन एक consumer shopping अनुभव का निर्माण कर रही है, उसकी संरचना गलत है। एक टीम जो ACP को चुनती है क्योंकि "Stripe एंटरप्राइज़-ग्रेड है" लेकिन $0.001 पर API एक्सेस के लिए भुगतान कर रही है, कॉल की संरचना गलत है। उपयोग के मामले को विकल्प चुनने दें।
संकल्पना 19 की निचली पंक्ति, और इस पाठ्यक्रम की: चार protocols (ACP, AP2, x402, MPP) layers हैं, विकल्प नहीं। आपका काम उपयोग के मामले को पढ़ना है, इसे चार layers (discovery, authorization, commerce, settlement) में तोड़ना है, प्रत्येक layer पर सही protocol चुनना है, और उपयोग के मामले की वास्तविक बाधाओं के खिलाफ विकल्प को उचित ठहराना है। OpenAI Agents SDK सार्वभौमिक client है जो चुने हुए protocol बनाता है। अगले 24 महीनों में जो भी protocols जीतेगा, अनुशासन कायम रहेगा। layers स्थिर हैं, भले ही प्रत्येक layer पर protocols विकसित हो।
चीट शीट: एक पेज में framework
इसे प्रिंट करें. इसे दीवार पर टेप कर दें. किसी agent-commerce डिज़ाइन की समीक्षा करते समय इसका उपयोग करें।
चार layers (इस stack को याद रखें)
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?"
प्रत्येक layer पर protocols (2026 में शीर्ष चयन)
| Layer | शीर्ष चयन | द्वारा चुनें |
|---|---|---|
| Discovery | MCP, A2A, agent directories, AI shopping surfaces | जहां agent के आवश्यक सेवाएं रहती हैं |
| Authorization | AP2 mandates, ACP SPT, TAP, ERC-8004 | ट्रस्ट model: ऑडिट-कठोर, Stripe-नेटिव, केवल पहचान, या मल्टी-agent |
| Commerce | ACP, UCP, सीधा API (कोई नहीं) | क्या उपयोग के मामले में commerce जीवनचक्र की आवश्यकता है? |
| Settlement | x402, MPP, card rails, बैंक / Lightning | अर्थशास्त्र: लेनदेन मूल्य rail को संचालित करता है |
चार विहित रचनाएँ
| केस का प्रयोग करें | Stack |
|---|---|
| Consumer shopping | AI सतह + ACP SPT + ACP + Stripe कार्ड |
| API-paying agent | MCP/directory + EIP-3009 + (कोई नहीं) + x402 |
| Enterprise procurement | A2A/MCP + AP2 + ACP/UCP + MPP/cards |
| Multi-agent marketplace | A2A + AP2 + ERC-8004 + (कोई नहीं) + x402 |
Spend-limit तीन स्तरों पर प्रवर्तन (आवश्यक)
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)
इनमें से किसी को भी छोड़ें और आप पूरी तरह बर्बाद होने से एक बग दूर हैं। सबसे आम गलती लेवल 2 के लिए agent-स्तर output_guardrail का उपयोग करना है। यह अंतिम agent उत्तर पर सक्रिय होता है, भुगतान रोकने के लिए बहुत देर हो चुकी है। इसके बजाय 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)
dispute model (अक्सर सबसे मजबूत बाधा)
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
लॉन्च से पहले Production चेकलिस्ट
- wallet/payment-method spend limits लेवल 1 पर कॉन्फ़िगर किया गया
- SDK
tool_input_guardrailप्रत्येक भुगतान-प्राधिकरण tool से जुड़ा हुआ है (स्तर 2) - एप्लिकेशन प्रति-उपयोगकर्ता, प्रति-श्रेणी और प्रति-व्यापारी सीमा लागू करता है (स्तर 3)
- key vault (Azure Key Vault या समतुल्य) में Signing कुंजियाँ, कभी भी env vars में नहीं
- प्रति-agent wallet पृथक्करण (agent वर्गों में कोई साझा कुंजी नहीं)
- Key rotation शेड्यूल परिभाषित (90-दिन की बेसलाइन)
- Audit logs से durable भंडारण agent runtime से स्वतंत्र
- OpenTelemetry traces स्पैन SDK, httpx, Inngest, और FastAPI; प्रति लेनदेन एक trace ID
- प्रत्येक सीमा पर Pydantic models (tool returns, protocol payloads, FastAPI निकाय, Inngest घटनाएँ)
- हर जगह पैसे के लिए
Decimal(कभीfloatनहीं) - Stripe webhook handler signature को सत्यापित करता है और एक Inngest ईवेंट सक्रिय करता है (पतला हैंडलर, durable function)
- AP2 अधिदेश-हस्ताक्षरित callback signature को सत्यापित करता है और
step.wait_for_eventको फिर से शुरू करता है - यदि भुगतान किए गए APIs को उजागर किया जाए: x402 seller-side middleware प्रति रूट कॉन्फ़िगर किया गया है
- Inngest
idempotencyप्रत्येक webhook-ट्रिगर function पर कुंजी सेट - Dispute और refund तंत्र को protocol के अनुसार समझा और प्रलेखित किया गया
- Human-in-the-loop production के पहले 30 दिनों के लिए पुष्टिकरण गेट
- पुष्टिकरण गेट को शिथिल करने से पहले cart-सटीकता मीट्रिक मापी गई
त्वरित संदर्भ: decision tree, संपीड़ित
जब आपके पास कोई नया उपयोग का मामला हो, तो इस पेड़ पर चलें।
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. वह धारणा जो टूट गई
भुगतान प्रणाली इस धारणा पर बनाई गई थी कि एक इंसान खरीद बटन पर क्लिक करता है। Agents इसे तीन तरीकों से तोड़ता है: कोई पारंपरिक identity नहीं, व्यवहार जो असंगत दिखता है, और विवाद को सुलझाने के लिए कोई चैनल नहीं। प्रत्येक ब्रेक को protocol-स्तरीय फिक्स की आवश्यकता होती है। पुराने payment rails को अच्छे agent UX में लपेटने से काम नहीं चला।
2. क्यों एक protocol सभी ब्रेक को हल नहीं कर सकता
एक protocol सभी चार ब्रेक को हल नहीं कर सकता है, क्योंकि ब्रेक अलग-अलग layers पर होते हैं, प्रत्येक के अपने मजबूत पदधारी होते हैं। चार protocols विशेषज्ञ हैं: commerce पर ACP, authorization पर AP2, निपटान पर x402 और MPP। layer के भीतर आप एक चुनें; layers के पार आप कई compose।
3. OpenAI Agents SDK यूनिवर्सल client के रूप में
SDK सभी चार protocol के लिए सार्वभौमिक client है। प्रत्येक protocol एक या अधिक
@function_toolfunctions agent कॉल बन जाता है। SDK काoutput_type,context, औरtool_input_guardrailस्पष्ट रूप से protocol चिंताओं को मैप करता है: structured payment results, प्रति-उपयोगकर्ता भुगतान संदर्भ, और पूर्व-निष्पादन spend-limit जाँच।
4. Layer 1, Discovery (agents कैसे पता लगाएं कि वे क्या खरीद सकते हैं)
Layer 1 उत्तर "क्या उपलब्ध है?" चार विकल्प प्रतिस्पर्धा करते हैं: आंतरिक tool server के लिए MCP, मल्टी-agent इकोसिस्टम के लिए A2A, तृतीय-पक्ष सेवाओं के लिए agent directories, consumer उत्पादों के लिए AI shopping surfaces। वह चुनें जो agent की आवश्यक सेवाओं से मेल खाता हो; वे पारस्परिक रूप से विशिष्ट नहीं हैं।
5. Layer 2, Identity और Authorization (agent को प्रमाणित करने की अनुमति है)
Layer 2 दो प्रश्नों के उत्तर देता है: क्या मानव ने इसे अधिकृत किया है, और क्या agent वह है जो वह होने का दावा करता है? चार protocols प्रतिस्पर्धा करते हैं: AP2 mandates (ऑडिट-कठोर), ACP SPT (धारी-मूल), TAP (केवल पहचान), ERC-8004 (मल्टी-agent ट्रस्ट)। प्रति-tool प्रमाणीकरण के लिए
RunContextWrapperऔर व्यय प्रवर्तन के लिएtool_input_guardrailके माध्यम से एकीकृत करें। विश्वास के अनुसार चुनें model; वे विनिमेय नहीं हैं.
6. Layer 3, Commerce (पूर्ण purchase lifecycle)
Layer 3 हैंडल cart, checkout, fulfillment, dispute, और refund। ACP और UCP consumer प्रवाह के लिए प्रतिस्पर्धा करते हैं; machine-to-machine API एक्सेस में कोई commerce परत नहीं है। Refund और dispute यांत्रिकी छिपी हुई जटिलता है जो वास्तविक commerce protocol को केवल भुगतान वाले से अलग करती है। उपयोग के मामले के अनुसार चुनें: जीवनचक्र आवश्यक (ACP/UCP) या जीवनचक्र छोड़ दिया गया (प्रत्यक्ष API)।
7. Layer 4, Settlement (पैसा वास्तव में चलता है)
Layer 4 वह जगह है जहां पैसा चलता है। चार विकल्प प्रतिस्पर्धा करते हैं: machine-to-machine के लिए x402 stablecoin, multi-rail के लिए MPP बहुत कम शुल्क वाले मामले। चुनाव ज्यादातर पैसे के बारे में है: उप-डॉलर से x402, consumer से कार्ड, enterprise से MPP। Settlement आमतौर पर आपकी commerce पसंद द्वारा निर्धारित किया जाता है; stack के निचले भाग को चुनें, पृथक रेलों को नहीं।
8. ACP, consumer-shopping protocol
ACP, consumer शॉपिंग के लिए उत्पादन के लिए तैयार commerce protocol है। SPT agent के खर्च का दायरा बढ़ाता है; merchant रिकॉर्ड का merchant बना हुआ है। आप इसे Stripe SDK प्लस एक पतले ACP client के माध्यम से एकीकृत करते हैं, जो चार
@function_toolfunctions (ब्राउज़ करें, checkout, स्थिति, refund) के रूप में वायर्ड है। agent के cart-सटीकता को मापने तक cart पर उपयोगकर्ता की पुष्टि डिफ़ॉल्ट है।
9. AP2, authorization layer
AP2 ऑडिट-सख्त agent वाणिज्य के लिए authorization layer है। तीन mandate प्रकार (इरादा, Cart, भुगतान) एक non-repudiable श्रृंखला बनाते हैं जो उपयोगकर्ता की सहमति को साबित करता है।
step.wait_for_eventअधिदेश-हस्ताक्षर प्रवाह के लिए स्वाभाविक रूप से उपयुक्त है। shopping शुरू होने से पहले, पहले इरादा Mandates बनाएं, checkout के बाद के विचार के अनुसार नहीं।
10. x402, HTTP-मूल settlement protocol
x402, machine-to-machine micropayment के लिए HTTP-मूल settlement protocol है। 402 status code प्लस एक signed भुगतान header प्लस एक EIP-3009 signature बिना किसी account निर्माण के एक से दो सेकंड में व्यवस्थित हो जाता है। wallet की smart-contract spend limits वह सुरक्षा है जो वास्तव में आपकी सुरक्षा करती है, per-request कैप नहीं। जिस spec version और facilitator के साथ आप एकीकृत हैं, उसके विरुद्ध header नामकरण की जाँच करें; यह V1 और V2 में भिन्न है।
11. MPP, sessions-based settlement protocol
MPP, Stripe का settlement है, जो x402 का उत्तर है, sessions-based metering और multi-rail डिस्पैच के लिए बनाया गया है। दो इरादे,
charge(one-off) औरsession(pre-authorized स्ट्रीमिंग), एकल खरीदारी और आवर्ती मीटरिंग को कवर करते हैं। HTTP आकार मानकWWW-Authenticate: Payment,Authorization: Payment, औरPayment-Receiptheaders का उपयोग करता है, इसलिए यह परिचित HTTP प्रमाणीकरण जैसा लगता है। अपेक्षित कार्य के लिए सही आकार session कैप, सुविधा के लिए नहीं।
12. न्यूनतम व्यवहार्य agent-भुगतान stack
न्यूनतम व्यवहार्य stack सबसे छोटा composition है जो उपयोग के मामले के लिए मूल्य प्रदान करता है। चार सामान्य: consumer shopping (ACP प्लस कार्ड), API-paying (केवल x402), enterprise procurement (AP2 प्लस ACP/UCP प्लस MPP/cards), multi-agent marketplace (AP2 प्लस ERC-8004 प्लस x402)। सार्वभौमिक ढेर न बनाएं; प्रत्येक उपयोग के मामले में एक composition चुनें और भेजें।
13. जब protocols compose पार layers बनाम layer के भीतर प्रतिस्पर्धा करें
Protocols पार layers compose (AP2 प्लस x402, ACP प्लस x402, MCP प्लस x402); layer के भीतर protocols प्रतिस्पर्धा (AP2 बनाम ACP SPT, ACP बनाम UCP, x402 बनाम MPP)। परीक्षण है "क्या ये एक ही layer पर हैं?" यदि हां, तो एक चुनें; यदि नहीं, तो संभवतः वे रचना करेंगे।
14. composition विकल्पों की लागत और विलंबता निहितार्थ
Card rails लागत 2.9% प्लस $0.30 प्रति लेनदेन लेकिन chargeback सुरक्षा प्रदान करें; stablecoin rails लागत उप-प्रतिशत लेकिन क्रिप्टो-देशी बुनियादी ढांचे की आवश्यकता है। डॉलर बिंदु जहां card rails समझ में आना बंद हो जाता है वह लगभग $5 से $10 है। विलंबता बिंदु जहां ACP checkout बहुत धीमा हो जाता है, उपयोगकर्ता-सामना वाले प्रवाह के लिए लगभग पांच सेकंड है। composition तय करने के लिए लागत और विलंबता का उपयोग करें, अमूर्त प्राथमिकता का नहीं।
15. Spend-limit तीन वास्तुशिल्प स्तरों पर प्रवर्तन
spend limits को तीन स्वतंत्र स्तरों पर लागू करें: wallet या payment-method इंफ्रास्ट्रक्चर, SDK tool guardrails (
tool_input_guardrailविशेष रूप से, क्योंकि यह प्रत्येक tool से पहले चलता है और इसे ब्लॉक कर सकता है), और एप्लिकेशन बिजनेस लॉजिक। प्रत्येक स्तर अलग-अलग बुनियादी ढांचे का उपयोग करता है, इसलिए एक में बग दूसरे द्वारा पकड़ लिया जाता है। खर्च नियंत्रण के लिएoutput_guardrailका उपयोग करना सबसे आम गलती है; यह अंतिम उत्तर पर सक्रिय हो जाता है, भुगतान रोकने में बहुत देर हो जाती है।
16. Agent identity स्वच्छता: चाबियाँ, wallets, और audit logs
Agent identity क्रिप्टोग्राफ़िक है; signing कुंजी अधिकृत खर्च को धोखाधड़ी से अलग करने वाली एकमात्र चीज़ है। चार आदतें: प्रति-agent wallet पृथक्करण, एक शेड्यूल पर और मांग पर key rotation, audit logs से durable भंडारण runtime से स्वतंत्र, और पूरे लेनदेन में एक trace ID के साथ traces वितरित किया गया। Signing कुंजियाँ key vault में जाती हैं, कभी भी env vars या स्रोत code में नहीं।
17. चार protocols में Dispute और refund यांत्रिकी
ACP को card-network chargeback विरासत में मिला है। AP2 कानूनी साक्ष्य के रूप में mandate श्रृंखला प्रदान करता है लेकिन अंतर्निहित rail के dispute पथ को प्रतिस्थापित नहीं करता है। x402 डिज़ाइन के अनुसार गैर-वापसी योग्य है: micropayments के लिए ठीक है, जहां refunds मायने रखता है वहां गलत है। MPP को रेल पटरियों पर Stripe से dispute मशीनरी विरासत में मिली है। आपके उपयोग के मामले में dispute model अक्सर protocol संरचना को मजबूर करने वाली सबसे मजबूत चीज है।
18. FastAPI और Inngest webhook प्लंबिंग: request और response लूप को बंद करना
Agent commerce द्विदिश है: disputes, mandate signatures, refunds, और seller-side भुगतान अनुरोध webhook के माध्यम से अतुल्यकालिक रूप से आते हैं। तीन पैटर्न आवश्यकता को कवर करते हैं: एक Stripe webhook एक Inngest ईवेंट को durable वर्कफ़्लो में सक्रिय करता है; एक AP2 अधिदेश-हस्ताक्षरित callback एक इवेंट को सक्रिय करता है जो
step.wait_for_eventको फिर से शुरू करता है; एक x402 seller-side FastAPI middleware सशुल्क API को उजागर करता है। FastAPI हैंडलर पतले रहते हैं; Inngest functions टिकाऊ हैं। Production सिस्टम तीनों को चलाते हैं।
19. स्तरित composition का अनुशासन
चार protocols (ACP, AP2, x402, MPP) layers हैं, विकल्प नहीं। आपका काम उपयोग के मामले को पढ़ना है, इसे चार layers में विभाजित करना है, प्रत्येक में सही protocol चुनना है, और उपयोग के मामले की वास्तविक बाधाओं के खिलाफ विकल्प को उचित ठहराना है। OpenAI Agents SDK सार्वभौमिक ग्राहक है। अगले 24 महीनों में जो भी protocols जीतेगा, अनुशासन कायम रहेगा; layers स्थिर है, भले ही प्रत्येक layer पर protocols विकसित हो।
डिज़ाइन-समीक्षा टेम्प्लेट: किसी agent-commerce आर्किटेक्चर की समीक्षा करते समय पूछे जाने वाले प्रश्न
जब आप किसी सहकर्मी के डिज़ाइन (या अपने स्वयं के ड्राफ्ट, एक दिन की दूरी के साथ) की समीक्षा करते हैं, तो इन प्रश्नों को क्रम से पूछें। प्रत्येक इस पाठ्यक्रम के एक अनुभाग को मैप करता है; यदि उत्तर प्रश्न को संतुष्ट नहीं करता है, तो उस अनुभाग पर वापस जाएँ।
वास्तु प्रश्न
- यह किस उपयोग के मामले में काम कर रहा है? यदि "एकाधिक" है, तो प्राथमिक क्या है? एक डिज़ाइन जो सभी चार विहित उपयोग मामलों को पूरा करने का प्रयास करता है वह संकल्पना 12 से विरोधी पैटर्न है; इसे ध्वजांकित करें.
- चार layers स्पष्ट रूप से चलें। Discovery? Authorization? Commerce? Settlement? प्रत्येक layer पर कौन सा protocol? चार-protocol composition को ज़ोर से बोलें।
- उपयोग के मामले में प्रत्येक layer की पसंद को उचित ठहराएं। इस layer पर यह protocol क्यों? एक अलग से क्या बदलेगा? संकल्पना 13 का पार-बनाम-भीतर परीक्षण यहां लागू होता है।
- क्या किसी layer पर protocol ओवरलैप है? दो protocols Layer 4 पर प्रतिस्पर्धा कर रहे हैं? Layer 2 पर दो? यदि हां, तो यह जटिलता है जिसे उचित ठहराने के लिए उपयोग के मामले की आवश्यकता है।
आर्थिक प्रश्न
- लेन-देन मूल्य वितरण क्या है? उप-डॉलर? $10 से $100? $1,000 से अधिक? संकल्पना 14 की आर्थिक सीमा को settlement विकल्प को संचालित करना चाहिए।
- विलंबता बजट क्या है? उप-सेकेंड? 5 से 30 सेकंड? विलंबता बजट को settlement और mandate विकल्पों को सीमित करना चाहिए।
- अपेक्षित मात्रा में प्रति लेनदेन लागत क्या है? protocol शुल्क और प्रोसेसर शुल्क तथा प्रति-लेनदेन बुनियादी ढांचा लागत जोड़ें। यह जांचने के लिए इसका उपयोग करें कि composition आर्थिक रूप से व्यवहार्य है।
संचालनात्मक प्रश्न
- Spend-limit तीनों स्तरों पर प्रवर्तन? wallet/payment-method, SDK, एप्लिकेशन व्यवसाय तर्क। संकल्पना 15: किसी को भी छोड़ें और आप उजागर हो जाएंगे।
- Identity स्वच्छता? प्रति-agent wallet पृथक्करण, key rotation, audit logs से durable भंडारण, प्रति लेनदेन एक trace ID के साथ traces वितरित। संकल्पना 16 की चार आदतें।
- Dispute और refund यांत्रिकी? क्या composition आपके उपयोग के मामले में वास्तव में मिलने वाले disputes को संभालता है? संकल्पना 17: यह अक्सर सबसे मजबूत बाधा होती है।
- ऑपरेशनल envelope? Inngest (या समकक्ष durable निष्पादन) लंबे समय तक चलने वाले प्रवाह, retries, और idempotency को कहां संभालता है? Production Worker क्रैश कोर्स में कवर किया गया।
- Human-in-the-loop गेट? प्रवाह में उपयोगकर्ता या ऑपरेटर कहां पुष्टि करता है? उत्पादन के पहले 30 दिनों के लिए पुष्टिकरण गेट पर डिफ़ॉल्ट।
Webhook और एसिंक-कॉलबैक प्रश्न (संकल्पना 18)
- Stripe webhook handler मौजूद है और पतला है? signature को सत्यापित करता है, एक Inngest ईवेंट सक्रिय करता है, पांच सेकंड के अंदर ACK करता है। व्यावसायिक तर्क Inngest function में रहता है, हैंडलर में नहीं।
- AP2 अधिदेश-हस्ताक्षर callback मौजूद है और उपयोगकर्ता signatures को सत्यापित करता है? इसके बिना, agent के
step.wait_for_eventकभी भी फिर से शुरू नहीं होता है। signature सत्यापन के बिना, कोई भी जनादेश-हस्ताक्षरित घटनाओं को जाली बना सकता है। - यदि एक्सपोज़िंग पेड APIs: x402 seller-side middleware प्रति रूट कॉन्फ़िगर किया गया है? मल्टी-agent मार्केटप्लेस buyer-side और seller-side code दोनों चलाते हैं; seller पक्ष को मिडलवेयर की आवश्यकता है।
- प्रत्येक webhook-ट्रिगर function पर Inngest idempotency कुंजियाँ? समान
event.idके साथ Stripe retries; idempotency के बिना आप दो बार चार्ज या refund करते हैं। - अनुबंध layer: Pydantic models प्रत्येक सीमा पर? Tool returns, protocol payloads, FastAPI request और response निकाय, Inngest घटना payloads, सभी टाइप किए गए। पैसे के लिए
Decimal, कभीfloatनहीं।
विफलता-मोड प्रश्न
- production में सबसे अधिक संभावित विफलता मोड क्या है? प्रत्येक विहित निर्णय में एक था: cart बेमेल (निर्णय 1), अनियंत्रित खर्च (निर्णय 2), Intent Mandate स्कोप बेमेल (निर्णय 3), खेल प्रतिष्ठा (निर्णय 4)। आपका क्या है?
- शमन क्या है? भाग 5 में प्रत्येक विफलता मोड में एक स्पष्ट शमन था। क्या डिज़ाइन में यह शामिल है, या यह "protocol इसे संभाल लेगा" पर निर्भर है?
ट्रैक-तत्परता प्रश्न (production परिनियोजन के लिए)
- टीम किस शिक्षण ट्रैक से संचालित हो रही है? रीडर, शुरुआती, मध्यवर्ती, उन्नत। ईमानदार हो। Production परिनियोजन के लिए उन्नत-ट्रैक गहराई की आवश्यकता है, रीडर-ट्रैक परिचितता की नहीं।
- यदि agent गलत व्यवहार करता है तो रोलबैक योजना क्या है? Wallet किल स्विच? SPT निरसन? agent को SDK स्तर पर अक्षम करें? इसे लॉन्च से पहले परिभाषित करें, घटना के बाद नहीं।
सन्दर्भ
चार protocol के लिए प्राथमिक स्रोत। द्वितीयक टिप्पणी की अपेक्षा इन्हें प्राथमिकता दें; specs उनके बारे में लिखने की तुलना में तेजी से विकसित होता है।
ACP (Agentic Commerce Protocol)
- विशिष्टता repository:
github.com/agentic-commerce-protocol/agentic-commerce-protocol(Apache 2.0) - डेवलपर साइट:
agenticcommerce.dev - सह-रखरखाव: OpenAI और Stripe
- Stripe एकीकरण docs:
stripe.com/docs/agentic-commerce - नवीनतम spec version उद्धृत:
2026-04-17
AP2 (Agent Payments Protocol)
- विशिष्टता repository:
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 एक्सटेंशन repository:
github.com/google-a2a/a2a-x402 - नवीनतम version उद्धृत: v0.2.0 (अप्रैल 2026)
x402
- विशिष्टता repository:
github.com/coinbase/x402(Apache 2.0) - दस्तावेज़ीकरण साइट:
x402.gitbook.io(x402.orgभी) - Coinbase द्वारा निर्मित और अब Linux Foundation के x402 फाउंडेशन (अप्रैल 2026) के तहत Cloudflare, Stripe, AWS, Google, और अन्य के साथ संचालित किया गया है।
- Cloudflare OpenAI Agents SDK एकीकरण:
developers.cloudflare.com/agents/x402 - दत्तक ग्रहण निर्देशिका:
agent.market - x402 फाउंडेशन के सदस्यों में शामिल हैं: Adyen, AWS, American Express, Base, Circle, Cloudflare, Coinbase, Google, Mastercard, Microsoft, Polygon Labs, Shopify, Solana फाउंडेशन, Stripe, Visa
MPP (Machine Payments Protocol)
- विशिष्टता साइट:
mpp.dev - सह-डेवलपर्स: Stripe और Tempo (Stripe का L1 blockchain, Paradigm के साथ इनक्यूबेट किया गया)
- Stripe घोषणा:
stripe.com/blog/machine-payments-protocol - लॉन्च की तारीख: 18 मार्च, 2026 (mainnet)
- लॉन्च के समय भागीदार: Stripe, Visa, Lightspark, Anthropic, OpenAI, Shopify, और 100 से अधिक सेवाएँ
निकटवर्ती protocols
- A2A (Agent2Agent, Google):
github.com/google-a2a/A2A, protocol AP2 विस्तारित - MCP (Model Context Protocol, Anthropic):
modelcontextprotocol.io, tool और संदर्भ layer agents के माध्यम से सेवाओं की खोज करें - UCP (Universal Commerce Protocol, Google): Google shopping सतहों के लिए ACP के समकक्ष के रूप में घोषित
- TAP (Trusted Agent Protocol, Visa और Cloudflare): identity सत्यापन protocol 14 अक्टूबर, 2025 को लॉन्च हुआ
- ERC-8004: बहु-agent लेनदेन के लिए on-chain विश्वास मानक
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 क्रैश कोर्स
- Build AI Agents क्रैश कोर्स: OpenAI Agents SDK बुनियादी बातें (
Agent,Runner.run(),@function_tool) - Production Worker क्रैश कोर्स: Inngest durable agent workflows के लिए परिचालन envelope के रूप में
- Eval-Driven Development क्रैश कोर्स: agents का परीक्षण और मूल्यांकन
- Choosing Agentic Architectures क्रैश कोर्स: कौन सा agentic पैटर्न फिट बैठता है जो केस का उपयोग करता है
- तैनाती-agent क्रैश कोर्स (क्लाउड तैनाती): क्लाउड हार्नेस (Azure कंटेनर ऐप्स प्लस Neon प्लस Cloudflare)। प्रगति पर है; शिप होने पर लिंक करें।
परिचालन और अनुबंध-परत tools (अवधारणा 16 और 18 में भारी उपयोग किया गया)
- Inngest:
inngest.com, durable निष्पादन प्लेटफ़ॉर्म जो इस पाठ्यक्रम में agent workflows चलाता है - FastAPI:
fastapi.tiangolo.com, async HTTP layer जहां webhook endpoints और seller-side x402 middleware रहते हैं - Pydantic:
pydantic.dev, प्रत्येक सीमा पर प्रकार का अनुबंध (tool returns, protocol payloads, FastAPI निकाय, Inngest इवेंट) - OpenTelemetry:
opentelemetry.io,httpx,openai-agents, FastAPI, और Inngest के लिए ऑटो-इंस्ट्रूमेंटेशन के साथ वितरित ट्रेसिंग; एक trace ID पूरे लेनदेन को फैलाता है - httpx:
python-httpx.org,x402-clientके नीचे async HTTP client, ACP client, और AP2 a2a-x402 एक्सटेंशन - Azure Key Vault: जहां signing कुंजियाँ production में रहती हैं, कॉन्सेप्ट 16 के अनुशासन के अनुसार घुमाई जाती हैं
- Stripe webhooks दस्तावेज़:
stripe.com/docs/webhooks, signature सत्यापन, ईवेंट प्रकार और retry शब्दार्थ
अब आपके पास संपूर्ण framework है: चार layers, चार protocols, उन्हें बनाने के नियम, पांच कार्यशील निर्णय, production चिंताएं जो तय करती हैं कि सिस्टम जीवित रहेगा या नहीं, और रखने के लिए एक पृष्ठ का संदर्भ। protocols चलता रहेगा। चार स्तरीय अनुशासन नहीं होगा. layers से निर्माण करें, और जब protocol नाम बदल जाएंगे तब भी आप सही रहेंगे।