Payment-Enabled Agents: ACP, AP2, x402, aur MPP Production mein

Un four protocols ka crash course jo OpenAI Agents SDK systems ko paisa kharch karne dete hain: merchants par, APIs ke against, doosre agents ke saath, aur open economy mein. Yeh un engineers ke liye hai jo agents ship kar chuke hain aur ab unhein payments handle karwane hain.

19 concepts. 5 decisions. 3 diagrams. Four learning tracks. Reader track 2-3 hours ki pure reading hai: four-layer stack, har protocol ki gehrai, composition rules, aur koi setup nahin. Beginner, Intermediate, aur Advanced tracks mein hands-on depth barhti jati hai: agents ko protocols se wire karna, composition ko durably chalana, aur identity, spend, aur disputes manage karna. Yeh tracks taqreeban 1 day, 2-3 days, aur 4-5 days lete hain. Honest estimate: parhne ke liye 2-3 hours; ek team ko is stack ko working habit banane ke liye 4-5 days. Part 5 ke decision lab se pehle apna track chunein.

Is course ka core idea yeh hai: yeh four protocols rivals nahin, layers hain. Zyada tar articles poochte hain: "ACP ya x402?" Yeh sawal protocol ki qisam ko hi ghalat samajhta hai. 2026 mein ship hone wala real system aksar in mein se kai protocols ko saath use karta hai, kyun ke har protocol agent-commerce problem ki alag layer solve karta hai. Consumer shopping agent commerce layer par ACP aur settlement par card rails use karta hai. API-paying agent x402 ko dono jagah use kar sakta hai, kyun ke machine-to-machine micropayments mein authorization aur settlement collapse ho kar ek layer ban jate hain. Enterprise procurement agent AP2 mandates se prove karta hai ke human ne spend authorize kiya, phir settlement par Stripe MPP use karta hai. Aap seekhenge ke use case ko kaise parhna hai aur sahi composition tak kaise pohanchna hai.

Agar aap ne baqi Agent Factory courses nahin kiye

Yeh course kuch sibling courses ka zikr karta hai: Build AI Agents crash course (SDK basics), Production Worker crash course (Inngest ke saath agents ko durably chalana), Eval-Driven Development crash course, aur Choosing Agentic Architectures crash course. Aap in courses ke baghair bhi yeh course parh sakte hain. Four protocols, layering, SDK code, aur decision discipline apni jagah kharay hain. Sirf ek cheez madad karti hai: Part 3 ka code assume karta hai ke aap Agent, Runner.run(), aur @function_tool parh sakte hain. Agar yeh naye hain, to pehle Build AI Agents crash course ya OpenAI Agents SDK docs skim karein, phir wapas aayen.

Agar aap different stack par hain to har protocol kis cheez se map hota hai

Agar aap OpenAI Agents SDK plus Stripe, Coinbase, aur Cloudflare par nahin hain, to yeh table har reference implementation ko common alternatives se map karta hai. Protocol specs stack-agnostic hain; sirf primitive names badalte hain.

protocol	Primary reference SDK (2026)	common alternatives	License / governance
ACP (Agentic Commerce Protocol)	Stripe SDK (stripe) plus OpenAI Agents SDK; PayPal ACP server tools; Worldpay credentials	Adyen ACP, Shopify-native checkout API	Apache 2.0, OpenAI plus Stripe at github.com/agentic-commerce-protocol/agentic-commerce-protocol
AP2 (Agent Payments Protocol)	Google ADK plus Python, TypeScript, Kotlin, Go mein reference implementations	LangGraph plus custom mandate signing, AutoGen plus a2a-x402	Apache 2.0, Google plus 60+ partners at github.com/google-agentic-commerce/AP2
x402	x402-client (Python), @x402/client (JS/TS), Coinbase Developer Platform, Cloudflare withX402Client, AgentPay MCP	Direct EIP-3009 implementations; Lobster.cash; Crossmint agent wallets	Apache 2.0, Coinbase ne banaya, ab Linux Foundation ki x402 Foundation ke under
MPP (Machine Payments Protocol)	Stripe PaymentIntents plus MPP extensions; Tempo blockchain SDK	Direct Lightning Network; Tempo native SDKs	Apache 2.0, Stripe plus Tempo; specs at mpp.dev
A2A (Agent2Agent, layer AP2 extends)	Google ADK	Custom A2A implementations	Apache 2.0, Google plus Linux Foundation
MCP (Model Context Protocol, discovery layer)	Anthropic MCP servers aur clients; openai-agents MCP support	LangChain MCP	MIT, Anthropic

Table ko aise use karein: jab course kehta hai "agent ke @function_tool ko Stripe ACP endpoint se wire karein" aur aap Adyen plus LangGraph par hain, to isay "equivalent LangGraph tool ko Adyen ACP endpoint se wire karein" samjhein. Argument same hai; names badalte hain. Sirf yeh course parhne ke liye Stripe stack seekhne ki zaroorat nahin. Primitives map karein, framework follow karein, aur apne stack par apply karein.

Glossary

📖 Is course ki terms, pehli reading par expand karein aur baad mein reference ke liye wapas dekhein

Four headline protocols

• ACP (Agentic Commerce Protocol). Consumer-shopping protocol, OpenAI aur Stripe ne banaya. Yeh define karta hai ke agent kisi real merchant par user ki taraf se checkout kaise complete karta hai. ChatGPT Instant Checkout isi se powered hai. Zyada tar commerce layer par rehta hai. Apache 2.0.
• AP2 (Agent Payments Protocol). Authorization protocol, Google ne 60+ partners ke saath banaya. Yeh signed "mandates" produce karta hai jo prove karte hain ke human ne agent ko spend karne ki ijazat di. AP2 khud paisa move nahin karta; yeh prove karta hai ke spending authorized thi. Apache 2.0.
• x402. HTTP-native settlement protocol, Coinbase ne banaya aur ab Linux Foundation govern karti hai. Yeh unused HTTP 402 "Payment Required" status code ko revive karta hai taake agent stablecoin ke saath ek se do seconds mein API call ke liye pay kar sake. Apache 2.0.
• MPP (Machine Payments Protocol). Stripe aur Tempo ka settlement protocol. Iska key move "session" hai: agent pehle spending cap approve karta hai, phir us cap ke against bohat si choti payments stream karta hai. Multi-rail: stablecoin, Lightning, cards. Apache 2.0.

Layers (poore course ki reedh ki haddi)

• Discovery layer. Yeh layer batati hai agent kya kharid sakta hai. Jawab MCP servers, A2A, agent directories, ya AI shopping surfaces se milta hai. Sawal: "available kya hai?"
• Authorization layer (Identity and Authorization bhi). Paisa move hone se pehle yeh layer do cheezen prove karti hai: human ne is spend ki ijazat di, aur agent wahi hai jo woh claim kar raha hai. Sawal: "kya mujhe yeh spend karne ki ijazat hai?"
• Commerce layer. Full purchase chalane wali layer: cart, checkout, fulfillment, dispute, refund. Sawal: "poora purchase lifecycle kya hai?" Plain API calls mein yeh layer poori tarah skip hoti hai.
• Settlement layer. Jahan paisa waqai haath badalta hai. Sawal: "paisa asal mein kahan move hota hai?"
• Settlement rail (ya rail). Woh actual pipe jahan se paisa guzarta hai: card networks (Visa/Mastercard via Stripe), blockchain par stablecoins, bank transfer (ACH/SEPA), ya Lightning. "Rail chunein" ka matlab hai "paisa kaise move hoga, yeh chunein."

Authorization primitives

• Mandate (AP2). Signed digital proof ke human ne ek specific qisam ke spend ko authorize kiya. AP2 mein teen mandates hain: Intent, Cart, aur Payment (neeche). Saath mil kar yeh ek chain banate hain jise aap baad mein audit kar sakte hain.
• Intent Mandate. Pehla mandate, jo user agent shuru hone se pehle sign karta hai: task ke rules. Misaal: "shoes $120 se kam mein kharido." Yeh woh limits set karta hai jinke andar agent ko rehna hota hai.
• Cart Mandate. Darmiyani mandate, jo user us waqt sign karta hai jab agent specific cart bana chuka hota hai: "haan, yeh exact items is exact price par." Yeh human-present flows mein approval ke liye use hota hai.
• Payment Mandate. Aakhri mandate, jo payment ke waqt sign hota hai ya Intent Mandate ke against auto-generate hota hai: "is exact rail par yeh exact payment authorize hai."
• SPT (Shared Payment Token). ACP ka primitive. Payment processor (Stripe) ka one-time token, jo ek merchant, ek amount cap, aur ek choti time window tak locked hota hai. Agar $50 ke liye cleared agent $1,000 spend karne ki koshish kare, SPT protocol level par fail ho jata hai. Yeh AP2 Payment Mandate ka card-rail cousin hai.
• Non-repudiable. Aisa signed record jise signer baad mein deny nahin kar sakta. AP2 mandate chain non-repudiable hai: "maine yeh kabhi authorize nahin kiya" user ki apni cryptographic signature ke saamne stand nahin karta.

Settlement aur crypto primitives

• Stablecoin. Cryptocurrency jo stable value, aksar ek US dollar, se pegged hoti hai. Agents isay use karte hain taake "$0.05 payment" send aur settle hone ke darmiyan five cents hi rahe.
• USDC. Dollar-pegged stablecoin jo zyada tar x402 payments use karte hain. One USDC ka intended value one US dollar hota hai. Circle issue karta hai.
• HTTP 402 Payment Required. HTTP status code jo 1997 se reserved tha lekin x402 se pehle practically unused tha. Server "402" plus payment requirements return karta hai; client signed proof of payment attach kar ke retry karta hai.
• EIP-3009 (transferWithAuthorization). Ethereum standard jis par x402 built hai. Buyer off-chain payment sign karta hai aur koi aur usay on-chain submit karta hai, is liye buyer gas fees pay nahin karta aur blockchain ko directly touch nahin karta.
• Facilitator (x402). Optional third party jo signature check karta hai aur merchant ki taraf se payment on-chain submit karta hai, taake merchant ko apni blockchain plumbing na chalani pare. Coinbase aur Cloudflare dono facilitators chalate hain.
• CAIP-2. Blockchain ko name karne ka standard tareeqa, taake protocol chain-agnostic reh sake. x402 chains ko CAIP-2 form mein likhta hai.
• EIP-155 / chain id. CAIP-2 ke andar Ethereum-style chains ki numbering scheme. eip155:8453 ka matlab Base chain hai; number chain id hai. (x402 code mein eip155:8453 dikhe to yeh sirf "Base" hai.)
• Smart-contract wallet. Crypto wallet jiske spending rules (per-transaction cap, daily cap, per-recipient cap) blockchain par code enforce karta hai. Kyun ke chain inhein enforce karti hai, yeh caps tab bhi hold karte hain jab agent ka apna code control se bahar ho jaye.
• MPP session. MPP ka signature move. Har payment sign karne ke bajaye agent ek "session" open karta hai jisme spending cap aur time limit hoti hai, phir uske against bohat si choti metered payments stream karta hai jab tak session close na ho. Agent ke liye prepaid tab samjhein.
• Sessions model (MPP). Upar wale pattern ka general name: cap aur duration pre-authorize karein, phir uske against bohat si choti charges meter karein. Frequent calls mein har micropayment sign karne se sasta.

Commerce aur money concepts

• Settlement. Woh moment jab paisa buyer se seller tak waqai move hota hai. Settlement se pehle sab choreography hai; deal settlement complete hone par hi done hoti hai.
• Merchant of record (MoR). Woh business jo transaction ke liye legally responsible hota hai: tax, disputes, aur customer support handle karta hai. ACP mein merchant hi MoR rehta hai. Plain machine-to-machine x402 calls mein aksar koi MoR nahin hota.
• Chargeback. Jab buyer ka bank dispute ke baad card payment reverse karta hai. Card rails chargebacks support karte hain; pure x402 nahin karta. Chargebacks ki zaroorat aksar decide karti hai ke aap kaun sa protocol use karenge.
• Dispute. Buyer ka formal challenge to a charge ("maine yeh authorize nahin kiya" / "item kabhi nahin aaya"). Mukhtalif protocols disputes ko mukhtalif tareeqe se resolve karte hain; yahi farq aksar protocol choice force karta hai.
• Idempotency. Property jahan same operation do baar karne ka effect same hota hai jaise ek baar karna. Yeh is liye matter karti hai ke Stripe same event id ke saath webhooks retry karta hai; idempotency key ke baghair code refund ya charge do baar kar sakta hai.

Agent stack aur adjacent protocols

• Agent commerce. Koi bhi transaction jahan autonomous AI agent buyer, seller, ya dono ho, aur us moment par koi human buy click na kar raha ho. Yeh "AI-assisted" shopping se different hai jahan insan ab bhi button press karta hai.
• OpenAI Agents SDK. Python/JavaScript toolkit jo Agent, Runner.run(), @function_tool, aur guardrails ke saath agent loops banata hai. Is course mein yeh "universal client" hai: har payment protocol ek ya zyada tools ban jata hai jise agent call kar sakta hai.
• MCP (Model Context Protocol). Anthropic ka open standard jo tools aur context agents ko expose karta hai. Agent commerce mein yeh aksar discovery layer hota hai: agents MCP servers ke zariye buyable services dhoondte hain. MIT licensed.
• A2A (Agent2Agent). Google ka protocol jisse agents ek doosre se baat aur discovery karte hain. AP2 A2A ke upar built hai: mandate A2A message ke taur par travel karta hai. Apache 2.0.
• UCP (Universal Commerce Protocol). Google ka commerce-layer protocol, ACP ka peer, jo Google's shopping surfaces (Gemini, Google AI Mode) ke around built hai. Commerce layer par ACP se compete karta hai.
• TAP (Trusted Agent Protocol). Visa aur Cloudflare ka protocol jo HTTP request headers ke andar agent identity prove karta hai. Yeh verify karta hai agent kaun hai, yeh nahin ke usay kya spend karne ki ijazat hai, is liye yeh usually kisi aur auth protocol ko replace nahin karta balkay uske saath add hota hai.
• ERC-8004. Agent identity aur reputation ke liye on-chain standard: agents ka public registry plus unki transaction history, taake no-prior-relationship wala agent trust karne se pehle doosre agent ka track record check kar sake.
• tool_input_guardrail. OpenAI Agents SDK guardrail jo tool execute hone se pehle chalta hai aur call reject kar sakta hai. Payment hone se pehle usay stop karne ka SDK-native tareeqa hai. Yeh course ki spine hai: yeh seven payment tools mein aata hai. (Compare karein output_guardrail, jo agent ke final reply par chalta hai aur payment stop karne ke liye bohat late hota hai.)

Prerequisites

Aapko is course se sab se zyada fayda hoga agar aap ke paas yeh cheezen hain:

1. Build AI Agents crash course, ya equivalent SDK experience. Protocol integrations SDK code ke taur par dikhayi gayi hain, is liye aapko Agent, Runner.run(), aur @function_tool comfortably parhna aana chahiye. Build AI Agents crash course dekhein.
2. Choosing Agentic Architectures crash course, ya equivalent design sense. Part 5 ka "which composition for which use case" framework us pattern-selection discipline par build karta hai. Choosing Agentic Architectures crash course dekhein.
3. Basic HTTP. Status codes, request/response cycle, headers. x402 khaas taur par HTTP level par kaam karta hai.
4. Basic payment vocabulary. Merchant, settlement, dispute, chargeback. Course agent-specific parts explain karta hai lekin assume karta hai ke aap jaante hain "merchant of record" kya hota hai.

Aapko blockchain ya smart-contract experience ki zaroorat nahin (course x402 aur EIP-3009 itna sikha deta hai ke aap follow kar sakein; Solidity nahin), aur four protocols mein se kisi ka prior experience bhi zaroori nahin. Yeh sab primary sources se sikhaye gaye hain.

Four learning tracks

Yeh course four depths par kaam karta hai. Part 5 se pehle apna track chunein.

Track	Time	Aap kya karenge	Best for
Reader	2-3 hours	Sab Concepts aur Decisions parhein; code run na karein.	Engineers jo decide kar rahe hain ke deeper invest karna hai ya nahin. PMs aur architects jinhein vendor proposals judge karne ke liye framework chahiye.
Beginner	~1 day	Reader plus x402 client examples run karein, aur Stripe test mode mein ek ACP test transaction karein.	Agent commerce mein naye engineers jo simplest protocol (x402) aur sab se production-ready protocol (ACP) ke saath hands-on waqt chahte hain.
Intermediate	2-3 days	Beginner plus ek agent banayein jo ek transaction type ke liye ACP aur doosre ke liye x402 use kare, plus AP2 Intent Mandate checks wire karein.	Engineers jo real system ship kar rahe hain jise multiple protocols compose karne hain.
Advanced	4-5 days	Intermediate plus composed system ko durably chalayein (Inngest envelope), spend limits aur human-approval gates wire karein, trace, cost, dispute metrics measure karein, aur ek full refund cycle handle karein.	Engineers jo real users ke liye real money move karne wale production systems ke responsible hain.

ek useful self-check: "ke liye use case I rakhte hain mein mind, kya hai sab se chota protocol composition ke ship karta hai value?" agar aap nahin kar sakte jawab ke baad part 4, re-read part 4. agar aap kar sakta hai, aapka track hai sirf ek sawal ka kaise far aap chahte hain to go se "sab se chota composition" to "production-grade composition."

Four-layer stack

yeh hai diagram sab kuch else hangs par.

har agent-commerce use case touches sab four layers, lekin mukhtalif istemaal karein cases compose karein mukhtalif protocols par har ek. ek consumer shopping agent: MCP ke liye discovery, ek ACP Shared Payment Token ke liye authorization, ACP ke liye commerce, card rails ke liye settlement. ek API-paying agent: ek agent directory ke liye discovery, ek EIP-3009 signature ke liye authorization, commerce layer nahin par sab, x402 ke liye settlement. ek enterprise procurement agent: ek A2A directory, ek AP2 mandate, ACP ya UCP ke liye commerce, Stripe MPP ke liye settlement. rule hai simple: ek chunein protocol per layer, aur let use case justify har chunein.

Part 1: Agent commerce ko naye protocols kyun chahiye

Reading part 1 lightly?

part 1 introduces six names (ACP, AP2, x402, MPP, MCP, A2A) aur teen layers fast. Yahi par purpose: yeh part hai briefing, not deep dive. least aap zaroorat to hold karein: ACP hai consumer shopping (Stripe plus OpenAI), AP2 hai authorization mandates (Google plus 60 partners), x402 hai per-request stablecoin payment ke upar HTTP (Coinbase), MPP hai session-based multi-rail payment (Stripe plus Tempo). MCP aur A2A hain kaise agents find aur talk to har other, not payment protocols. hold karein names loosely. part 2 wapas deta hai to har mein depth aur they'll stick par doosra pass.

concept 1: assumption ke broke

ek line mein: payment systems assumed ek human tha clicking kharidein, aur agents break ke assumption teen ways par once.

payment systems banaya gaya par ek quiet assumption: ek human hai par keyboard, clicking kharidein. har screen, har fraud check karein, har dispute process, har signup form tha designed ke liye people. AI agents break ke assumption mein teen ways par same time.

Break 1: agents mat rakhte hain email addresses. Consumer payment flows chahte hain ek account. ek account chahta hai ek email, ek phone number, aksar ek name. ek autonomous agent rakhta hai koi nahin ka yeh. Fake inhein, aur you've banaya gaya ek entity ke fail hota hai KYC moment fraud detection lagta hai par yeh. signup flow assumes ek human applying ke liye ek relationship; ek agent zaroorat hai kuch else.

Break 2: agents act thousands ka times per doosra. Fraud detection flags odd behavior ke zariye rate, location, aur pattern. ek agent making 1,000 API calls mein ek minute lagta hai exactly like ek credential-stuffing attack. Kya hai normal ke liye ek agent hai ek alarm ke liye ek human, aur rails hain tuned ke liye humans.

Break 3: agents nahin kar sakte chunein up phone. dispute resolution assumes buyer ho sakta hai reached: "kiya aap authorize karein yeh?" ek agent ke authorized ek charge nahin kar sakte jawab, aur human behind yeh ho sakta hai not even know charge happened. disputes zaroorat ek mukhtalif model jab buyer hai software.

har break zaroorat hai ek fix par protocol level, not ek coat ka paint par UI:

Break	kya human-rail fix nahin kar sakte karein	kya ek agent-rail fix deta hai aap
No email ya account	Force agents to banayein fake accounts	Cryptographic identity (TAP, ERC-8004) ya scoped tokens (ACP SPT, AP2 mandate)
High-frequency behavior	Block traffic ke lagta hai like ek attack	HTTP-native per-request payment (x402) ya pre-authorized sessions (MPP)
No phone ke liye disputes	Email disputes agent nahin kar sakte parhein	Mandate-based authorization (AP2) ke saath ek non-repudiable audit trail

"sirf wrap karein purana payments mein nicer agent UX" path pehle se fail hua. kai startups tried yeh mein 2024 aur 2025: dein agents human-like accounts ke saath made-up identity. Fraud detection caught inhein, chargebacks piled up, merchant relationships fell apart. Protocol-level fixes turned out to hona required, not optional. Yahi kyun ACP, AP2, x402, aur MPP sab showed up andar same twelve months.

bottom line ka concept 1: payment systems assumed ek human clicks kharidein. agents break ke teen ways: no traditional identity, alarming behavior patterns, no channel to clarify ek dispute. har break zaroorat hai ek protocol-level fix. Wrapping purana rails mein nicer UX fail hua. four protocols har cover ek mukhtalif mix ka yeh breaks.

concept 2: kyun ek protocol nahin kar sakte win

ek line mein: breaks happen par four mukhtalif layers ke saath four mukhtalif incumbents, so protocols split kaam ke zariye layer instead ka ek swallowing sab ka yeh.

ek fair sawal: agar sab four protocols showed up to fix same teen breaks, kyun didn't ek ka inhein sirf win? jawab hai structural. breaks happen par mukhtalif layers, aur ek single protocol ke tried to fix sab ka inhein hoga hona bhi big ke liye koi bhi to adopt.

Think ke bare mein kya ek unified protocol hoga rakhte hain to specify:

1. kaise agents find available merchants aur services. Yahi discovery layer.
2. kaise agents sabit karein jo yeh hain aur ke ek human authorized paisa kharch karein. Yahi authorization layer.
3. kaise agents chalayein ek full purchase, disputes aur refunds included. Yahi commerce layer.
4. kaise paisa waqai move hota hai ke darmiyan parties. Yahi settlement layer.

har layer pehle se rakhta hai strong incumbents. discovery belongs to search engines aur APIs. identity belongs to OAuth aur certificate authorities. commerce belongs to Stripe, Adyen, aur Shopify. settlement belongs to Visa, Mastercard, aur ACH, plus naya crypto rails. ek unified protocol hoga zaroorat har incumbent par har layer to agree par yeh. ke tha kabhi nahin jana to happen.

kya happened instead hai ke har protocol chuna ek layer jahan iska sponsor rakhta tha sab se zyada leverage:

protocol	jahan iska sponsor rakhta hai leverage	layer yeh took
ACP	OpenAI own karta hai shopping channel (ChatGPT); Stripe own karta hai merchant integration	commerce, ke liye human-buyer-via-AI flows
AP2	Google rakhta hai Android wallets aur ek 60-partner coalition	authorization, mandates ke taur par signed credentials
x402	Coinbase rakhta hai stablecoin infrastructure; Cloudflare rakhta hai HTTP edge	settlement, ke liye machine-to-machine micropayments
MPP	Stripe rakhta hai merchant relationships; Tempo rakhta hai blockchain	settlement, ke liye enterprise aur multi-rail flows

So protocols mat fight andar ek layer; yeh compete karte hain to define ek. par settlement, x402 aur MPP genuinely compete karte hain, aur zyada tar "x402 vs MPP" pieces miss ke yeh hai sirf place yeh waqai overlap. par commerce, ACP aur UCP compete karte hain. par authorization, AP2, TAP, aur ERC-8004 compete karte hain.

ke deta hai us ek idea yeh whole course rests par. ke andar ek layer, aap ek chunein protocol. across layers, aap compose karein kai. four protocols hain alternatives nahin to chunein ke darmiyan; yeh hain layers to stack. ek consumer shopping agent chalta hai ACP par commerce aur card rails par settlement. ek API-paying agent chalta hai x402 par settlement aur skip karta hai commerce entirely. ek enterprise agent chalta hai AP2 mandates par authorization aur MPP par settlement. decision tree mein part 5 walks yeh layer ke zariye layer. hold karein par yeh: har section baad yeh ek assumes yeh.

bottom line ka concept 2: Ek protocol nahin kar sakte fix sab four breaks kyun ke breaks live par four layers, har ke saath strong incumbents. protocols specialize: ACP par commerce, AP2 par authorization, x402 aur MPP par settlement. ke andar ek layer aap ek chunein; across layers aap compose karein kai.

concept 3: OpenAI agents SDK ke taur par universal client

ek line mein: aap mat talk to four protocols four mukhtalif ways; har ek becomes ek tool agent calls, aur SDK hai single client ke wire karta hai inhein sab mein.

ek practical sawal: given four protocols par four layers, kaise karta hai ek agent actually istemaal karein inhein? jawab mein 2026 hai ke agent's framework becomes universal client. har protocol exposes ek SDK ya ek HTTP endpoint, aur framework wire karta hai yeh mein ke taur par ek tool. yeh hai true ke liye OpenAI agents SDK, LangGraph, AutoGen, aur CrewAI alike. We'll istemaal karein OpenAI agents SDK throughout.

ke liye SDK, har protocol integration follows same shape: wrap karein protocol mein ek ya zyada @function_tool functions, hand inhein to ek Agent, aur let Runner.run drive loop.

stripe.PaymentTokens.create, X402Client(wallet=...), aur from ap2 import ... calls neeche hain illustrative: yeh dikhayein shape ek protocol integration takes. Agent, Runner, aur @function_tool scaffolding around inhein hai real aur chalta hai. dekhein note baad block ke liye kya hai ek stand-in.

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

kya chalta hai aur kya hai ek stand-in here: Agent, Runner.run, aur @function_tool wiring hai real SDK aur kaam karta hai ke taur par written. payment clients hain stand-ins. stripe.PaymentTokens.create nahin hai ek real Stripe call (production ACP integrates ke zariye live Stripe ACP endpoints), aur rich X402Client(wallet=..., max_per_request=...) constructor hai illustrative bhi. real buyer-side package hai x402-client, aur ek live call zaroorat hai ek funded account aur ek real 402 endpoint, kaun sa yeh course nahin karta karein. part 3 deta hai har protocol ek runnable mock backend so aap kar sakta hai dekhein harness kaam end to end ke baghair moving real paisa.

shape hai identical across sab four protocols. SDK hai universal client; har protocol hai sirf ek tool agent reasons ke bare mein aur calls jab yeh zaroorat hai ke. Teen parts ka SDK's structure matter ke liye payments:

1. ek typed wapas dein value ke liye payment results. jab ek payment tool wapas deta hai ek Pydantic model, agent's reasoner milta hai clean type information ke bare mein kya succeeded, kya fail hua, aur kya to karein agla. part 3 defines yeh shared result models once.
2. Runner.run(..., context=...) ke liye payment context. agent aksar zaroorat hai user's identity, spend limits, aur wallet handle. Pass yeh ke zariye SDK's context parameter instead ka baking inhein mein instructions. context hai per-run aur per-user.
3. tool_input_guardrail ke liye spend limits. ek tool input guardrail chalta hai before har tool executes aur reject kar sakta hai call. Yeh hai SDK-native way to block ek payment pehle yeh happens, not baad. concept 15 walks full teen-level enforcement. agent-level output_guardrail nahin karta solve yeh, kyun ke yeh fires par agent's final reply, baad koi bhi payment tool rakhta hai pehle se chalayein.

bottom line ka concept 3: OpenAI agents SDK hai universal client ke liye sab four protocols. har ek becomes ek @function_tool agent calls. SDK's typed wapas deta hai, context, aur tool_input_guardrail map cleanly to payment concerns: structured results, per-user context, aur stopping ek payment pehle yeh happens. integration shape hai same across sab four; part 3 fills mein har ek.

---

---

part 2: four layers mein depth

aap met four layers mein part 1; yahan har ek up close. har layer jawab ek mukhtalif sawal, rakhta hai iska own competing protocols, aur forces ek decision: ke liye this use case, kaun sa protocol best fit hota hai this layer? parhein part 2 pehle part 3. layer-by-layer framing yahan kya banata hai protocol details mein part 3 cohere instead ka reading like ek list ka rivals.

concept 4: layer 1, discovery (kaise agents find kya yeh kar sakta hai kharidein)

ek line mein: discovery hai jahan agent finds out kya hai even available to kharidein, aur sahi mechanism depends par jahan woh services actually live.

pehle ek agent kar sakta hai transact, yeh rakhta hai to find kya hai out there. ek shopping agent zaroorat hai merchants ke carry product. ek API-paying agent zaroorat hai ke know kaun sa endpoints rakhte hain data aur kya yeh cost. ek procurement agent zaroorat hai suppliers ke pass iska compliance rules. discovery jawab "kya hai available?"

Four serious options compete karte hain here mein 2026:

protocol	kaise yeh kaam karta hai	Best ke liye
MCP (Anthropic)	tool servers expose callable functions; agent connects, lists tools, aur calls inhein	Programmatic access to specific services developer wired mein; high-volume agent kaam; dominant agent-tooling discovery layer
A2A (Google)	agents publish kya yeh offer mein standard envelopes; other agents discover inhein	Multi-agent ecosystems jahan agents zaroorat to find peer agents; discovery layer AP2 extends
agent directories (agent.market, lobster.cash, Tenzro)	Public marketplaces listing paid APIs aur services; agents query inhein like ek catalog	Third-party services discovered par runtime; "Yellow Pages" ka agent commerce
AI shopping surfaces (ChatGPT Instant checkout, Google AI Mode, Walmart-in-ChatGPT)	Consumer AI products ke saath product discovery plus ACP checkout banaya gaya mein	Consumer flows jahan user hai talking to AI aur yeh surfaces products inline

SDK rakhta hai first-class support ke liye MCP: wire karein ek MCP server to ek agent mein ek kam lines aur sab iska tools become available to agent's reasoning. ke liye non-MCP discovery, wrap karein yeh ke taur par ek ordinary @function_tool ke queries directory aur wapas deta hai structured listings.

MCPServerStreamableHttp wiring neeche hai real aur importable. agent_market_client call hai illustrative: yeh stands mein ke liye ek directory client. @function_tool aur Agent scaffolding hai real.

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

choice aap banayein here nahin hai "MCP vs A2A vs directories." Yeh hai: jahan karein mera agent's services actually live? Internal to aapka org, istemaal karein MCP. across ek network ka partner agents, istemaal karein A2A. Third-party APIs aap discover par runtime, istemaal karein directories. Consumer products, istemaal karein ek AI shopping surface (aur ACP par commerce layer). yeh aren't mutually exclusive; ek real agent aksar istemaal karta hai kai.

bottom line ka concept 4: discovery jawab "kya hai available?" Four options compete karte hain: MCP ke liye internal tool servers, A2A ke liye multi-agent ecosystems, directories ke liye third-party services, AI surfaces ke liye consumer products. SDK rakhta hai first-class MCP support aur wire karta hai rest ke taur par @function_tool functions. chunein ke zariye jahan services live; yeh hain not mutually exclusive.

concept 5: layer 2, identity aur authorization (proving agent hai allowed)

ek line mein: authorization hai jahan agent sabit karta hai human allowed yeh spend aur ke agent hai jo yeh claims to hona, pehle koi bhi paisa move karta hai.

pehle paisa move kar sakta hai, do cheezen rakhte hain to hona true: agent hai jo yeh claims to hona, aur human authorized yeh spend. Yeh hain mukhtalif problems ke saath mukhtalif solutions, aur layer 2 settle hota hai both pehle settlement happens. skip karein layer 2 aur aap milta hai ek ka do failures: fraud (anyone's agent kar sakta hai paisa kharch karein anyone's paisa) ya paralysis (har transaction zaroorat hai ek human to click confirm).

yeh hai sab se zyada contested layer mein 2026. Four options, four philosophies:

protocol	kaise yeh kaam karta hai	Strongest jahan
AP2 mandates (Google)	signed credentials: Intent mandate ("kharidein shoes ke neeche $120"), cart mandate ("yeh cart, yeh price"), Payment mandate ("authorize karein yeh rail")	Audit-heavy flows ke zaroorat non-repudiable proof ka consent; multi-agent flows jahan merchant rakhta hai kabhi nahin dekha gaya buyer's agent pehle
ACP SPT (OpenAI plus Stripe)	Stripe mints ek Shared Payment Token scoped to ek merchant, amount, aur time window; agent presents yeh; merchant verify karta hai aur charges	consumer shopping jahan Stripe hai processor aur card rails carry chargeback discipline
TAP (Visa plus Cloudflare)	agent's identity signature rides mein HTTP headers; merchants verify karein yeh against Visa's directory	identity verification specifically (not authorization); aksar add hua to another auth protocol, not istemaal hua akela
ERC-8004 plus on-chain reputation	ek on-chain registry ka agent identities aur transaction history, ke saath ek reputation score se past deals	Pure multi-agent flows ke saath no prior trust; high-stakes B2B jahan reputation hai worth checking

do sawalat layer 2 lazmi jawab, aur kaise har protocol jawab inhein:

1. "kiya human authorize karein yeh?" AP2 jawab ke saath ek mandate user signed pehle delegating. ACP jawab ke saath ek SPT Stripe minted sirf baad user authorized par account level. TAP nahin karta jawab yeh; yeh hai identity-only. ERC-8004 jawab ke saath signed on-chain transactions.
2. "hai agent jo yeh claims to hona?" AP2 jawab ke saath signing key (sirf real agent kar sakta hai sign karein). ACP jawab ke saath SPT hona merchant-scoped (sirf authorized merchant kar sakta hai redeem yeh). TAP jawab ke saath Visa's directory lookup. ERC-8004 jawab ke saath on-chain identity record.

SDK deta hai aap do integration points: ek tool input guardrail ke chalta hai pehle payment tool, aur chalayein context ke carries per-user state mein both.

guardrail, @function_tool, aur Agent wiring neeche hai real SDK aur chalta hai ( attribute paths data.context.tool_arguments aur data.context.context hain confirmed against installed SDK). stripe.PaymentTokens.create call andar tool hai illustrative; production ACP istemaal karta hai live Stripe ACP endpoints.

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

kaun sa guardrail stops ek payment

SDK rakhta hai teen guardrail types aur yeh fire par mukhtalif moments. input_guardrail chalta hai par pehla agent's initial input. output_guardrail chalta hai par final agent's response to user. tool_input_guardrail aur tool_output_guardrail chalayein par har function-tool call, pehle aur baad yeh executes. ke liye payment safety aap zaroorat tool input guardrail: yeh fires pehle payment tool chalta hai aur reject kar sakta hai call. ek output guardrail fires bhi late to stop payment; yeh hai useful ke liye cleaning up final reply (say, redacting sensitive data), not ke liye blocking ek tool. concept 15 wapas deta hai to yeh; yeh hai single zyada tar common mistake.

choice aap banayein here comes down to aapka trust model. agar user hai signed mein aapka app aur aap kar sakta hai mint SPTs ke zariye Stripe, ACP deta hai aap sab se zyada production-ready story. agar aap zaroorat non-repudiable audit trails, ke taur par mein regulated industries ya B2B procurement, AP2 mandates fit. agar aap zaroorat cryptographic identity par iska own, separate se authorization, add karein TAP. mein ek pure multi-agent setting ke saath no shared trust, ERC-8004 fills gap. yeh hain interchangeable nahin.

bottom line ka concept 5: authorization jawab do sawalat: "kiya human authorize karein yeh?" aur "hai agent jo yeh claims to hona?" four protocols compete karte hain: AP2 mandates (audit-heavy), ACP SPT (Stripe-native), TAP (identity-only), ERC-8004 (multi-agent trust). SDK integrates via chalayein context ke liye per-tool check karta hai aur tool_input_guardrail (kaun sa chalta hai pehle har tool aur reject kar sakta hai yeh) ke liye spend limits. chunein ke zariye trust model.

concept 6: layer 3, commerce ( full purchase lifecycle)

ek line mein: commerce hai sab kuch mein ek real purchase ke isn't authorization ya settlement: cart, order, fulfillment, dispute, refund, aur ek plain API call skip karta hai yeh entirely.

authorization aur settlement saath cover "paisa move karta hai ke saath permission." commerce covers sab kuch else mein ek purchase: structured carts, order confirmation, fulfillment tracking, dispute resolution, refunds, chargebacks, wapas deta hai. yeh hai layer ke separates ek checkout se ek paisa transfer. ek plain machine-to-machine API call nahin karta zaroorat ek commerce layer; yeh hai sirf ek API call. ek consumer purchase clearly zaroorat hai ek.

Teen meaningfully mukhtalif options:

protocol	kya yeh karta hai	Best ke liye
ACP (OpenAI plus Stripe)	ek structured flow: cart format, order confirmation, fulfillment status, dispute escalation, refunds. merchant stays merchant ka record.	consumer shopping: retail goods, subscriptions, physical fulfillment. Powers ChatGPT Instant checkout.
UCP (Google)	ek similar lifecycle, banaya gaya around Google's shopping surfaces (Gemini, Google AI Mode) aur Google pay karein	merchants par Google Shopping; agents par Google AI surfaces
Direct API (machine-to-machine)	No commerce protocol par sab, sirf ek HTTP API. Payment via x402 ya MPP. No cart, no disputes, no refunds.	API access, compute, data feeds: purchases jahan cheez kharida hai ek stateless API response

So ACP aur UCP compete karte hain; "direct API" hai absence ka yeh layer, not ek teesra competitor, aur yeh aksar sits happily agla to kuch nahin. ek consumer platform chunta hai ACP ya UCP (ya both, agar yeh spans ChatGPT aur Gemini). ek API marketplace nahin karta chunein par yeh layer par sab, kyun ke iska purchases ke paas koi nahin lifecycle to manage.

part zyada tar engineers underestimate hai refunds aur disputes. ek customer jo orders ghalat size t-shirt expects to bhejein yeh back. commerce protocol rakhta hai to say kaise wapas dein shuru hota hai, kaise agent hears ke bare mein yeh, aur kaise refund flows back ke zariye settlement. ACP milta hai yeh sahi ke zariye keeping merchant ke taur par merchant ka record: existing dispute machinery (Stripe's chargeback flows, retailer's wapas dein policy) sirf kaam karta hai. Direct-API approaches milta hai yeh ghalat ke zariye ignoring yeh. There's aksar no refund path par sab, kaun sa hai fine ke liye ek $0.0001 API call aur ghalat ke liye $500 ka API credits.

commerce flows aksar zaroorat kai tools working mein sequence:

acp_client calls neeche hain illustrative; yeh stand mein ke liye ek ACP commerce backend. Pydantic models, @function_tool, aur Agent wiring hai real.

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

sawal to poochein yahan whether aapka use case zaroorat hai ek commerce lifecycle par sab. agar yeh karta hai (cart, refund, dispute), chunein ACP ke liye ChatGPT reach ya UCP ke liye Google reach, ya both. agar yeh nahin karta, skip karein yeh layer aur go straight se authorization to settlement. do ways to milta hai yeh ghalat: forcing ek consumer-commerce protocol par ek machine-to-machine call (bhi bohat), ya skipping commerce par ek real consumer purchase aur phir re-implementing disputes badly baad mein (bhi little).

bottom line ka concept 6: commerce handles full purchase lifecycle: cart, checkout, fulfillment, dispute, aur refund. ACP aur UCP compete karte hain ke liye consumer flows; machine-to-machine access rakhta hai commerce layer nahin par sab. refund aur dispute mechanics hain hidden weight ke separates ek real commerce protocol se ek payment-only ek. SDK wire karta hai commerce ke taur par ek sequence ka tools (cart, checkout, status, refund). chunein ke zariye use case: lifecycle zaroori tha (ACP/UCP) ya skip hua (direct API).

concept 7: layer 4, settlement (paisa waqai move hota hai)

ek line mein: settlement hai jahan dollars actually change custody, aur chunein hai zyada tar ke bare mein transaction's economics.

move karein value se buyer to seller. sab kuch oopar yeh layer hai choreography; settlement hai jahan dollars (ya stablecoins, ya whatever unit hai) actually change hands. agent rakhta hai sirf complete hua ek transaction once settlement complete karta hai.

Four serious options, har ke saath iska own economics aur limits:

protocol	kaise yeh kaam karta hai	Economics	Best ke liye
x402	HTTP-native; settle hota hai via ek stablecoin transfer par Base/Solana/EVM, signed ke saath EIP-3009	Sub-cent gas, 1-2 doosra finality, no protocol fees	machine-to-machine micropayments; high-frequency, low-value (API access, per-call billing)
MPP	sessions: agent pre-authorizes ek cap aur duration, phir streams metered payments. Multi-rail (stablecoin par Tempo, Lightning, cards)	Stripe fees par card rails; near-zero par stablecoin; subscription-friendly	Enterprise aur multi-rail flows; recurring subscriptions; cases needing both fiat aur crypto mein ek envelope
card rails (Stripe/Adyen/Worldpay)	Visa, Mastercard, Amex via Stripe; agent presents ek SPT (ACP) ya Payment mandate (AP2); processor charges card	Around 2.9% plus $0.30 ke liye cards; established dispute machinery	Consumer flows; transactions ke saath chargeback exposure; international card acceptance
bank transfer / Lightning	ACH, SEPA, Bitcoin Lightning	ACH ~$0.25 fixed; Lightning sub-cent; SEPA ~€0.20	High-value flows jahan 2.9% card fees hurt; cross-border micropayments via Lightning

settlement chunein hai zyada tar ke bare mein paisa. Sub-dollar payments jayein x402, jahan stablecoin gas hai sub-cent. Consumer purchases up to ke bare mein $1,000 jayein card rails via ACP, jahan chargeback protection hai worth 2.9%. Recurring subscriptions jayein MPP sessions. Large B2B transfers jayein bank rails ya Lightning. aur layers oopar aksar force chunein: ACP par commerce zyada tar means card rails par settlement; ek x402-paywalled MCP server par discovery zyada tar means x402 par settlement.

Watch ke liye headline-number trap. Pieces citing x402's transaction volume ya MPP's integration count kar sakta hai mislead. sahi sawal isn't "kaun sa rakhta hai sab se zyada volume?" Yeh hai "kaun sa fit hota hai yeh transaction's economics?" ek $0.001 API call settled par card rails costs more mein fees se call khud. ek $5,000 procurement settled par x402 stablecoin throws away chargeback protection ek card hoga dein aap.

settlement aksar fires ke taur par ek side effect ka ek higher-layer tool: agent kam hi calls settle_payment() directly; settlement happens andar acp_checkout() ya x402_fetch(). lekin spend limits par SDK level phir bhi matter:

x402_client.get call neeche hai illustrative; yeh stands mein ke liye ek buyer-side x402 fetch. @function_tool wiring aur paisa kharch karein check karein hain real 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,
    )

Ek cheez to hona clear ke bare mein: if spent_so_far + ... check karein hai ek soft guard andar tool body, useful ke liye ek fast, friendly failure lekin not real safety. safety ke actually protect karein karta hai aap hai agent's smart-contract wallet. Even agar aap deleted in-tool check karein, wallet caps se concept 15 hoga phir bhi reject on-chain transfer. tool's check karein hai ke liye UX; wallet caps hain safety.

move karein yahan to chunein rail ke matches transaction's economics, phir confirm yeh hai compatible ke saath aapka commerce choice. Sub-dollar machine-to-machine jata hai to x402. Consumer purchases jayein card rails via ACP. Enterprise subscriptions jayein MPP. Don't chunein settlement mein isolation; chunein yeh ke taur par bottom ka ek composed stack.

bottom line ka concept 7: layer 4 (settlement) hai jahan paisa waqai move hota hai. Four options compete karte hain. x402 ke liye machine-to-machine stablecoin payments. MPP ke liye multi-rail sessions. card rails ke liye consumer purchases ke zaroorat chargebacks. bank ya Lightning ke liye high-value ya very-low-fee cases. choice hai zyada tar ke bare mein paisa: sub-dollar jata hai to x402, consumer jata hai to cards, enterprise jata hai to MPP. SDK chalta hai settlement ke taur par ek side effect ka higher-layer tools. yeh caps paisa kharch karein par chalayein aur session level ke saath RunContextWrapper, aur wallet's on-chain caps hain layer kuch nahin kar sakta hai bypass.

---

part 3: four protocols mein depth, ke saath OpenAI agents SDK integration

parts 1 aur 2 set framing: four layers, kai protocols per layer, SDK ke taur par universal client. part 3 walks har ka four headline protocols up close. ke liye har ek aap milta hai yeh kya hai, iska key primitives, SDK integration code, aur short notes par kaise teams deploy aur chalayein yeh.

parhein yeh ke taur par four parallel deep-dives. har protocol rakhta hai same shape, so aap kar sakta hai compare inhein side ke zariye side.

har protocol mein concepts 8 ke zariye 11 wire karta hai mein SDK ke zariye ek ka patterns mein yeh diagram. teen-level spend-limit stack par bottom previews concept 15 mein part 6. rakhein yeh mein corner ka aapka eye ke taur par aap parhein: safety discipline yeh dikhata hai hai kya turns yeh code mein kuch aap kar sakta hai actually deploy.

🧰 Pydantic ke taur par contract layer: parhein once, applies to har protocol neeche

har code sample mein part 3 istemaal karta hai Pydantic models, not plain Python dicts, ke liye protocol payloads, tool wapas deta hai, FastAPI request aur response bodies, aur Inngest event payloads. yeh hai part aap nahin kar sakte skip karein. yeh hai kya hold karta hai poora system saath.

Four boundaries milta hai crossed mein ek typical agent-commerce flow:

1. SDK's @function_tool wapas deta hai ek value to agent's reasoner.
2. ke value crosses wire karein to ek protocol endpoint (ACP, AP2, x402, MPP).
3. protocol wapas deta hai ek response ke crosses back.
4. Sometimes ek webhook arrives baad mein aur crosses mein ek FastAPI handler.

par har boundary, ek untyped dict quietly loses fields, drops coercions, aur ship karta hai ghalat shape. Pydantic models catch sab four kinds ka failure sahi par boundary, ke saath errors ke point par exact field.

Yahan pattern ke recurs mein har concept neeche:

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

Teen concrete reasons yeh matters par yeh scale:

1. ** reasoner istemaal karta hai wapas dein type ke taur par feedback.** jab acp_checkout wapas deta hai ek typed CheckoutResult, agent's agla reasoning step milta hai clean field names aur types, not ek stringified dict. Tool-selection accuracy jata hai up measurably.
2. FastAPI istemaal karta hai Pydantic natively. Stripe webhooks, AP2 mandate callbacks, aur MPP session events sab deserialize mein Pydantic models mein FastAPI handler: same models agent's tools wapas dein. Ek contract, do endpoints.
3. Inngest events carry Pydantic payloads. jab ek FastAPI webhook handler fires ek Inngest event, payload hai ek Pydantic model. suspended step.wait_for_event receive karta hai typed payload directly. No JSON parsing mein workflow.

Decimal ke liye paisa, hamesha. har monetary amount hai course mein istemaal karta hai Decimal, kabhi nahin float. Floating-point math par paisa loses precision mein ways ke compound across thousands ka micropayments. Stripe SDK accepts both lekin reports back mein Decimal. x402 amounts arrive ke taur par on-chain integers (USDC rakhta hai 6 decimal places) ke aap wrap karein mein Decimal. paisa stays Decimal everywhere yeh isn't hona serialized to ek wire karein format.

** shared result models.** Rather se redefine result types mein har concept, course defines ek chota set ka result models once. har code block neeche imports inhein ke zariye name. Put yeh mein aapka 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

yeh models recur ke zariye part 3 aur part 6. code blocks neeche import inhein ke zariye name aur kabhi nahin redefine inhein. aap hoga dekhein import pattern repeated mein har concept; yeh sidebar nahin karta repeat.

concept 8: ACP (Agentic commerce protocol), consumer-shopping protocol

ek line mein: ACP hai kaise ek agent complete karta hai ek real checkout par ek real merchant par ek person's behalf, ke saath merchant phir bhi par hook ke liye sale.

yeh kya hai. ACP hai ek open specification banaya gaya ke zariye OpenAI aur Stripe, launched September 29, 2025 ke saath Etsy aur Shopify ke taur par launch partners. ke zariye early 2026 yeh powers ChatGPT Instant checkout across Shopify-integrated merchants aur kai bara retail brands. merchant counts aur brand lists vary ke zariye source, so verify karein against ACP integration directory ke liye current adoption. protocol hai Apache 2.0, governed ke zariye ek Specification Enhancement Proposal process par github.com/agentic-commerce-protocol/agentic-commerce-protocol. repository marks spec ke taur par beta, so expect drift ke darmiyan course misaalein aur live spec.

yeh kahan fit hota hai. ACP zyada tar rehta hai par layer 3 (commerce) aur reaches mein layer 2 (authorization) ke zariye iska token mechanism. yeh covers cart formation, checkout, order management, fulfillment status, aur refund mechanics. merchant stays merchant ka record: chargebacks, wapas deta hai, aur customer service sab flow ke zariye merchant's existing systems. (merchant ka record hai business legally par hook ke liye ek transaction.)

** do primitives ke matter.**

1. Shared Payment Token (SPT). ek ek-time token se payment processor (Stripe mein reference banayein), locked to ek merchant, ek amount cap, ek short time window, aur aksar ek single istemaal karein. agar ek agent cleared ke liye $50 try karta hai to paisa kharch karein $1,000, SPT sirf fail hota hai par protocol level. SPT hai kaise ACP rakhta hai agent andar user's authorized scope.
2. cart mandate (via AP2 extension). ACP compose kar sakta hai karein ke saath AP2 ke liye extra audit rigor: user sign karta hai ek cart mandate pehle agent submits SPT. yeh hai optional mein ACP lekin increasingly common mein regulated flows. (ek mandate hai ek signed proof ke ek human authorized ek specific qisam ka spend.)

** OpenAI agents SDK integration.** ACP hai sab se zyada production-ready protocol ke liye SDK, kyun ke OpenAI co-built yeh. Stripe Python SDK plus ek thin ACP client wrapper dein aap full integration.

acp_client calls aur stripe.PaymentTokens.create(...) neeche hain illustrative: yeh dikhayein shape ek ACP integration takes. real SPT minting jata hai ke zariye live Stripe ACP endpoints, not ek stripe.PaymentTokens method. agent wiring, guardrail, aur result models hain real aur chalayein aaj. dekhein note baad block.

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

kya hai real here: Agent, Runner, @function_tool, aur tool_input_guardrail scaffolding, plus typed result models. ke hai part aap reuse ke liye har protocol. kya hai ek stand-in: acp_client aur stripe.PaymentTokens.create call, kaun sa represent ACP-Stripe backend. production mein aap swap ke backend ke liye live Stripe ACP endpoints aur rest stays put. Yahan same shape ke saath ek runnable mock so aap kar sakta hai dekhein yeh kaam:

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

standard harness (stated once here, referenced ke zariye agla teen concepts). ACP chalta hai par plain cloud harness ke saath no extra parts. Stripe SDK chalta hai andar FastAPI handler; ACP calls hain outbound HTTPS; SPTs live mein agent's run-scoped context, passed ke zariye RunContextWrapper. ek rule: rakhein Stripe API keys mein ek secret store (ek key vault), not mein environment variables, aur rotate inhein par Stripe's schedule. No sandbox hai zaroori tha (ACP chalta hai code nahin) aur special storage nahin hai zaroori tha (orders persist mein Stripe aur merchant's system, ke saath optional shadow records ke liye audit). yeh deployment baseline hai same ke liye AP2, x402, aur MPP. agla teen concepts say sirf kya har ek adds. Cloud deployment hai covered mein deploying-agents crash course (mein progress).

isay durably chalana (Inngest). ACP transactions hain short, aksar 5 to 30 seconds end to end. yeh fit cleanly mein Inngest step.run blocks. step.wait_for_event primitive earns iska rakhein jab agent lazmi pause ke liye user to confirm cart ke darmiyan cart creation aur checkout ( human-in--loop pattern). Production Worker crash course covers yeh durability layer mein depth; yahan shape:

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}

ek couple ka details ke trip people up: wait_for_event matches incoming payload ke saath if_exp (ek chota expression), aur awaited fields live ke neeche async. prefix. ek timeout wapas deta hai None, so check karein ke liye yeh pehle continuing.

teams yahan kahan ghalti karti hain. yeh skip karein user-confirmation step. ACP supports both "user confirms har cart" aur "user pre-authorized yeh qisam ka purchase." teams aksar chunein doosra ek ke liye speed, phir find ke ek chota SPT misconfiguration lets agent kharidein slightly-ghalat items ke saath no way to recover. Default to confirming cart ke liye pehla month production mein. Relax yeh sirf once aap rakhte hain measured kaise aksar agent milta hai cart sahi.

bottom line ka concept 8: ACP hai production-ready commerce protocol ke liye consumer shopping ke saath OpenAI agents SDK. SPT scopes agent's spend; merchant stays merchant ka record. aap integrate karein yeh ke taur par four @function_tool functions (browse, checkout, status, refund) ke upar Stripe SDK aur ek thin ACP client. Inngest's step.wait_for_event banata hai user-confirmation gate, aur plain cloud harness hai kaafi. Default to confirming carts until aap rakhte hain measured agent's cart accuracy.

concept 9: AP2 (agent Payments protocol), authorization layer

ek line mein: AP2 produces signed proofs ke ek human allowed spend; yeh nahin karta move karein paisa khud, yeh sabit karta hai paisa tha allowed to move karein.

yeh kya hai. AP2 hai ek open specification se Google ke saath 60+ partners, launched September 2025 (latest version v0.2.0, April 2026). Apache 2.0, maintained par github.com/google-agentic-commerce/AP2, ke saath reference implementations mein Python, TypeScript, Kotlin, aur Go. AP2 hai authorization layer, not ek commerce ya settlement protocol. yeh produces signed mandates ke sabit karein ek agent hai authorized to paisa kharch karein, phir leaves asal settlement to whatever rail fit hota hai (cards, bank, ya x402 ke zariye a2a-x402 extension).

yeh kahan fit hota hai. AP2 rehta hai par layer 2 (identity aur authorization). yeh banata hai par do protocols underneath: A2A (Agent2Agent, ke liye agent-to-agent messaging) aur MCP (ke liye tool exposure). ek AP2 mandate travels ke taur par ek signed credential ke upar A2A ya attached to ek MCP tool call.

** teen primitives ke matter, teen mandate types.**

mandate	jab yeh hai banaya gaya	kya yeh sabit karta hai
Intent mandate	par shuru karein ka task, signed ke zariye user mein inka UI	user allowed agent to act ke andar set rules (price limits, time windows, allowed merchants)
cart mandate	agent ke baad rakhta hai banaya gaya ek specific cart, signed ke zariye user pehle checkout (human-present flows)	user approved yeh exact cart par yeh exact price
Payment mandate	par moment ka payment, signed ke zariye user ya auto-generated against Intent mandate	user authorized yeh exact payment par yeh exact rail

** audit trail.** teen mandates form ek chain signer nahin kar sakta baad mein deny: Intent ("kharidein shoes ke neeche $120") leads to cart ("yeh shoes par $110") leads to Payment ("charge yeh stablecoin wallet"). har mandate points back to ek pehle yeh. agar koi bhi step hai challenged baad mein ek dispute ya ek fraud claim, poora chain hai auditable. ke property hai non-repudiable: "I kabhi nahin authorized yeh" hold nahin hota against user's own signature. yeh hai kyun AP2 fit hota hai regulated industries like healthcare aur financial services, jahan "kiya user actually authorize karein yeh?" carries legal weight.

SDK ke liye kya badalta hai. AP2 ke paas koi nahin first-class place mein OpenAI agents SDK; iska reference banata hai istemaal karein Google's agent Development Kit. aap wire karein yeh mein ke taur par @function_tool functions ke banayein, sign karein, validate karein, aur dispatch mandates. harness hai same ek se concept 8. ek cheez AP2 add karta hai: ek signing surface jahan user actually sign karta hai har mandate.

from ap2 import ... imports, MandateSigner, aur ap2_x402 calls neeche hain illustrative. AP2's real Python package hai ap2, ke saath mandate models ke neeche ap2.types.mandate, aur iska real fields differ se simplified principal_did / agent_did / rules dikhaya gaya here. There koi nahin MandateSigner class; real signing istemaal karta hai verifiable credentials ke upar A2A. mandate-chain concept hai real; yeh exact code hai ek teaching stand-in. SDK scaffolding aur typed results hain real.

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

kya hai real: same SDK scaffolding aur typed results ke taur par concept 8. kya hai ek stand-in: ap2 mandate classes, MandateSigner, aur ap2_x402 extension. mandate chain khud hai ek real idea aap kar sakta hai banayein; exact API yahan simplified ke liye teaching. Yahan ek runnable mock so pattern executes:

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"))})()

yeh harness mein kya add karein karta hai. Do cheezen beyond concept 8 baseline: ek signing surface ke liye user to sign karein mandates (ek web app, ek mobile app, ya ek notification-based signing tool), aur durable storage ke liye signed mandates ke lasts ke taur par long ke taur par aapka dispute windows (7-year retention hai standard ke liye financial mandates). signing surface hai real delta se ACP: ACP kar sakta hai reuse existing login sessions, lekin AP2 zaroorat hai ek dedicated signature flow.

isay durably chalana (Inngest). mandate signing hai textbook istemaal karein ka step.wait_for_event. agent's function fires ek "signing requested" event, function suspends, user sign karta hai mein UI kaun sa fires "signing signed," aur function resumes. No compute hai burned jabke yeh wait karta hai, kaun sa matters kyun ke ek enterprise signature kar sakta hai take hours. Production Worker crash course jata hai deep par yeh resume pattern.

teams yahan kahan ghalti karti hain. yeh treat mandate creation ke taur par ek checkout-time concern aur sign karein mandate agent ke baad rakhta hai pehle se done ek lot ka kaam. banayein Intent mandate pehla, pehle agent shops par sab. ke catches ek scope mismatch early (user wanted shoes lekin Intent mandate sirf allows office supplies) instead ka agent ke baad rakhta hai spent compute building ek cart yeh kar sakta hai kabhi nahin fund.

bottom line ka concept 9: AP2 hai authorization layer ke liye audit-heavy agent commerce. Teen mandate types (Intent, cart, Payment) form ek chain user nahin kar sakta baad mein deny, proving consent par har step. Reference implementations ship mein Python, TypeScript, Kotlin, aur Go via Google's agent Development Kit; aap integrate karein ke saath OpenAI agents SDK ke taur par @function_tool functions ke banayein, sign karein, aur validate karein mandates. Inngest's step.wait_for_event hai natural fit ke liye signing wait karein. banayein Intent mandates pehla, pehle shopping begins, kabhi nahin ke taur par ek checkout afterthought.

concept 10: x402, HTTP-native settlement protocol

ek line mein: x402 lets ek agent pay karein ke liye ek API call mein ek se karein seconds ke saath ek stablecoin, ke zariye reviving purana HTTP 402 "Payment Required" status code.

yeh kya hai. x402 turns dormant HTTP 402 status code mein ek working payment layer ke liye APIs aur machine-to-machine commerce. yeh tha banaya gaya ke zariye Coinbase (ho sakta hai 2025), ke saath V2 launched mein December 2025, aur hai ab stewarded ke neeche Linux Foundation's x402 Foundation (April 2026), ke saath Cloudflare, Stripe, AWS, Google, aur others ke taur par members. Apache 2.0. ke taur par ka early 2026, x402 reports ke upar 100 million payments to date across Base aur Solana, ke saath ek growing facilitator ecosystem; numbers move karein fast, so verify karein current figures par x402.org aur Coinbase's x402 launch pages.

yeh kahan fit hota hai. x402 zyada tar rehta hai par layer 4 (settlement) ke liye machine-to-machine flows, lekin yeh reaches mein layer 1 (ke zariye agent.market aur similar directories) aur layer 3 (yeh kaam karta hai ke taur par ek full commerce layer ke liye plain API access jahan there hai real purchase lifecycle nahin). ke liye pure machine-to-machine flows, x402 hai aksar sirf protocol aap zaroorat.

four primitives ke matter.

1. ** HTTP 402 status code.** jab ek unpaid client requests ek paid resource, server wapas deta hai 402 Payment Required plus ek header carrying payment requirements: scheme (exact ke liye ek fixed amount), network (mein CAIP-2 form like eip155:8453, kaun sa sirf means "Base"), asset (USDC), recipient address, max amount, aur ek expiry. (CAIP-2 hai ek standard way to name ek blockchain so protocol stays chain-agnostic.)
2. payment authorization header. client dobara try karta hai ke saath ek header carrying ek signed payment authorization. signature hai banaya off-chain, so buyer pay karta koi nahin gas.
3. EIP-3009 (transferWithAuthorization). Ethereum standard x402 hai banaya gaya par. yeh lets buyer sign karein ek payment off-chain ke koi else submits on-chain, so buyer kabhi nahin touches blockchain directly ya pay karta hai gas.
4. Facilitator. ek optional teesra party ke check karta hai signature aur submits payment on-chain ke liye merchant, so merchant chalta koi nahin blockchain plumbing. Coinbase aur Cloudflare both chalayein facilitators.

ek note par header naming: verify karein against current docs

x402 went ke zariye V1 aur V2, aur header names differ across spec versions, facilitators, aur SDKs. Cloudflare's current docs istemaal karein PAYMENT-REQUIRED par 402 response, PAYMENT-SIGNATURE par client's dobara try karein, aur PAYMENT-RESPONSE par success reply. kuch earlier misaalein istemaal karein X-PAYMENT aur X-PAYMENT-PROOF. flow hai identical; sirf wire karein names differ. check karein exact names against x402.gitbook.io aur aapka facilitator's docs pehle writing code. trace neeche istemaal karta hai roles (request, 402 ke saath requirements, signed dobara try karein, success ke saath proof) ke baghair picking ek naming convention.

** flow mein ek trace.**

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

poora transaction takes ek se karein seconds. account banane ki zaroorat nahin, no API key, no session, human loop mein nahin.

SDK ke liye kya badalta hai. x402 rakhta hai simplest story ka four. Cloudflare ship karta hai ek helper ke wraps ek MCP client ke saath x402 payment ability; ke liye non-MCP istemaal karein, ek Python buyer-side library plus canonical pattern neeche covers yeh. harness hai same concept 8 baseline.

from x402_client import ... constructor dikhaya gaya here, from cloudflare_agents import withX402Client import, aur response.amount_paid_usdc field hain illustrative. real buyer-side package hai x402-client (from x402_client import X402Client, real constructor X402Client(account=...), .get(url) wapas deta hai ek httpx.Response). richer wallet constructor dikhaya gaya yahan ek teaching stand-in, aur ek live call zaroorat hai ek funded account aur ek real 402 endpoint, kaun sa yeh course nahin karta karein. Cloudflare's withX402Client hai ek JavaScript helper; there koi nahin Python cloudflare_agents package. MCP server (MCPServerStreamableHttp) hai real Python; wrapping yeh ke saath payment hai illustrative here. No real funds move karein.

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

kya hai real: SDK scaffolding, typed results, aur MCPServerStreamableHttp ( MCP server hai genuine Python). kya hai ek stand-in: buyer-side x402 client ke taur par written here, withX402Client wrapper (JavaScript sirf mein reality), aur agent_market_client. Here hain runnable mocks so harness pattern executes ke baghair real funds:

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

yeh harness mein kya add karein karta hai. Almost kuch nahin. x402 zaroorat hai extra infrastructure nahin beyond concept 8 baseline. agent's smart-contract wallet rehta hai par ek address par chain yeh transacts par (Base mein zyada tar cases), wallet's signing key sits mein key vault, aur buyer-side library handles signing aur HTTP dobara try karein. (ek smart-contract wallet hai ek crypto wallet kis ka spend caps hain enforced ke zariye code par blockchain khud, so yeh hold karein even agar agent's code jata hai haywire.)

isay durably chalana (Inngest). x402 calls hain short (ek se karein seconds) aur idempotent: same request aur signature hamesha produce same outcome. yeh fit cleanly mein step.run blocks, aur memoization pay karta hai off here. agar chalayein crashes baad paying ke liye 5 ka 10 API calls, 5 paid calls hain memoized aur dobara try karein pay karta hai sirf ke liye remaining 5. ke baghair yeh, dobara try karein hoga pay karein ke liye sab 10 dobara.

wallet cap hai safety ke protect karein karta hai aap

trap hai treating x402 like handing agent ek credit card. safety ke actually protect karein karta hai aap hai wallet's on-chain paisa kharch karein limit, not per-request max_payment_usdc. skip karein on-chain limit aur istemaal karein ek hot wallet ke saath no cap, aur ek single stuck agent loop kar sakta hai drain karein yeh. Configure on-chain spend limits per agent identity, har session par, aur per merchant, teen independent layers, so ek bug mein ek nahin karta empty wallet.

bottom line ka concept 10: x402 hai production-ready HTTP-native settlement protocol ke liye machine-to-machine micropayments. 402 status code, ek signed payment-authorization header, aur EIP-3009 signature flow settle karein mein ek se karein seconds ke saath account banane ki zaroorat nahin. Cloudflare's helper wraps MCP servers ke saath payment ability; direct calls kaam ke zariye Python buyer-side library. Inngest's step.run memoization saves duplicate payments par dobara try karein. wallet's on-chain paisa kharch karein limit hai safety ke protect karein karta hai aap, not per-request cap. verify karein header names against spec version aur facilitator aap integrate karein ke saath.

concept 11: MPP (Machine Payments protocol), sessions-based settlement protocol

ek line mein: MPP lets agent open ek prepaid tab ke saath ek spend cap, phir stream bohat se chota payments against yeh across kai rails until yeh closes tab.

yeh kya hai. MPP hai banaya gaya ke zariye Stripe aur Tempo, ke saath public launch announcements mein March 2026. Tempo hai ek layer-1 blockchain incubated ke zariye Stripe aur Paradigm ke liye high-frequency machine payments. MPP launched ke saath partners across Stripe, Visa, Lightspark ( Lightning Network), aur other ecosystem players; partner list grows, so verify karein against mpp.dev aur Cloudflare's MPP docs ke liye current participants. Apache 2.0. MPP hai Stripe's settlement-layer jawab to x402: overlapping use case, mukhtalif philosophy.

yeh kahan fit hota hai. MPP rehta hai par layer 4 (settlement) aur compete karta hai directly ke saath x402 ke liye machine-to-machine payments. key difference: MPP hai multi-rail aur supports both per-charge aur session-based authentication, jabke x402 hai stablecoin-only aur per-request.

** HTTP shape.** jahan x402 istemaal karta hai 402 code aur custom headers, MPP layers payment par standard HTTP authentication. server wapas deta hai WWW-Authenticate: Payment ke saath requirements, client dobara try karta hai ke saath Authorization: Payment <signed-payload>, aur server replies ke saath Payment-Receipt carrying settlement proof. yeh banata hai MPP feel like ek familiar HTTP auth flow rather se ek custom protocol.

** do intent types.**

Intent	lifecycle	Best ke liye
charge	ek ek-off transfer, authorized aur settled mein ek round-trip	Single purchases, ek-time API access, replace karna individual x402 calls jab aap zaroorat multi-rail
session	agent pre-authorizes ek cap aur ek duration, phir streams metered micropayments until yeh closes	High-frequency micropayments jahan signing har request hai expensive; recurring subscriptions; "Stripe Subscription ke liye agents" model

** trade against x402.**

Dimension	x402	MPP
authorization frequency	har request par (ek EIP-3009 signature har time)	Per charge ya per session (ek auth, bohat se metered calls)
HTTP shape	Custom 402 plus payment headers	Standard WWW-Authenticate / Authorization / Payment-Receipt
rails	stablecoin sirf (USDC par Base/Solana/EVM)	Multi-rail (Tempo stablecoin, Lightning, cards, ACH)
Fees	Zero protocol fee plus sub-cent gas	Stripe processing fees par card rails; near-zero par Tempo stablecoin
Recurring support	Limited (zaroorat hai per-period signing)	Native via session intent
Best fit	Ek-off API calls, public infrastructure	Recurring subscriptions, enterprise aur Stripe-integrated merchants, flows needing ek fiat fallback

SDK ke liye kya badalta hai. MPP integrates ke zariye Stripe Python SDK plus Stripe's MPP surface. integration leans par session management. harness hai same concept 8 baseline.

from stripe.mpp import MPPSession import aur stripe.MPPSession calls neeche hain illustrative. stripe.MPPSession aur stripe.mpp nahin hain mein Stripe Python SDK; MPP hai Stripe aur Tempo standard (mainnet March 18, 2026), integrated ke zariye Stripe's MPP surface. session concept (pre-authorize ek cap, stream metered calls) hai real; exact API yahan ek teaching stand-in. SDK scaffolding aur typed results hain real.

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

kya hai real: SDK scaffolding aur typed results. kya hai ek stand-in: stripe.MPPSession aur mpp_client. session lifecycle hai ek real pattern; exact Stripe API yahan simplified ke liye teaching. Yahan ek runnable mock:

from decimal import Decimal

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

yeh harness mein kya add karein karta hai. Ek configuration step: aapka Stripe account zaroorat hai MPP enabled. Tempo blockchain integration hai handled ke zariye Stripe's MPP server, so agent kabhi nahin touches Tempo directly. Beyond Stripe SDK aur key management (same ke taur par ACP), there hai kuch nahin extra.

isay durably chalana (Inngest). MPP sessions map cleanly par Inngest's long-running function pattern. session lifecycle (banayein, istemaal karein, close) becomes ek sequence ka step.run blocks, ke saath step.sleep available ke liye time-based expiry. session model aur durable execution compose karein well: both hain banaya gaya ke liye stateful, multi-step kaam.

teams yahan kahan ghalti karti hain. yeh banayein sessions ke hain bhi bara ya bhi long. session cap hai aapka loss limit agar kuch bhi jata hai ghalat. ek $1,000 session set "ke liye convenience" exposes aap to $1,000 ka agent-loop-gone-ghalat losses. Right-size sessions to asal expected kaam: ke liye ek 30-call task, ek $5 session lasting 5 minutes hai safer se ek $50 session lasting ek hour.

bottom line ka concept 11: MPP hai Stripe's settlement-layer jawab to x402, tuned ke liye sessions-based metering aur multi-rail dispatch. Do intents, charge ke liye ek-offs aur session ke liye pre-authorized streaming, cover both single purchases aur recurring metering. session primitive hai cheaper se x402 ke liye high-frequency calls, aur multi-rail dispatch handles stablecoin, Lightning, aur cards mein ek envelope. HTTP shape istemaal karta hai standard WWW-Authenticate: Payment aur Authorization: Payment instead ka x402's custom headers, kaun sa banata hai yeh feel like familiar auth. aap integrate karein via Stripe SDK aur Stripe's MPP surface, aur Inngest's durable execution compose karta hai well ke saath session lifecycle. Right-size session caps to expected kaam, not to "convenience."

---

part 4: Composition rules, jab to istemaal karein kaun sa protocols saath

part 3 walked four protocols ek par ek time. ab hum put inhein back saath. aap met idea mein part 1: ek real system istemaal karta hai kai protocols par once, ek per layer. part 4 deta hai aap rules ke liye kaun sa combinations kaam, kaun sa fail, aur kaise to rakhein stack ke taur par chota ke taur par job allows.

concept 12: minimum viable agent-payment stack

ek line mein: sahi stack hai sab se chota set ka protocols ke ship karta hai value ke liye ek use case, not sab four protocols par har layer.

pehle aap compose karein kuch bhi, poochein ek sawal: kya hai sab se chota stack ke ship karta hai value here? jawab hai almost kabhi nahin "sab four protocols, har layer." zyada tar production systems shuru karein ke saath ek layer fully wired aur add karein rest sirf jab use case forces yeh.

Yahan sab se chota stack ke liye har common use case. yeh bhi previews five decisions mein part 5.

use case	layer 1 (discovery)	layer 2 (Auth)	layer 3 (commerce)	layer 4 (settlement)	kyun yeh hai MVP
consumer shopping (agent kharidta hai retail goods ke liye ek person)	AI shopping surface, ya ek MCP server ke saath ek merchant catalog	ACP SPT (ya ek AP2 mandate mein regulated fields)	ACP	card rails via Stripe	zyada tar buyers chahte hain chargeback cover. ACP plus Stripe hai path ke ship karta hai aaj.
API-paying agent (agent calls third-party APIs ke charge)	MCP server ke saath x402 support, ya ek agent.market directory	EIP-3009 signature ( x402 default)	koi nahin: direct API call	x402 par Base ya Solana	ke liye machine-to-machine, layers 2 aur 4 collapse karein. There koi nahin purchase lifecycle.
enterprise procurement (agent kharidta hai se approved suppliers ke neeche rules)	A2A discovery andar partner network	AP2 Intent mandate (required ke liye audit)	ACP ya UCP ke liye catalog suppliers; direct API ke liye service kharidta hai	MPP sessions ke liye recurring; ACP SPT via card rails ke liye ek-off	audit trail hai part aap nahin kar sakte skip karein. AP2 mandates hain required.
multi-agent marketplace (agent hires other agents)	A2A ya ek agent directory	AP2 mandate plus ek ERC-8004 reputation check karein	koi nahin: direct agent-to-agent	x402 (zyada tar common), ya MPP agar Stripe hai pehle se wired	Trust chalta hai both ways. har side zaroorat hai verifiable identity aur payment proof.

** composition rule.** chunein protocol par har layer use case demands. add na karein karein protocols par layers use case kabhi nahin touches. ek pure API-paying agent nahin karta zaroorat ACP. ek consumer-shopping agent nahin chahiye reach ke liye x402 par ek $50 t-shirt, kyun ke chargeback cover par cards hai worth 2.9% fee.

** trap.** kuch teams try to wire karein ACP, AP2, x402, aur MPP sab par once "ke liye flexibility." aap milta hai four times integration surface aur no clear jawab to "kaun sa protocol fires jab." ek chunein stack. Ship yeh. add karein ek doosra stack sirf jab ek doosra use case demands yeh.

bottom line ka concept 12: minimum viable stack hai sab se chota protocol set ke ship karta hai value ke liye ek use case. Four common stacks cover zyada tar ka yeh. consumer shopping hai ACP plus card rails. API-paying hai x402 akela. enterprise procurement hai AP2 plus ACP ya UCP plus MPP ya cards. ek multi-agent marketplace hai AP2 plus ERC-8004 plus x402. mat ek banayein universal stack; ek chunein composition per use case aur ship yeh.

concept 13: jab protocols compose karein across layers aur compete karte hain ke andar ek

ek line mein: protocols par mukhtalif layers hain banaya gaya to stack saath; protocols par same layer hain banaya gaya to replace karein har other, so sirf sawal hai whether do protocols sit par same layer.

Do protocols relate mein ek ka do ways. yeh either compose karein, kyun ke yeh sit par mukhtalif layers aur banaya gaya to stack, ya yeh compete karte hain, kyun ke yeh sit par same layer aur banaya gaya to substitute. zyada tar architectural confusion comes se reading doosra case ke taur par pehla.

across layers, banaya gaya to compose karein:

Composition	layer mapping	jahan yeh ship karta hai
AP2 + ACP	AP2 par layer 2 (audit-grade auth), ACP par layer 3 (commerce)	Regulated fields jahan ACP's normal flow zaroorat hai extra audit
AP2 + x402	AP2 par layer 2 (mandate auth), x402 par layer 4 (stablecoin settlement)	Crypto-native flows ke phir bhi zaroorat audit, via a2a-x402 extension
ACP + x402	ACP par layer 3 (commerce), x402 par layer 4 ke liye machine-to-machine sub-flows andar ek consumer purchase	Hybrid platforms jahan ek consumer kharidein includes kuch API paisa kharch karein
MCP + x402 (via withX402Client)	MCP par layer 1 (discovery), x402 par layer 4 (settlement)	Cloudflare's standard pattern ke liye paid MCP tools

ke andar ek layer, banaya gaya to compete karte hain:

Competition	layer	jab har wins
AP2 vs. ACP SPT vs. TAP	layer 2	AP2 ke liye audit-grade flows; ACP SPT ke liye Stripe-wired consumer flows; TAP ke liye identity-only check karta hai
ACP vs. UCP	layer 3	ACP ke liye ChatGPT reach; UCP ke liye Gemini reach; both ke liye cross-surface sellers
x402 vs. MPP	layer 4	x402 ke liye ek-off micropayments aur pure stablecoin flows; MPP ke liye sessions, subscriptions, aur multi-rail flows

** test.** jab aap hain stuck ke darmiyan do protocols, poochein ek cheez: hain yeh par same layer? agar yes, aap ek chunein, ya aap pay karein to support both ke liye mukhtalif sub-flows. agar no, yeh probably compose karein, aur sahi design aksar istemaal karta hai both.

ek worked composition: AP2 + x402 stack. yeh hai crypto-native pattern, common ab mein B2B aur agent-to-agent flows:

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 assembly sirf compose karta hai per-protocol tools se part 3. yeh tools (a2a_discover_partners, ap2_create_intent_mandate, aur rest) hain defined back mein concepts 8 ke zariye 11; here aap sirf wire karein inhein par ek 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.
)

bottom line ka concept 13: protocols par mukhtalif layers compose karein: AP2 plus x402, ACP plus x402, MCP plus x402. protocols par same layer compete karte hain: AP2 against ACP SPT, ACP against UCP, x402 against MPP. test hai "hain yeh par same layer?" agar yes, ek chunein. agar no, yeh likely compose karein. AP2 plus x402 stack hai standard crypto-native B2B composition.

concept 14: cost aur latency, kya forces choice

ek line mein: Transaction size aur wait karein aap kar sakta hai accept decide settlement protocol, kyun ke card fees crush chota payments aur slow checkouts break tight loops.

har composition rakhta hai ek price aur ek speed. ek consumer-shopping flow par ACP plus card rails costs ke bare mein 2.9% + $0.30 har transaction par aur takes 5 to 30 seconds end to end. ek API-paying agent par x402 costs ke neeche ek cent aur takes 1 to 2 seconds. sahi composition hai partly set ke zariye kya cost aur kya wait karein aapka use case kar sakta hai absorb.

cost har transaction par ke zariye composition.

Composition	Typical cost har transaction par	Typical latency
ACP + card rails (consumer shopping)	2.9% + $0.30 (Stripe rate)	5 to 30 seconds
ACP + MPP sessions (subscriptions)	2.9% par cards, ya ke bare mein 0.5% par Tempo stablecoin, har session par	1 to 3 seconds per metered call
AP2 + x402 (B2B stablecoin)	Sub-cent gas, zero protocol fees	2 to 5 seconds (mandate signing add karta hai 1 to 3)
x402 sirf (API-paying)	Sub-cent gas, zero protocol fees	1 to 2 seconds
MPP sessions sirf (recurring API)	Near zero par Tempo stablecoin; Stripe rate par cards	50 to 500 ms per metered call andar ek active session

kya paisa forces. Fees oopar ke bare mein 5% ka transaction hain ek problem. ek $0.05 API call ke pay karta hai 2.9% + $0.30 mein card fees costs more mein fees se call hai worth, kaun sa hai ek clear signal to istemaal karein x402 ya MPP stablecoin instead. ek $50 t-shirt paying same 2.9% + $0.30 hai fine. dollar line jahan card rails stop making sense hai around $5 to $10. neeche yeh, machine-payment rails win; oopar yeh, chargeback cover par cards hai aksar worth fee.

kya latency forces. ek wait karein oopar 5 seconds per user-facing step hai ek problem. AP2 mandate signing kar sakta hai add karein 1 to 3 seconds, bohat longer agar yeh wait karta hai par ek human signature; ACP checkout add karta hai 5 to 30. ke liye agent-to-agent flows ke saath human loop mein nahin, budget hai tighter phir bhi, aksar sub-second, kaun sa banata hai x402 par Base aur MPP par Tempo default chunta hai.

** decision tree, compressed.**

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

bottom line ka concept 14: Composition choices rakhte hain real cost aur latency. card rails cost 2.9% + $0.30 lekin dein aap chargeback cover; stablecoin rails cost ke neeche ek cent lekin zaroorat crypto-native plumbing. card rails stop making sense around $5 to $10 har transaction par. ACP checkout milta hai bhi slow around 5 seconds ke liye user-facing flows. Let cost aur latency force composition, not taste.

---

part 5: decision lab, five worked misaalein

parts 2 ke zariye 4 gave aap framework: four layers, ek kam protocols per layer, composition across layers. part 5 walks five real decisions. har ek dikhata hai full reasoning: kya layers use case touches, kaun sa protocol par har layer, kyun, aur kya agent code lagta hai like.

parhein across ek row to dekhein ek use case's full stack. parhein down ek column to dekhein kya changes par ek layer ke taur par use case changes. five decisions neeche walk rows mein detail. pehla four cover matrix; fifth rebuilds ek ka inhein mein ek completely mukhtalif toolchain to sabit karein framework nahin hai tied to koi bhi ek vendor.

decision 1: consumer shopping agent ( ChatGPT Instant checkout pattern)

use case. aap hain building ek agent ke helps people shop par ACP-enabled merchants like Walmart, Etsy, aur Shopify sellers. user says kya yeh chahte hain; agent searches catalogs, dikhata hai options, aur check karta hai out par confirmation. Single buyer to single merchant, $5 to $500 per order, refunds aur chargebacks required.

four layers ko walk karna.

• Layer 1 (discovery). agent rakhta hai to find products across bohat se merchants. aap kar sakta tha integrate karein har merchant's MCP catalog, ya istemaal karein ChatGPT Shopping surface ke pehle se aggregates ACP merchants. Choice: AI shopping surface, kyun ke discovery kaam hai pehle se done aur wiring up ek million catalogs yourself nahin hai viable.
• Layer 2 (authorization). user hai signed mein surface aur confirms har kharidein, so authorization hai simple. Choice: ACP SPT, minted ke zariye Stripe per purchase, scoped to ek merchant, ek amount, aur ek 10-minute window.
• Layer 3 (commerce). full lifecycle matters: cart, checkout, fulfillment, disputes, aur refunds. Choice: ACP, protocol banaya gaya ke liye exactly yeh.
• Layer 4 (settlement). values ka $5 to $500 sit sahi mein card-rail sweet spot, aur chargeback cover hai worth fee. Choice: card rails via Stripe, rail ACP assumes ke zariye default.

implementation. yeh hai concept 8's code; tools come se concept 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",
)

zyada tar likely failure production mein. cart mismatches: agent banata hai ek cart ke nahin karta match request ("I asked ke liye red, got pink"). Fix: require user to confirm cart pehle SPT hai minted, log cart-accuracy, aur tune instructions jab accuracy drops neeche 95%.

isay durably chalana (Inngest). istemaal karein step.wait_for_event pattern se concept 8 ke liye cart-confirmation gate, plus ek per-user concurrency cap.

chunein yeh ek pehla. yeh hai live use case aaj: ChatGPT Instant checkout, ACP ecosystem, har Shopify merchant ke saath ACP turned par. agar aap kar sakta hai sirf ship ek composition, ship yeh ek.

decision 2: API-paying research agent ( x402-sirf pattern)

use case. aap hain building ek research agent ke pay karta hai third-party APIs ke liye data: financial feeds, news, specialized search. yeh discovers paid APIs par runtime ke zariye ek directory like agent.market, weighs cost against value, aur pay karta hai per call. High-frequency micropayments ka $0.001 to $0.50, human loop mein nahin baad task shuru hota hai, no commerce lifecycle.

four layers ko walk karna.

• Layer 1 (discovery). agent.market aur similar x402-paywalled directories let agent find services par runtime; MCP servers ke saath x402 support handle pre-integrated ones. Choice: agent.market plus MCP-via-Cloudflare, runtime discovery ke saath ek pre-wired fallback set.
• Layers 2 aur 4 (authorization aur settlement, collapsed). No human baad task shuru karein. wallet's on-chain caps bound per-transaction paisa kharch karein; user-level caps chalayein via ek SDK tool_input_guardrail par har paying tool. EIP-3009 signature hai both authorization aur settlement. Choice: x402 par Base (USDC), ke saath no separate mandate protocol.
• Layer 3 (commerce). "purchase" hai sirf ek API call. Choice: koi nahin, direct API access via x402.

implementation. yeh hai concept 10's code; tools come se concept 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.
)

zyada tar likely failure production mein. Runaway paisa kharch karein se ek stuck loop: agent re-fetches same data aur burns budget. Fix: wallet's on-chain caps ( safety ke actually protect karein karta hai aap), SDK session-spend guardrails, aur ek dedup cache so identical fetches mat re-pay.

isay durably chalana (Inngest). step.run memoization pay karta hai off here. Crash mid-session aur dobara try karein resumes ke saath already-paid-for data intact. ek per-user concurrency cap stops ek burst se taking ke upar.

Pure machine-to-machine. layers 2 aur 4 collapse karein mein ek signature, aur layer 3 hai empty. yeh stack hai structurally simpler se decision 1: fewer protocols, fewer integration points, lower cost per call. trade koi nahin chargeback cover aur no commerce semantics, kaun sa hai fine kyun ke use case zaroorat hai neither.

decision 3: enterprise procurement agent ( AP2 plus composed-stack pattern)

use case. aap hain building ek procurement agent ke liye ek regulated enterprise mein financial services. Buyers delegate tasks: "kharidein 50 ergonomic keyboards se hamara approved suppliers, ke neeche $5,000, ke zariye Friday." audit trail hai legally required, paisa kharch karein caps chalayein par kai levels, aur suppliers hain pre-approved, so there koi nahin runtime discovery.

four layers ko walk karna.

• Layer 1 (discovery). supplier list hai known mein advance. Choice: ek internal MCP server ke saath supplier catalogs, kyun ke discovery scope hai bounded.
• Layer 2 (authorization). ek non-repudiable audit trail hai part aap nahin kar sakte skip karein; ek non-repudiable record hai ek signer nahin kar sakta baad mein deny. AP2 mandates dein exactly ke. Choice: AP2, ke saath ek Intent mandate par task creation, ek cart mandate pehle checkout, aur ek Payment mandate par settlement, har signed ke zariye procurement officer.
• Layer 3 (commerce). Large suppliers expose ACP ya UCP; smaller ones expose direct B2B APIs. Choice: ACP ke liye ACP-enabled suppliers, direct API ke liye rest; agent handles both.
• Layer 4 (settlement). Recurring suppliers favor MPP sessions; ek-off kharidta hai favor card rails ke liye chargeback cover par higher values. Choice: MPP sessions ke liye recurring, ACP SPT plus card rails ke liye ek-off, chuna ke zariye supplier history.

implementation. yeh compose karta hai tools se concepts 8, 9, aur 11.

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

zyada tar likely failure production mein. Intent mandate scope mismatches: officer sign karta hai ek mandate, agent karta hai kaam, phir cart nahin karta fit mandate. Fix: validate karein mandate scope agent shuru hone se pehle shopping (concept 9's "banayein Intent mandates pehla"), aur reject tasks kis ka scope exceeds kya user authorize kar sakta hai karein.

isay durably chalana (Inngest). AP2 mandate signing hai natural fit ke liye step.wait_for_event. Multi-stage tasks istemaal karein step.run per stage, ke saath ek per-user concurrency cap.

Regulated industry. Audit rules force AP2 par layer 2; bohat se suppliers force ACP aur direct APIs saath par layer 3; recurring versus ek-off forces MPP aur cards saath par layer 4. yeh composition hai heavier se decisions 1 aur 2, aur audit requirement hai kya justifies weight.

decision 4: multi-agent marketplace ( AP2 plus x402 plus ERC-8004 pattern)

use case. aap hain building ek platform jahan agents hire other agents. agent ek zaroorat hai research; agent B bechta hai research ke taur par ek x402 service. Neither trusts other yet, transactions lazmi hona verifiable, aur payment hai pure crypto-native ke saath no cards. agent to agent, $0.10 to $100 har transaction par, both sides zaroorat verifiable identity.

four layers ko walk karna.

• Layer 1 (discovery). agent B publishes iska capability ke upar A2A; agent ek finds yeh. Choice: A2A, protocol banaya gaya ke liye yeh.
• Layer 2 (authorization). No human par transaction time, lekin trust lazmi hona verifiable both ways. AP2 mandates sabit karein user consent; ERC-8004 deta hai agent B ek on-chain reputation agent ek check kar sakta hai pehla. Choice: AP2 plus ERC-8004, composed ke liye full bilateral verification.
• Layer 3 (commerce). No carts, no refunds, sirf "karein yeh task aur deliver report." Choice: koi nahin, direct A2A request aur response.
• Layer 4 (settlement). Crypto-native, sub-second, no chargeback cover zaroori tha. Choice: x402 via a2a-x402 extension to AP2.

implementation. yeh compose karta hai tools se concepts 9 aur 10 ke saath A2A discovery.

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

zyada tar likely failure production mein. Trusting ek reputation ke rakhta hai hua gamed: ERC-8004 scores hain auditable lekin ek operator kar sakta hai inflate ek ke saath chota successful jobs. Fix: combine reputation ke saath other signals (operator identity, transaction-volume thresholds, dispute history), aur add karein human review oopar ek set amount ke liye first-time counterparties.

isay durably chalana (Inngest). Fan out jab hiring kai specialists par once; istemaal karein step.wait_for_event ke liye har result aur step.run per stage. yeh decision touches har Inngest primitive.

Pure multi-agent economy. human loop mein nahin par transaction time; both agents act andar pre-authorized scopes. yeh hai shape agent economy hai hona banaya gaya around, aur yeh rakhta hai sab se zyada failure modes, kyun ke bilateral trust ke saath no prior relationship hai hard aur protocol stack sirf partly solves yeh.

decision 5: ek non-Stripe, non-OpenAI stack (proving framework travels)

har code sample so far istemaal hua stripe.PaymentTokens.create(...) aur OpenAI agents SDK. woh hain sab se zyada mature integrations ke liye ACP aur SDK hai yeh course's runtime, lekin four-layer architecture hai stack-agnostic ke zariye design, aur ek course ke sirf dikhata hai ek stack rakhta hai not proven ke. So yeh decision rebuilds decision 2, API-paying research agent, par ek completely mukhtalif toolchain: Google's agent Development Kit (ADK) ke liye runtime, ek Coinbase smart-contract wallet ke liye on-chain identity, AP2 mandates ke liye authorization, aur direct x402 ke liye settlement. Zero Stripe, zero OpenAI.

use case stays decision 2's. ek research agent paying $0.001 to $0.10 per call, capped par $10 har session par. Sub-dollar, no human baad authorization, machine-to-machine settlement. architecture stays decision 2's bhi: x402 collapse hota hai layers 2 aur 4, commerce layer nahin, MCP ke liye discovery. sirf library changes.

block neeche hai illustrative. Google ADK structure (Agent, tool decorator) hai real aur google-adk hai ek real package. payment pieces hain stand-ins: AP2's real package hai ap2 ke saath bohat mukhtalif mandate fields aur no MandateSigner class, Coinbase wallet hai configured ke zariye coinbase_agentkit's SmartWalletProvider, aur ek live x402 call zaroorat hai ek funded account aur ek real 402 endpoint. No real paisa move karta hai here. point hai shape, not ek runnable buyer.

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

** line-by-line translation.** decision 2's OpenAI plus Stripe code par left, decision 5's Google ADK plus Coinbase code par sahi. yeh table hai payoff: har row hai same concept ke neeche ek mukhtalif name.

decision 2 (OpenAI + Stripe)	decision 5 (Google ADK + Coinbase)	same concept, mukhtalif 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 decorator
RunContextWrapper	context={...} kwarg to run_async	Per-run state
stripe.Customer.modify(...) ke liye caps	SmartWalletProvider(spend_limits={...})	paisa kharch karein caps, chain-native
tool_input_guardrail decorator	in-tool check karein + wallet caps	Pre-execution validation
Runner.run(agent, ...)	agent.run_async(...)	agent execution

kya cheez same rehti hai. architecture: layer 1 hai MCP ya ek directory, layer 2 hai ek mandate plus wallet caps, layer 3 hai koi nahin (machine-to-machine collapse hota hai commerce), layer 4 hai x402. primitives: Intent mandate, EIP-3009 signatures, 402 responses, payment-signature headers, on-chain paisa kharch karein caps. framework hai kya survives library swap.

karein real operational differences.

1. Google ADK ke paas koi nahin first-class tool input guardrail (ke taur par ka mid-2026). SDK's tool_input_guardrail hai genuinely handy ke liye pre-execution check karta hai; ADK's tool decorator ke paas koi nahin direct equal yet. workaround hai in-tool validation backed ke zariye wallet's on-chain caps. caps phir bhi protect karein aap; in-tool check karein sirf fail hota hai faster. chunein ADK aur aap trade guardrail convenience ke liye ek mukhtalif multi-agent story.
2. AP2 mandate signing hai more native here. Google banaya gaya AP2, so ADK ecosystem integrates mandate-signing UI flows more cleanly. agar aapka use case leans hard par mandate-rigorous authorization (decisions 3 aur 4), ADK plus AP2 hai ek real fit, not sirf ek alternative.

bottom line ka decision 5: four-layer architecture nahin hai ek Stripe-and-OpenAI story mein disguise. discovery, authorization, commerce, settlement, ek chunein protocol per layer, justify yeh against use case: ke survives koi bhi library swap. decision 5 istemaal hua Google ADK aur ek Coinbase wallet to banayein exact same composition ke taur par decision 2; sirf imports changed. agar ek framework nahin kar sakta hona expressed mein ek mukhtalif stack, yeh hai ek library tutorial wearing ek costume. yeh ek nahin hai.

---

part 6: Production concerns: kya kills aap jab system jata hai live

parts 1 ke zariye 5 banaya gaya framework aur walked real decisions. part 6 covers cheezen ke decide whether aapka stack survives real users. yeh hain failures ke mat dikhayein up mein ek demo aur karein dikhayein up par 2 ek.m.

reader track

agar aap hain reading to understand, not to ship, aap kar sakta hai skim part 6. agar aap hain building koi bhi ka yeh ke liye real, yeh hai jahan yeh milta hai real. four concepts here hain difference ke darmiyan ek system ke kaam karta hai aur ek system ke drain karein karta hai ek wallet.

concept 15: Spend-limit enforcement par teen architectural levels

ek line mein: Stop ek agent se overspending ke zariye enforcing limit mein teen independent places, so ek bug mein ek hai caught ke zariye other do.

single biggest way ek agent-commerce system fail hota hai badly hai simple: agent paisa kharch karta hai more se yeh tha allowed to. ek stuck agent loop kar sakta hai drain karein ek wallet mein seconds. har protocol rakhta hai iska own cap (ACP's SPT amount, MPP's session cap, x402's per-request max), lekin no single ek ka inhein hai kaafi par iska own. Production systems enforce spend limits par teen separate levels.

Level 1: wallet aur payment-method limits. yeh hai cap ke actually protect karein karta hai aap. agent's smart-contract wallet (ke liye x402) ya iska Stripe customer account (ke liye ACP aur MPP) carries paisa kharch karein caps set par infrastructure level. chain ya Stripe enforces inhein no matter kya agent code karta hai. yeh hai sirf level ke hold karta hai jab agent loop fail hota hai completely.

ke liye x402 ke saath ek smart-contract wallet:

SmartContractWallet.deploy(...) call neeche hai illustrative. yeh dikhata hai jahan Level 1 caps live, not ek real pip package. practice mein aap set yeh caps par ek real smart-contract wallet (ke liye misaal ke zariye Coinbase AgentKit's SmartWalletProvider). teen-level discipline hai real lesson.

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
)

ke liye ACP ya MPP ke saath Stripe, cap rehta hai par Stripe customer:

stripe.Customer.modify(...) hai ek real Stripe API call. yeh chalta hai against aapka Stripe account.

# 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.

Level 2: SDK tool guardrails. OpenAI agents SDK's tool_input_guardrail chalta hai pehle har payment tool executes aur reject kar sakta hai call. aap met yeh mein concept 5: yeh hai SDK-native way to stop ek payment pehle yeh happens, aur family ke chalta hai mein time. Here yeh milta hai full treatment, kyun ke yeh hai canonical guardrail block ke liye poora course. code neeche hai real aur chalta hai.

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
)

istemaal karein sahi guardrail family

SDK rakhta hai teen guardrail families. Input guardrails chalayein par user's pehla message to agent. Output guardrails chalayein par agent's final reply. tool guardrails (tool_input_guardrail aur tool_output_guardrail) chalayein par har custom tool call. ke liye payment safety aap chahte hain tool_input_guardrail specifically: yeh hai sirf family ke fires pehle ek payment tool chalta hai aur kar sakta hai block yeh. Reaching ke liye output_guardrail to control paisa kharch karein hai single zyada tar common mistake mein agent-commerce code. ke zariye time yeh fires, paisa hai gone.

Level 3: application aur business-logic limits. aapka own code enforces user-specific rules: per-user daily caps, per-category caps, allowed merchants. yeh hai jahan business rules live. "yeh user kar sakta hai paisa kharch karein $500 ek day par koi bhi merchant, lekin sirf $50 ek day par unverified ones." ke rule belongs here, not mein ek protocol. yeh code hai plain Python aur real.

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

har level rehta hai mein mukhtalif infrastructure. Level 1 hai mein chain ya Stripe. Level 2 hai mein agent SDK. Level 3 hai mein aapka application code. ek bug mein ek hai caught ke zariye other do. skip karein Level 1 aur ek agent-loop bug kar sakta hai drain karein poora wallet. skip karein Level 2 aur aap lose power to abort ek chalayein mid-flight. skip karein Level 3 aur aap nahin kar sakta enforce per-user ya per-category policy.

trap hai trusting protocol caps akela. ACP's SPT cap, MPP's session cap, aur x402's per-request max hain protocol-level limits. yeh stop specific protocol abuse, lekin yeh add na karein karein up across protocols. ek team istemaal karte hue sirf ACP SPTs ke saath ek $50 cap har ke paas koi nahin protection against ek agent minting 100 ka inhein mein ek row, ke liye $5,000 total. teen levels oopar exist precisely kyun ke protocol caps mat aggregate.

bottom line ka concept 15: Enforce spend limits par teen independent levels: wallet ya payment-method infrastructure, SDK tool guardrails (tool_input_guardrail specifically, since yeh chalta hai pehle har tool aur kar sakta hai block yeh), aur application business logic. har level istemaal karta hai mukhtalif infrastructure, so ek bug mein ek hai caught ke zariye others. sab se zyada common mistake hai istemaal karte hue agent-level output_guardrail ke liye paisa kharch karein control. yeh chalta hai par final reply, bhi late, payment pehle se happened. Protocol-level caps (SPT, MPP session, x402 per-request) hain necessary lekin kaafi nahin; yeh mat aggregate across protocols ya across chalta hai. Production systems enforce par sab teen.

concept 16: agent identity hygiene: keys, wallets, aur audit logs

ek line mein: agent's signing key hai sirf cheez separating authorized spend se fraud, so aap protect karein key, separate yeh per agent, rotate yeh, aur log har paisa kharch karein to durable storage.

agent commerce brings ek failure ke hai unique to autonomous systems: agent's cryptographic identity hai sab ke stands ke darmiyan real spend aur fraud. agar signing key leaks, wallet (ya Stripe customer, ya AP2 mandate signer) ho sakta hai drained ya impersonated until aap rotate key. identity hygiene hai set ka habits ke prevents yeh. There hain four.

1. Per-agent wallet separation. har agent, ya har class ka agent, milta hai iska own wallet ya payment handle. kabhi nahin share signing keys across agents ke saath mukhtalif jobs. agar aapka shopping agent aur aapka procurement agent share ek wallet, ek compromise ka either drain karein karta hai both. Separate wallets cost almost kuch nahin (ek ek-time deployment cost) aur security gain hai real.

SmartContractWallet.deploy(...) hai illustrative, ke taur par mein concept 15. pattern hai kya matters: ek wallet per agent class, kabhi nahin shared.

# 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, par ek schedule aur par demand. Rotate signing keys har 90 days ke taur par ek baseline (matching Stripe's advice ke liye API keys). Rotate inhein sahi away jab ek agent operator leaves team, jab ek deployment touches signing surface, ya jab kuch lagta hai ghalat. habit ka rotating matters more se exact number ka days.

pattern neeche hai real. client name azure_key_vault hai illustrative; istemaal karein aapka provider's vault SDK. point hai ke key rehta hai mein ek vault aur aap parhein current version par istemaal karein time.

# 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 ke survive ek crash. har authorization decision milta hai logged to durable storage ke rehta hai apart se agent's runtime: har SPT minted, har mandate signed, har x402 signature, har MPP session opened. agar agent crashes, audit log lazmi phir bhi hona there. Neon Postgres plus Inngest's step memoization deta hai aap yeh; aap kar sakta hai bhi likhein straight to object storage (S3 ya equivalent) ke liye maximum durability.

audit-log pattern hai teaching. client name neon_client hai illustrative; istemaal karein aapka own database client. rule hai to log decision pehle payment happens.

# 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. Distributed traces across poora transaction. audit log tells aap kya succeeded. Traces tell aap kya happened, including calls ke fail hua, retried, ya stalled. mein agent commerce full trace hai aksar sirf way to debug ek fail hua transaction, kyun ke ek user request kar sakta hai fan out mein ek SDK chalayein, 5 to 10 tool calls, 2 ya 3 protocol HTTP requests, ek Stripe webhook ke arrives baad mein, aur ek Inngest function ke resumes hours afterward. ke baghair ek trace ID tying sab ka ke saath, ek post-mortem hai impossible. OpenTelemetry code neeche hai real, stable 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 context flows automatically ke zariye httpx, openai-agents, aur Inngest ke saath sahi instrumentation. jab ek Stripe webhook arrives 20 minutes baad mein ke liye ek dispute par yeh order, webhook handler joins same trace ke zariye trace_id carried mein order's metadata. Ek trace ID covers poora life ka transaction, se pehla request to dispute resolution.

audit logs aur traces jawab mukhtalif sawalat, aur aap zaroorat both. audit logs jawab business sawalat ("kaise bohat kiya yeh user paisa kharch karein par Tuesday?"). Traces jawab debugging sawalat ("kyun kiya checkout ke liye order abc123 fail?"). audit log sirf records successful path; yeh kabhi nahin captures call ke retried five times pehle working, ya protocol call ke stalled ke liye 30 seconds pehle timing out. woh failure shapes sirf appear mein traces. Skipping traces kyun ke aap rakhte hain audit logs hai ek mistake ke bare mein kya har tool hai ke liye.

sab se zyada common identity mistake hai treating wallet's address ke taur par agent's identity. address hai public: koi bhi kar sakta hai bhejein to yeh aur koi bhi kar sakta hai verify karein ek transaction came se yeh. private signing key hai identity, aur aap protect karein yeh ke taur par ek. teams ke rakhein signing keys mein environment variables (ya worse, mein source code) rakhte hain handed agent's identity to koi bhi ke saath access to woh secrets. Keys go mein ek vault, kabhi nahin mein env vars.

bottom line ka concept 16: agent identity hai cryptographic; signing key hai sirf cheez separating authorized spend se fraud. Four habits protect karein yeh. Per-agent wallet separation, so ek compromise nahin karta drain karein har agent. key rotation par ek schedule aur par demand (90-day baseline, immediate par ek trigger). audit logs to durable storage ke rehta hai apart se runtime (Neon Postgres ya object storage). Distributed traces ke saath ek trace ID spanning poora transaction (OpenTelemetry ke zariye SDK, httpx, Inngest, aur FastAPI). Signing keys go mein ek key vault, kabhi nahin mein environment variables ya source code. audit logs jawab business sawalat; traces jawab debugging sawalat; aap zaroorat both.

concept 17: dispute aur refund mechanics across four protocols

ek line mein: har protocol handles disputes aur refunds differently, aur dispute model aapka use case zaroorat hai hai aksar sab se strong cheez ke decides kaun sa protocols aap compose karein.

four protocols har treat disputes aur refunds mein inka own way, aur ke difference aksar decides protocol choice ke liye ek use case. ek use case ke zaroorat hai chargeback protection nahin kar sakta chalayein par pure x402. ek use case jahan seller ke paas koi nahin customer-service setup nahin kar sakta istemaal karein ACP. Yahan kaise har ek handles ek dispute, so aap kar sakta hai match protocol to dispute model aap actually zaroorat.

ACP: disputes ke zariye card network. kyun ke merchant stays merchant ka record mein ACP, har standard card-network dispute path kaam karta hai. buyer's bank shuru hota hai chargeback; Stripe (ya whichever processor) handles merchant's defense; merchant follows iska existing refund policy. yeh hai ACP's biggest practical advantage. har retail buyer's expectation ke bare mein wapas deta hai simply kaam karta hai.

ke liye ek ACP refund agent shuru hota hai:

acp_client.refunds.create(...) hai illustrative, like other ACP client calls hai course mein. result model aur tool wiring hain real.

@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 settled ke zariye audit trail. AP2's contribution to ek dispute hai mandate chain (Intent, phir cart, phir Payment). jab ek dispute comes up, ke chain hai evidence ka kya user actually authorized, aur yeh hold karta hai up legally. yeh nahin karta replace karein underlying rail's dispute path: agar AP2 mandate authorized ek card payment ke zariye Stripe, Stripe's dispute process phir bhi applies. AP2 add karta hai proof ka kya user agreed to.

dispute flow:

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: no formal dispute mechanism. Pure x402 payments hain non-refundable ke zariye design. payment settle hota hai on-chain mein ek se karein seconds; there koi nahin chargeback. yeh hai x402's biggest practical limit. yeh hai fine ke liye ek $0.001 API call (ek dispute hoga cost more se payment) aur ghalat ke liye kuch bhi jahan buyer ho sakta hai fairly chahte hain ek refund.

Teen ways to soften x402's no-refund property:

• Escrow. ke liye higher-value x402 payments, istemaal karein ek smart-contract escrow ke hold karta hai funds until buyer signals acceptance. ERC-8004 includes escrow primitives ke liye multi-agent transactions.
• compose karein ke saath AP2 aur ek mukhtalif rail. agar aap zaroorat x402's speed lekin bhi zaroorat dispute support, AP2 plus x402 composition deta hai aap mandate chain ke taur par evidence jabke x402 rakhta hai settlement fast. settlement khud hai phir bhi non-reversible; mandate sirf sabit karta hai kya tha agreed.
• seller guarantees. ke liye paid APIs, seller's terms aksar include refund rules enforced off-chain (seller voluntarily bhejta hai USDC back agar service fail hua). yeh kaam karta hai ke liye reputable sellers aur falls apart ke saath anonymous ones.

MPP: disputes ke zariye Stripe. MPP sessions settled par card rails inherit Stripe's standard dispute machinery, same ke taur par ACP. MPP sessions settled ke zariye stablecoin par Tempo, ya ke zariye Lightning, go ke zariye Stripe's seller-side dispute resolution. Stripe hold karta hai merchant accountable ke liye outcome regardless ka rail.

dispute model aap zaroorat aksar drives composition more se cost ya latency karein. ek consumer-shopping platform zaroorat hai chargebacks, so ACP fit hota hai. ek pure machine-to-machine API marketplace zaroorat koi nahin disputes par sab, so x402 fit hota hai. ek enterprise procurement platform zaroorat hai audit-grade evidence, so AP2 ke saath koi bhi settlement rail fit hota hai.

bottom line ka concept 17: dispute aur refund mechanics differ sharply across protocols. ACP inherits card-network chargebacks, so merchant's existing wapas dein policy kaam karta hai. AP2 provides mandate chain ke taur par legal evidence lekin nahin karta replace karein underlying rail's dispute path. x402 hai non-refundable ke zariye design: fine ke liye micropayments, ghalat jahan refunds matter. MPP inherits Stripe's dispute machinery across rails. dispute model aapka use case zaroorat hai hai aksar sab se strong cheez forcing protocol composition.

concept 18: FastAPI aur Inngest webhook plumbing: closing request aur response loop

ek line mein: kuch payment events arrive par inka own schedule (disputes, mandate signatures, seller-side payment requests), so aap zaroorat ek thin FastAPI handler to catch inhein aur ek Inngest event to carry kaam mein ek durable workflow.

parts 1 ke zariye 5, aur concepts 15 ke zariye 17, treated agent ke taur par ek buyer: yeh bhejta hai ek request, protocol replies, SDK reasons ke bare mein result. lekin agent commerce chalta hai both ways. Stripe bhejta hai charge.dispute.created webhooks. AP2 mandate signing happens off aapka server, par user's device, aur posts back baad mein. x402 sellers zaroorat ek server-side middleware ke wapas deta hai 402 Payment Required aur check karta hai X-PAYMENT headers. koi nahin ka yeh fit andar ek single Runner.run() call. yeh zaroorat FastAPI handlers ke taur par HTTP boundary aur Inngest events ke taur par bridge back mein durable workflows.

yeh concept walks teen patterns aap hoga zaroorat production mein. inke baghair, system rakhta hai cracks jahan async events fall ke zariye.

Pattern 1: ek Stripe webhook flowing mein ek suspended Inngest function. jab ek user files ek chargeback par ek ACP order, Stripe bhejta hai charge.dispute.created to aapka endpoint. yeh ho sakta hai arrive five minutes baad order ya 60 days baad mein. workflow ke placed order rakhta hai long since exited, lekin agent phir bhi zaroorat hai ke react: notify merchant, log to audit, maybe ek banayein defense. FastAPI handler turns webhook mein ek Inngest event, aur ek Inngest function chunta hai yeh up aur chalta hai ek agent to handle dispute.

stripe.Webhook.construct_event(...) aur stripe.error.SignatureVerificationError hain real Stripe APIs. Inngest wiring hai real. note firing API: events go out ke taur par send(events=[inngest.Event(...)]), not ek bare dict.

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

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

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

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

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

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

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

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

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

FastAPI handler stays thin (verify karein, phir fire ek event). Inngest function hai durable (idempotency, dobara try karta hai, step memoization). agent's reasoning happens andar Inngest function, kabhi nahin andar webhook handler. yeh split matters kyun ke Stripe expects ek 2xx response ke andar ke bare mein paanch seconds, aur ek agent chalayein kar sakta hai take 30 ya more.

Pattern 2: ek AP2 mandate-signing callback ke resumes ek suspended step.wait_for_event. concept 9 showed AP2 signing tool asking ke liye ek signature aur wait karein karna. production mein ke signing happens off aapka server: user opens inka phone app, sees mandate, taps Approve, aur signed mandate posts back. agent's Inngest workflow tha suspended par step.wait_for_event; FastAPI callback fires event ke wakes yeh.

signing callback hai aapka own FastAPI route. Inngest correlation istemaal karta hai if_exp= (ek CEL expression), aur awaited payload hai ke neeche async. prefix. wait_for_event wapas deta hai None par timeout. ap2_verify_signature aur persistence client hain illustrative; workflow shape hai real.

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's step.wait_for_event ke saath if_exp hai banaya gaya ke liye yeh. FastAPI handler hai ek ek-way bridge se HTTP mein Inngest's event bus. workflow ke suspended hours ago resumes ke saath signed payload, aur agent chunta hai up jahan yeh stopped.

Pattern 3: x402 seller-side middleware (jab aap expose ek paid API, not sirf consume ek). mein ek multi-agent marketplace (decision 4), aapka agent hai sometimes buyer aur sometimes seller, jahan other agents pay karein aapka ke liye research, analysis, ya code. seller side zaroorat hai ek FastAPI middleware ke wapas deta hai 402 Payment Required, check karta hai X-PAYMENT headers, aur serves resource sirf once ek facilitator rakhta hai verified payment.

seller-side X402Middleware neeche hai illustrative; there koi nahin x402_server PyPI package. real server-side x402 comes ke zariye x402 package's server aur facilitator helpers plus ek framework integration. symmetric buyer-and-seller idea hai real, aur FastAPI route hai real.

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 hai symmetric. buyer-side code se concept 10 aur seller-side middleware here hain do halves ka same protocol. ek multi-agent marketplace chalta hai both: iska agents kharidein se bahar services aur bechein to bahar agents.

Teen failures recur production mein:

1. Webhook handlers doing business logic inline. ek FastAPI handler ke chalta hai agent andar webhook response hoga blow past Stripe's five-second timeout. Stripe dobara try karta hai, agent chalta hai twice, aur aap charge user twice. handler stays thin; Inngest function hai durable.
2. Forgetting webhook idempotency. Stripe dobara try karta hai fail hua deliveries ke saath same event.id. ke baghair ek idempotency key par Inngest function, har dobara try karein banata hai ek duplicate. istemaal karein "event.data.raw_event_id" ke taur par idempotency key.
3. No signature check karein par callbacks. AP2 mandate-signed callbacks lazmi verify karein user's signature against registered public key. Otherwise koi bhi caller kar sakta hai forge mandate-signed events. ek fail hua check karein wapas deta hai ek 400, not ek logged warning.

bottom line ka concept 18: agent commerce hai bidirectional. protocol responses arrive synchronously aur SDK handles inhein, lekin disputes, mandate signatures, refunds, aur seller-side payment requests arrive asynchronously ke zariye webhooks aur callbacks. Teen patterns cover operational zaroorat. ek Stripe webhook handler fires ek Inngest event mein ek durable agent workflow ke liye disputes aur refunds. ek AP2 mandate-signed callback fires ek Inngest event ke resumes ek suspended step.wait_for_event ke liye out-ka-band signing. ek x402 seller-side FastAPI middleware exposes paid APIs ke saath verified payment. FastAPI handlers stay thin (verify karein aur fire); Inngest functions hain durable (idempotent aur retried). buyer-side framing se parts 1 to 5 hai incomplete ke baghair yeh teen; production systems chalayein sab teen.

---

part 7: Closing: kya yeh course tha waqai teaching

concept 19: discipline ka layered composition

ek line mein: sab kuch hai course mein reduces to ek job: parhein use case, break yeh mein four layers, aur chunein sahi protocol par har layer.

yeh course rakhta hai 19 concepts aur 5 decisions. sab ka inhein hain scaffolding ke liye ek claim: agent commerce mein 2026 nahin hai ek single protocol lekin ek layered architecture, aur aapka job hai to chunein sahi protocol par har layer ke liye use case mein front ka aap. sab kuch else follows se ke.

same shape dikhata hai up par teen scales.

par protocol scale, four headline protocols solve mukhtalif problems par mukhtalif layers: ACP par layer 3, AP2 par layer 2, x402 aur MPP par layer 4. Treating inhein ke taur par rivals par same layer hai sab se zyada common architectural mistake. yeh compete karte hain sirf jahan inka layers overlap (x402 against MPP par settlement; AP2 against ACP's SPT par authorization ke liye kuch flows). Everywhere else yeh compose karein.

par system scale, ek production system rakhta hai ek protocol se har layer, wired saath ke zariye OpenAI agents SDK ke taur par universal client. SDK's @function_tool, RunContextWrapper, aur tool_input_guardrail map cleanly to concerns par har layer. SDK hai protocol nahin. yeh hai orchestrator ke lets aap compose karein protocols cleanly.

par discipline scale, aapka job hai to parhein ek use case, break yeh mein four layers, chunein sahi protocol par har ek, aur justify har choice against use case's real constraints: transaction value, latency budget, dispute model, audit requirements. job nahin hai "ek chunein favorite protocol." yeh hai "ke liye yeh use case, kya karta hai har layer demand?"

five decisions mein part 5 walked real istemaal karein cases ke zariye yeh discipline. decision 1 (consumer shopping) landed par ACP plus Stripe card rails, kyun ke use case zaroori tha chargeback protection. decision 2 (ek API-paying agent) landed par x402 sirf, kyun ke layers 2 aur 4 collapse karein ke liye machine-to-machine flows. decision 3 (enterprise procurement) reached sab se zyada complex composition (AP2 plus ACP plus MPP), kyun ke audit aur recurrence zaroorat hai forced yeh. decision 4 (ek multi-agent marketplace) landed par AP2 plus ERC-8004 plus x402, kyun ke bilateral-trust zaroorat kar sakta tha not hona met koi bhi other way. decision 5 rebuilt decision 2 par ek completely mukhtalif stack (Google ADK plus ek Coinbase wallet plus AP2 plus x402), aur reached same four-layer shape, proving architecture nahin hai ek wrapper around Stripe aur OpenAI.

composition aap reach ke liye hai set ke zariye use case, not ke zariye taste. ek team ke chunta hai x402 kyun ke "stablecoins hain future" lekin hai building ek consumer shopping experience rakhta hai ghalat composition. ek team ke chunta hai ACP kyun ke "Stripe hai enterprise-grade" lekin hai paying ke liye API access par $0.001 ek call rakhta hai ghalat composition. Let use case drive choice.

bottom line ka concept 19, aur ka yeh course: four protocols (ACP, AP2, x402, MPP) hain layers, alternatives nahin. aapka job hai to parhein use case, break yeh mein four layers (discovery, authorization, commerce, settlement), chunein sahi protocol par har layer, aur justify choice against use case's real constraints. OpenAI agents SDK hai universal client ke compose karta hai chuna hua protocols. discipline survives whichever protocols win mein agla 24 months. layers hain stable, even ke taur par protocols par har layer evolve.

---

Cheat sheet: framework mein ek page

Print yeh. Tape yeh to wall. istemaal karein yeh jab reviewing koi bhi agent-commerce design.

four layers (memorize yeh 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?"

protocols par har layer (top chunta hai mein 2026)

layer	Top chunta hai	chunein ke zariye
discovery	MCP, A2A, agent directories, AI shopping surfaces	jahan agent's zaroori tha services live
authorization	AP2 mandates, ACP SPT, TAP, ERC-8004	Trust model: audit-rigorous, Stripe-native, identity-only, ya multi-agent
commerce	ACP, UCP, direct API (koi nahin)	karta hai use case zaroorat ek commerce lifecycle?
settlement	x402, MPP, card rails, bank/Lightning	Economics: transaction value drives rail

four canonical compositions

use case	stack
consumer shopping	AI surface + ACP SPT + ACP + Stripe cards
API-paying agent	MCP/directory + EIP-3009 + (koi nahin) + x402
enterprise procurement	A2A/MCP + AP2 + ACP/UCP + MPP/cards
multi-agent marketplace	A2A + AP2 + ERC-8004 + (koi nahin) + x402

Spend-limit enforcement par teen levels (required)

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)

skip karein koi bhi ka yeh aur aap hain ek bug away se ek total drain karein. sab se zyada common mistake hai istemaal karte hue agent-level output_guardrail ke liye Level 2. yeh fires par final agent reply, bhi late to stop ek payment. istemaal karein tool_input_guardrail instead.

economic threshold (memorize yeh)

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 (aksar sab se strong constraint)

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 checklist pehle launch

• wallet/payment-method spend limits configured par Level 1
• SDK tool_input_guardrail attached to har payment-authorizing tool (Level 2)
• Application enforces per-user, per-category, aur per-merchant caps (Level 3)
• Signing keys mein ek key vault (Azure key vault ya equivalent), kabhi nahin mein env vars
• Per-agent wallet separation (no shared keys across agent classes)
• key rotation schedule defined (90-day baseline)
• audit logs to durable storage independent ka agent runtime
• OpenTelemetry traces span SDK, httpx, Inngest, aur FastAPI; ek trace ID har transaction par
• Pydantic models par har boundary (tool wapas deta hai, protocol payloads, FastAPI bodies, Inngest events)
• Decimal ke liye paisa everywhere (kabhi nahin float)
• Stripe webhook handler verify karta hai signature aur fires ek Inngest event (thin handler, durable function)
• AP2 mandate-signed callback verify karta hai signature aur resumes step.wait_for_event
• agar exposing paid APIs: x402 seller-side middleware configured per route
• Inngest idempotency key set par har webhook-triggered function
• dispute aur refund mechanism understood aur documented per protocol
• human-in--loop confirmation gate ke liye pehla 30 days ka production
• Cart-accuracy metric measured pehle relaxing confirmation gate

---

Quick reference: decision tree, compressed

jab aap rakhte hain ek naya use case, walk yeh 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-minute refresher: 19 concepts mein ek sentence har

parhein yeh jab aap rakhte hain forgotten kya har concept said. har entry hai bottom-line ke closes concept; collected here ke liye fast lookup.

1. assumption ke broke

payment systems banaya gaya par assumption ke ek human clicks kharidein button. agents break ke mein teen ways: no traditional identity, behavior ke lagta hai anomalous, aur no channel to clear up ek dispute. har break zaroorat hai ek protocol-level fix. Wrapping purana payment rails mein nicer agent UX nahin hua kaam.

2. kyun ek protocol nahin kar sakte solve sab breaks

Ek protocol nahin kar sakta solve sab four breaks, kyun ke breaks happen par mukhtalif layers, har ke saath iska own strong incumbents. four protocols specialize: ACP par commerce, AP2 par authorization, x402 aur MPP par settlement. ke andar ek layer aap ek chunein; across layers aap compose karein kai.

3. OpenAI agents SDK ke taur par universal client

SDK hai universal client ke liye sab four protocols. har protocol becomes ek ya zyada @function_tool functions agent calls. SDK's output_type, context, aur tool_input_guardrail map cleanly to protocol concerns: structured payment results, per-user payment context, aur pre-execution spend-limit check karta hai.

4. layer 1, discovery (kaise agents find kya yeh kar sakta hai kharidein)

layer 1 jawab "kya hai available?" Four options compete karte hain: MCP ke liye internal tool servers, A2A ke liye multi-agent ecosystems, agent directories ke liye third-party services, AI shopping surfaces ke liye consumer products. chunein ek ke matches jahan agent's zaroori tha services live; yeh nahin hain mutually exclusive.

5. layer 2, identity aur authorization (proving agent hai allowed)

layer 2 jawab do sawalat: kiya human authorize karein yeh, aur hai agent jo yeh claims to hona? four protocols compete karte hain: AP2 mandates (audit-rigorous), ACP SPT (Stripe-native), TAP (identity-only), ERC-8004 (multi-agent trust). integrate karein ke zariye RunContextWrapper ke liye per-tool auth aur tool_input_guardrail ke liye spend enforcement. chunein ke zariye trust model; yeh hain interchangeable nahin.

6. layer 3, commerce ( full purchase lifecycle)

layer 3 handles cart, checkout, fulfillment, dispute, aur refund. ACP aur UCP compete karte hain ke liye consumer flows; machine-to-machine API access rakhta hai commerce layer nahin. refund aur dispute mechanics hain hidden complexity ke separates ek real commerce protocol se ek payment-only ek. chunein ke zariye use case: lifecycle zaroori tha (ACP/UCP) ya lifecycle skip hua (direct API).

7. layer 4, settlement (paisa waqai move hota hai)

layer 4 hai jahan paisa move karta hai. Four options compete karte hain: x402 ke liye machine-to-machine stablecoin, MPP ke liye multi-rail sessions, card rails ke liye consumer purchases ke saath chargebacks, bank ya Lightning ke liye high-value ya very-low-fee cases. choice hai zyada tar ke bare mein paisa: sub-dollar to x402, consumer to cards, enterprise to MPP. settlement hai aksar set ke zariye aapka commerce choice; chunein bottom ka stack, not isolated rails.

8. ACP, consumer-shopping protocol

ACP hai production-ready commerce protocol ke liye consumer shopping. SPT scopes agent's spend; merchant stays merchant ka record. aap integrate karein yeh ke zariye Stripe SDK plus ek thin ACP client, wired mein ke taur par four @function_tool functions (browse, checkout, status, refund). Default to user confirmation par carts until agent's cart-accuracy hai measured.

9. AP2, authorization layer

AP2 hai authorization layer ke liye audit-rigorous agent commerce. Teen mandate types (Intent, cart, Payment) form ek non-repudiable chain proving user consented. step.wait_for_event hai natural fit ke liye mandate-signing flows. banayein Intent mandates pehla, pehle shopping begins, not ke taur par ek checkout afterthought.

10. x402, HTTP-native settlement protocol

x402 hai HTTP-native settlement protocol ke liye machine-to-machine micropayments. 402 status code plus ek signed payment header plus ek EIP-3009 signature settle hota hai mein ek se karein seconds ke saath account banane ki zaroorat nahin. wallet's smart-contract spend limits hain safety ke actually protect karein karta hai aap, not per-request cap. check karein header naming against spec version aur facilitator aap integrate karein ke saath; yeh differs across V1 aur V2.

11. MPP, sessions-based settlement protocol

MPP hai Stripe's settlement jawab to x402, banaya gaya ke liye sessions-based metering aur multi-rail dispatch. Do intents, charge (ek-off) aur session (pre-authorized streaming), cover single purchases aur recurring metering. HTTP shape istemaal karta hai standard WWW-Authenticate: Payment, Authorization: Payment, aur Payment-Receipt headers, so yeh feels like familiar HTTP auth. Right-size session caps to expected kaam, not to convenience.

12. minimum viable agent-payment stack

minimum viable stack hai sab se chota composition ke ship karta hai value ke liye use case. Four common ones: consumer shopping (ACP plus cards), API-paying (x402 sirf), enterprise procurement (AP2 plus ACP/UCP plus MPP/cards), multi-agent marketplace (AP2 plus ERC-8004 plus x402). mat banayein universal stacks; ek chunein composition per use case aur ship.

13. jab protocols compose karein across layers vs compete karte hain ke andar ek layer

protocols across layers compose karein (AP2 plus x402, ACP plus x402, MCP plus x402); protocols ke andar ek layer compete karte hain (AP2 vs ACP SPT, ACP vs UCP, x402 vs MPP). test hai "hain yeh par same layer?" agar yes, ek chunein; agar no, yeh likely compose karein.

14. cost aur latency implications ka composition choices

card rails cost 2.9% plus $0.30 har transaction par lekin provide chargeback protection; stablecoin rails cost sub-cent lekin zaroorat crypto-native infrastructure. dollar point jahan card rails stop making sense hai around $5 to $10. latency point jahan ACP checkout becomes bhi slow hai around paanch seconds ke liye user-facing flows. istemaal karein cost aur latency to decide composition, not abstract preference.

15. Spend-limit enforcement par teen architectural levels

Enforce spend limits par teen independent levels: wallet ya payment-method infrastructure, SDK tool guardrails (tool_input_guardrail specifically, since yeh chalta hai pehle har tool aur kar sakta hai block yeh), aur application business logic. har level istemaal karta hai mukhtalif infrastructure, so ek bug mein ek hai caught ke zariye others. istemaal karte hue output_guardrail ke liye paisa kharch karein control hai sab se zyada common mistake; yeh fires par final reply, bhi late to stop ek payment.

16. agent identity hygiene: keys, wallets, aur audit logs

agent identity hai cryptographic; signing key hai sirf cheez separating authorized spend se fraud. Four habits: per-agent wallet separation, key rotation par ek schedule aur par demand, audit logs to durable storage independent ka runtime, aur distributed traces ke saath ek trace ID spanning poora transaction. Signing keys go mein ek key vault, kabhi nahin mein env vars ya source code.

17. dispute aur refund mechanics across four protocols

ACP inherits card-network chargebacks. AP2 provides mandate chain ke taur par legal evidence lekin nahin karta replace karein underlying rail's dispute path. x402 hai non-refundable ke zariye design: fine ke liye micropayments, ghalat jahan refunds matter. MPP inherits Stripe's dispute machinery across rails. dispute model aapka use case zaroorat hai hai aksar sab se strong cheez forcing protocol composition.

18. FastAPI aur Inngest webhook plumbing: closing request aur response loop

agent commerce hai bidirectional: disputes, mandate signatures, refunds, aur seller-side payment requests arrive asynchronously ke zariye webhooks. Teen patterns cover zaroorat: ek Stripe webhook fires ek Inngest event mein ek durable workflow; ek AP2 mandate-signed callback fires ek event ke resumes step.wait_for_event; ek x402 seller-side FastAPI middleware exposes paid APIs. FastAPI handlers stay thin; Inngest functions hain durable. Production systems chalayein sab teen.

19. discipline ka layered composition

four protocols (ACP, AP2, x402, MPP) hain layers, alternatives nahin. aapka job hai to parhein use case, break yeh mein four layers, chunein sahi protocol par har ek, aur justify choice against use case's real constraints. OpenAI agents SDK hai universal client. discipline survives whichever protocols win mein agla 24 months; layers hain stable, even ke taur par protocols par har layer evolve.

---

Design-review template: sawalat to poochein jab reviewing koi bhi agent-commerce architecture

jab aap review ek colleague's design (ya aapka own draft, ke saath ek day's distance), walk yeh sawalat mein order. har maps to ek section ka yeh course; agar jawab nahin karta satisfy sawal, go back to ke section.

architecture sawalat

1. kya use case hai yeh serving? agar "multiple," kya hai primary ek? ek design ke try karta hai to serve sab four canonical istemaal karein cases hai anti-pattern se concept 12; flag yeh.
2. Walk four layers explicitly. discovery? authorization? commerce? settlement? kaun sa protocol par har layer? Get four-protocol composition stated out loud.
3. Justify har layer's choice against use case. kyun yeh protocol par yeh layer? kya hoga change ke saath ek mukhtalif ek? concept 13's across-vs-within test applies here.
4. hai there protocol overlap par koi bhi layer? Do protocols competing par layer 4? Do par layer 2? agar yes, ke hai complexity ke zaroorat hai ek use case to justify yeh.

Economic sawalat

5. Kya hai transaction value distribution? Sub-dollar? $10 to $100? $1,000-plus? concept 14's economic threshold chahiye drive settlement choice.
6. Kya hai latency budget? Sub-second? 5 to 30 seconds? latency budget chahiye constrain settlement aur mandate choices.
7. Kya hai cost har transaction par expected volume? add karein protocol fees plus processor fees plus per-transaction infrastructure cost. istemaal karein yeh to check karein composition hai economically viable.

Operational sawalat

8. Spend-limit enforcement par sab teen levels? wallet/payment-method, SDK, application business logic. concept 15: skip karein koi bhi aur aap hain exposed.
9. identity hygiene? Per-agent wallet separation, key rotation, audit logs to durable storage, distributed traces ke saath ek trace ID har transaction par. concept 16's four habits.
10. dispute aur refund mechanics? karta hai composition handle disputes aapka use case hoga actually milta hai? concept 17: yeh hai aksar sab se strong constraint.
11. Operational envelope? jahan karta hai Inngest (ya equivalent durable execution) handle long-running flows, dobara try karta hai, aur idempotency? Covered mein Production Worker crash course.
12. human-in--loop gates? jahan mein flow karta hai user ya operator confirm? Default to ek confirmation gate ke liye pehla 30 days ka production.

Webhook aur async-callback sawalat (concept 18)

13. Stripe webhook handler exists aur hai thin? verify karta hai signature, fires ek Inngest event, ACKs mein ke neeche paanch seconds. Business logic rehta hai mein Inngest function, not handler.
14. AP2 mandate-signing callback exists aur verify karta hai user signatures? ke baghair yeh, agent's step.wait_for_event kabhi nahin resumes. ke baghair signature verification, koi bhi kar sakta hai forge mandate-signed events.
15. agar exposing paid APIs: x402 seller-side middleware configured per route? Multi-agent marketplaces chalayein both buyer-side aur seller-side code; seller side zaroorat hai middleware.
16. Inngest idempotency keys par har webhook-triggered function? Stripe dobara try karta hai ke saath same event.id; ke baghair idempotency aap charge ya refund twice.
17. Contract layer: Pydantic models par har boundary? tool wapas deta hai, protocol payloads, FastAPI request aur response bodies, Inngest event payloads, sab typed. Decimal ke liye paisa, kabhi nahin float.

Failure-mode sawalat

18. Kya hai sab se zyada likely failure mode production mein? har canonical decision rakhta tha ek: cart mismatch (decision 1), runaway paisa kharch karein (decision 2), Intent mandate scope mismatch (decision 3), gamed reputation (decision 4). Kya hai aapka?
19. Kya hai mitigation? har failure mode mein part 5 rakhta tha ek explicit mitigation. karta hai design include yeh, ya hai yeh relying par "protocol hoga handle yeh"?

Track-readiness sawalat (ke liye production deployment)

20. kya learning track hai team operating se? reader, beginner, intermediate, advanced. hona honest. Production deployment zaroorat hai Advanced-track depth, not Reader-track familiarity.
21. Kya hai rollback plan agar agent misbehaves? wallet kill switch? SPT revocation? Disable agent par SDK level? rakhte hain yeh defined pehle launch, not baad incident.

---

References

Primary sources ke liye four protocols. Prefer yeh ke upar secondary commentary; specs evolve faster se write-ups ke bare mein inhein.

ACP (Agentic commerce protocol)

• Specification repository: github.com/agentic-commerce-protocol/agentic-commerce-protocol (Apache 2.0)
• Developer site: agenticcommerce.dev
• Co-maintainers: OpenAI aur Stripe
• Stripe integration docs: stripe.com/docs/agentic-commerce
• latest spec version cited: 2026-04-17

AP2 (agent Payments protocol)

• Specification repository: github.com/google-agentic-commerce/AP2 (Apache 2.0)
• Documentation site: ap2-protocol.org
• Coalition members: Google plus 60-plus partners (Salesforce, ServiceNow, Adobe, Shopee, Etsy, Adyen, American Express, JCB, UnionPay International, PayPal, Mastercard, Coinbase, others)
• a2a-x402 extension repository: github.com/google-a2a/a2a-x402
• latest version cited: v0.2.0 (April 2026)

x402

• Specification repository: github.com/coinbase/x402 (Apache 2.0)
• Documentation site: x402.gitbook.io (bhi x402.org)
• banaya gaya ke zariye Coinbase aur ab stewarded ke neeche Linux Foundation's x402 Foundation (April 2026), ke saath Cloudflare, Stripe, AWS, Google, aur others.
• Cloudflare OpenAI agents SDK integration: developers.cloudflare.com/agents/x402
• Adoption directory: agent.market
• x402 Foundation members include: Adyen, AWS, American Express, Base, Circle, Cloudflare, Coinbase, Google, Mastercard, Microsoft, Polygon Labs, Shopify, Solana Foundation, Stripe, Visa

MPP (Machine Payments protocol)

• Specification site: mpp.dev
• Co-developers: Stripe aur Tempo (Stripe's L1 blockchain, incubated ke saath Paradigm)
• Stripe announcement: stripe.com/blog/machine-payments-protocol
• Launch date: March 18, 2026 (mainnet)
• Partners par launch: Stripe, Visa, Lightspark, Anthropic, OpenAI, Shopify, aur 100-plus services

Adjacent protocols

• A2A (Agent2Agent, Google): github.com/google-a2a/A2A, protocol AP2 extends
• MCP (model Context protocol, Anthropic): modelcontextprotocol.io, tool aur context layer agents discover services ke zariye
• UCP (Universal commerce protocol, Google): announced ke taur par ACP's peer ke liye Google shopping surfaces
• TAP (Trusted agent protocol, Visa aur Cloudflare): identity verification protocol launched October 14, 2025
• ERC-8004: on-chain trust standard ke liye multi-agent transactions

OpenAI agents SDK

• Python SDK: pip install openai-agents (latest release ho sakta hai 19, 2026)
• Documentation: openai.github.io/openai-agents-python
• JavaScript/TypeScript SDK: github.com/openai/openai-agents-js

Related agent Factory crash courses

• banayein AI agents crash course: OpenAI agents SDK fundamentals (Agent, Runner.run(), @function_tool)
• Production Worker crash course: Inngest ke taur par operational envelope ke liye durable agent workflows
• Eval-Driven Development crash course: testing aur evaluating agents
• Choosing Agentic Architectures crash course: kaun sa agentic pattern fit hota hai kaun sa use case
• deploying-agents crash course (cloud deployment): cloud harness (Azure Container Apps plus Neon plus Cloudflare). mein progress; link once yeh ship karta hai.

Operational aur contract-layer tools (istemaal hua heavily mein concepts 16 aur 18)

• Inngest: inngest.com, durable execution platform ke chalta hai agent workflows hai course mein
• FastAPI: fastapi.tiangolo.com, async HTTP layer jahan webhook endpoints aur seller-side x402 middleware live
• Pydantic: pydantic.dev, type contract par har boundary (tool wapas deta hai, protocol payloads, FastAPI bodies, Inngest events)
• OpenTelemetry: opentelemetry.io, distributed tracing ke saath auto-instrumentation ke liye httpx, openai-agents, FastAPI, aur Inngest; ek trace ID spans poora transaction
• httpx: python-httpx.org, async HTTP client underneath x402-client, ACP client, aur AP2 a2a-x402 extension
• Azure key vault: jahan signing keys live production mein, rotated per concept 16's discipline
• Stripe webhooks documentation: stripe.com/docs/webhooks, signature verification, event types, aur dobara try karein semantics

---

aap ab rakhte hain poora framework: four layers, four protocols, rules ke liye composing inhein, five worked decisions, production concerns ke decide whether system survives, aur ek ek-page reference to rakhein. protocols hoga rakhein moving. four-layer discipline nahin hoga. banayein se layers, aur aap hoga phir bhi hona sahi jab protocol names change.