Payment-Enabled Agents：ACP、AP2、x402 与 MPP 的生产组合
这是一门关于四个协议的速成课。它们让 OpenAI Agents SDK 系统能够在商家、API、其他 agents 和开放经济中花钱。适合已经构建过 agents、现在需要让 agents 安全付款的工程师。
19 个概念。5 个 Decision。3 张图。四条学习路径。 Reader 路径大约 2–3 小时，只读四层 stack、协议深讲和组合规则，不跑代码。Beginner、Intermediate 和 Advanced 会逐步加入 hands-on：把 agents 接到协议、让组合 durable 运行、管理 identity、spend 和 dispute。完整团队习惯化需要 4–5 天。进入 Part 5 的 decision lab 前，先选好自己的路径。
本课建立在一个核心判断上：四个协议不是竞争对手，而是不同层。 许多文章问“ACP 还是 x402？”这其实问错了。2026 年真正上线的系统通常会把几个协议组合起来，因为每个协议解决 agent-commerce 问题的不同层。consumer shopping agent 在 commerce 层用 ACP，在 settlement 层用 card rails；API-paying agent 用 x402，因为 machine-to-machine micropayments 会让 commerce 和 settlement 合成一个流程；enterprise procurement agent 用 AP2 mandates 证明人类授权，再用 Stripe MPP 或其他 rail settlement。
本课会提到几个相邻课程：Build AI Agents、Production Worker、Eval-Driven Development 和 Choosing Agentic Architectures。没学过也能读；四层协议、SDK code 和 decision discipline 都是自洽的。唯一建议：Part 3 代码假设你能读懂 Agent、Runner.run() 和 @function_tool。如果陌生，先快速扫 Build Agents 课程。
不同技术栈下，每个协议映射到什么
即使你不用 OpenAI Agents SDK、Stripe、Coinbase 或 Cloudflare，这套分层也成立。协议 specs 与 stack 无关，变的是 primitive 名称。
| Protocol | 2026 年主要 reference SDK | 常见替代 | License / governance |
|---|---|---|---|
| ACP | Stripe SDK + OpenAI Agents SDK；PayPal ACP server tools；Worldpay credentials | Adyen ACP、Shopify checkout API | Apache 2.0，OpenAI + Stripe |
| AP2 | Google ADK；Python、TypeScript、Kotlin、Go reference implementations | LangGraph + custom mandate signing、AutoGen + a2a-x402 | Apache 2.0，Google + 60+ partners |
| x402 | x402-client、@x402/client、Coinbase Developer Platform、Cloudflare withX402Client、AgentPay MCP | Direct EIP-3009、Lobster.cash、Crossmint agent wallets | Apache 2.0，Coinbase 发起，Linux Foundation x402 Foundation 治理 |
| MPP | Stripe PaymentIntents + MPP extensions；Tempo blockchain SDK | Lightning Network、Tempo native SDKs | Apache 2.0，Stripe + Tempo |
| A2A | Google ADK | Custom A2A implementations | Apache 2.0，Google + Linux Foundation |
| MCP | Anthropic MCP servers/clients；openai-agents MCP support | LangChain MCP | MIT，Anthropic |
读这张表的方法是：当课程说“把 agent 的 @function_tool 接到 Stripe ACP endpoint”时，如果你的 stack 是 Adyen + LangGraph，就理解为“把等价的 LangGraph tool 接到 Adyen ACP endpoint”。论证相同，名称变化。
Glossary
本课术语，第一次阅读建议展开
四个 headline protocols
- ACP（Agentic Commerce Protocol）。 OpenAI 和 Stripe 构建的 consumer-shopping protocol，管理 agent 如何代表真人在真实商家完成 checkout。ChatGPT Instant Checkout 用的就是这个方向。主要位于 commerce layer。
- AP2（Agent Payments Protocol）。 Google 与 60+ partners 构建的 authorization protocol。它产生 signed mandates，证明人类允许 agent 在某个范围内花钱。AP2 自身不移动资金；它证明支出被授权。
- x402。 Coinbase 发起、Linux Foundation 治理的 HTTP-native settlement protocol。它复活 HTTP
402 Payment Required：server 返回 payment requirement，agent 附带支付证明重试请求。 - MPP（Machine Payments Protocol）。 Stripe 和 Tempo 的 session-based settlement protocol。agent 先打开有 spending cap 的 session，然后在 cap 内做多次小额 metered payments。
四层 stack
- Discovery layer。 agent 发现可以买什么：MCP servers、A2A、agent directories、merchant APIs。
- Identity and Authorization layer。 证明两件事：人类授权这笔支出，agent 身份可信。AP2 mandates、ACP SPT、wallet policy、TAP、ERC-8004 都在附近。
- Commerce layer。 完整购买 lifecycle：cart、checkout、fulfillment、dispute、refund、customer support。ACP 和 UCP 在这里竞争。
- Settlement layer。 钱真正移动的层：cards、bank rails、stablecoins、Lightning、x402、MPP。
授权 primitives
- Mandate。 AP2 中人类签署的数字授权，描述 agent 可以做什么。
- Intent Mandate。 任务开始前签署，例如“买不超过 $120 的鞋”。
- Cart Mandate。 agent 建好具体 cart 后，人类确认“就是这些商品、这个价格”。
- Payment Mandate。 付款时的具体授权，绑定 exact amount、merchant 和 rail。
- SPT（Shared Payment Token）。 ACP 的 scoped token，通常由 payment processor 发行，只能在特定 merchant、amount cap 和短时间窗内使用。
- Non-repudiable。 签署者事后不能否认的记录。AP2 mandate chain 的价值就在这里。
settlement 与 crypto primitives
- Stablecoin。 锚定稳定价值的 crypto，常用于 agent micropayments。
- USDC。 x402 常用的美元锚定 stablecoin。
- HTTP 402 Payment Required。 1997 年保留但长期未用的 HTTP status code，x402 重新使用它。
- EIP-3009。 x402 基于的 Ethereum 标准，允许 buyer 离线签名付款授权，由别人提交 on-chain。
- Facilitator。 x402 中可选第三方，替 merchant 验签并提交链上支付。
- Smart-contract wallet。 支出规则由链上代码 enforce 的 wallet，例如 per-transaction cap、daily cap、recipient cap。
- MPP session。 agent 预授权 cap 和 duration，然后在 session 内做多次小额支付。
commerce 与资金概念
- Settlement。 钱真正从 buyer 到 seller 的时刻。
- Merchant of record（MoR）。 对交易承担税务、争议和客户支持责任的商家。
- Chargeback。 card payment 被银行逆转。
- Dispute。 buyer 正式质疑收费。dispute model 往往决定协议选择。
- Idempotency。 同一操作做两次效果等同于做一次；支付 webhook 和退款路径必须具备。
agent stack 与相邻协议
- Agent commerce。 autonomous AI agent 作为 buyer、seller 或二者之一参与交易。
- OpenAI Agents SDK。 本课中的 universal client：各协议暴露为
@function_tool，由Agent和Runner.run()驱动。 - MCP。 常作为 discovery layer。
- A2A。 agents 之间通信和发现。AP2 构建在 A2A 之上。
- UCP。 Google 生态下与 ACP 类似的 commerce-layer protocol。
- TAP。 Visa + Cloudflare 的 agent identity protocol，证明“谁在请求”，但不证明“允许花多少钱”。
- ERC-8004。 agent identity 和 reputation 的 on-chain registry。
tool_input_guardrail。 OpenAI Agents SDK 中付款前拦截 tool call 的关键机制。与output_guardrail不同，它在付款前执行。
Prerequisites
你会更顺畅地学习本课，如果已经具备：
- Build AI Agents 课程或等价 SDK 经验。 需要能读懂
Agent、Runner.run()、@function_tool。 - Choosing Agentic Architectures 课程或等价架构判断。 Part 5 的 composition decision 依赖这种模式选择纪律。
- 基本 HTTP。 status codes、request/response、headers。x402 在 HTTP 层工作。
- 基本支付词汇。 merchant、settlement、dispute、chargeback、merchant of record。
不需要 blockchain 或 smart-contract 经验。本课会解释足够的 x402 和 EIP-3009；不需要写 Solidity。
四条学习路径
| 路径 | 时间 | 你会做什么 | 最适合谁 |
|---|---|---|---|
| Reader | 2–3 小时 | 阅读所有 Concepts 和 Decisions，不运行代码 | 判断是否投入更深的工程师、PM、architect |
| Beginner | 约 1 天 | Reader + 跑 x402 client examples + 一个 ACP test transaction | 第一次接触 agent commerce 的工程师 |
| Intermediate | 2–3 天 | Beginner + 构建一个 agent：部分交易用 ACP，部分用 x402，并接 AP2 Intent Mandate checks | 正在交付真实系统的工程师 |
| Advanced | 4–5 天 | Intermediate + durable runtime、spend limits、HITL gates、trace/cost/dispute metrics、完整 refund cycle | 对生产资金系统负责的团队 |
自检问题：“我的 use case 中，最小可交付的 protocol composition 是什么？” 如果 Part 4 后还答不上，重读 Part 4。能答上后，路径选择只是从“最小组合”走多远到“生产级组合”的问题。
四层 stack
每个 agent-commerce use case 都会碰到四层，但不同 use case 在每层选不同协议。consumer shopping：MCP discovery、ACP SPT authorization、ACP commerce、card rails settlement。API-paying agent：agent directory discovery、EIP-3009 authorization、跳过 commerce、x402 settlement。enterprise procurement：A2A directory、AP2 mandate、ACP/UCP commerce、Stripe MPP settlement。规则很简单：每层选一个协议，并让 use case 证明这个选择。
第 1 部分：为什么 agent commerce 需要新协议
先记住四个名字：ACP 是 consumer shopping，AP2 是 authorization mandates，x402 是 HTTP 上的 per-request stablecoin payment，MPP 是 session-based multi-rail payment。MCP 和 A2A 帮 agents 发现和通信，不是付款协议。Part 2 会逐层展开。
概念 1：坏掉的假设
传统支付系统默认：人类在键盘前点击 buy。agent 同时打破了三个假设。
第一，agents 没有 email address。 消费支付流程要 account，account 要 email、phone、name。给 agent 伪造这些字段会在 fraud detection 或 KYC 面前崩掉。
第二，agents 每秒可以行动上千次。 对人类来说异常的速率、地点和模式，对 agent 可能是正常行为。传统 fraud system 会把正常 agent 行为看成攻击。
第三，agents 不会接电话。 dispute resolution 默认能联系 buyer：“你授权了吗？”agent 授权的 charge 不会接电话，人类 owner 可能都不知道这笔 charge 已发生。
| Break | 旧人类 rails 做不到什么 | agent rails 需要给什么 |
|---|---|---|
| 没有 email/account | 逼 agent 创建 fake accounts | cryptographic identity 或 scoped tokens |
| 高频行为 | 把正常 agent 流量当攻击阻断 | HTTP-native per-request payment 或 pre-authorized sessions |
| 无法电话确认 | 发送 agent 读不了的 dispute email | mandate-based authorization + audit trail |
概念 2：为什么一个协议不可能赢
一个统一协议必须同时定义 discovery、authorization、commerce 和 settlement，还要让 search、identity、payments、banks、card networks、crypto rails 全部采用。现实上做不到。因此每个协议在 sponsor 最有 leverage 的层上切入。
| Protocol | sponsor 的 leverage | 它占据的层 |
|---|---|---|
| ACP | OpenAI 拥有 shopping channel；Stripe 拥有 merchant integration | commerce |
| AP2 | Google wallet、Android、60+ partner coalition | authorization |
| x402 | Coinbase stablecoin infra；Cloudflare HTTP edge | settlement |
| MPP | Stripe merchant relationships；Tempo chain | settlement |
本课的核心纪律是：同一层内选择一个协议，跨层组合多个协议。 x402 和 MPP 真正竞争的是 settlement；ACP 和 UCP 竞争的是 commerce；AP2、TAP、ERC-8004 竞争或互补的是 identity/authorization。
概念 3：OpenAI Agents SDK 是 universal client
实践中，agent framework 成为 universal client。每个协议暴露 SDK 或 HTTP endpoint，再包装成一个或多个 @function_tool。OpenAI Agents SDK、LangGraph、AutoGen、CrewAI 都可以用这个形状。本课用 OpenAI Agents SDK：
# Each protocol becomes one or more @function_tool decorated functions
from agents import Agent, Runner, function_tool
@function_tool
def discover_products(query: str) -> list[dict]:
return []
@function_tool
def checkout_with_acp(cart_id: str) -> dict:
return {"status": "pending_authorization"}
# Compose the tools into an agent
agent = Agent(
name="Shopping agent",
instructions="Respect mandates and spend limits before checkout.",
tools=[discover_products, checkout_with_acp],
)
# Run the agent. The SDK handles tool selection, the loop, and retries.
Runner.run_sync(agent, "Buy the cheapest approved replacement filter.")
SDK 不替代 ACP、AP2、x402 或 MPP。它把这些协议变成 tools、guardrails、run context 和 trace，放进同一个 agent loop。
第 2 部分：四层深入
概念 4：Layer 1，Discovery（agent 如何找到可以买什么）
Discovery 回答：有什么、价格多少、条款是什么、通过哪个 tool 访问。MCP servers、A2A directories、merchant APIs、agent directories 都属于这里。
Discovery 的输出不应该直接付款。它输出候选商品、API、服务、价格、capabilities 和 terms；authorization layer 再决定是否允许购买。
# Wire an MCP discovery server: all its tools become available
# Wire a non-MCP directory as a regular tool
设计时问三件事：agent 能否看到完整价格？terms 是否机器可读？发现结果是否带上 merchant/service identity，供后续 authorization 和 audit 使用？
概念 5：Layer 2，Identity and Authorization（证明 agent 被允许）
Authorization 回答：谁授权、金额多少、merchant 是谁、时间窗多长、类别是什么、如何撤销。AP2 mandates、ACP SPT、wallet policies 和 spend caps 都在这里。
在 SDK 中，最重要的 enforcement point 是 tool input guardrail：它在付款 tool 执行前运行。
# 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.
# Pattern 2: the payment tool itself, guarded at the function-tool level
不要把 authorization 当成“agent 在最终回答里承诺不会超额”。输出 guardrail 太晚了。付款已经发生后再检查，不能防止资金移动。
概念 6：Layer 3，Commerce（完整购买 lifecycle）
Commerce 是 cart、checkout、fulfillment、refund、dispute 和 customer support。ACP 适合 consumer shopping，因为它定义的不只是付款，而是购物 lifecycle：商品、cart、merchant of record、配送、退款、争议。
如果你的 use case 是“买鞋”“订滤芯”“补货办公用品”，通常需要 commerce layer。因为这些交易不只是 money movement，还有商品、库存、税、配送、售后和 dispute。
如果 use case 是“agent 调用一个付费 API 端点”，通常没有 commerce layer。x402 直接在 HTTP request/response 中完成 payment requirement 和 settlement。
概念 7：Layer 4，Settlement（钱真正移动）
Settlement 是资金移动：card rails、bank rails、stablecoins、Lightning、x402、MPP。它绝不能是唯一授权层。一个 wallet 能转钱，不代表这个 agent 被允许为这个用户、这个 merchant、这个类别、这个金额转钱。
Settlement selection 受经济现实驱动：微额高频 API calls 要低延迟、低手续费；高价值 consumer purchase 要 chargeback、refund 和 dispute；enterprise procurement 要 invoice、approval、budget 和 audit。
第 3 部分：四个协议深入，以及 OpenAI Agents SDK integration
生产代码要把三个模型层分清：tool result models、FastAPI handler models、Inngest workflow result models。混用会让 webhook、payment tool 和 durable workflow 的边界变模糊。
# --- Tool-result models (returned by @function_tool functions) ---
# --- FastAPI handler models (request/response bodies for webhooks/callbacks) ---
# --- Inngest workflow result models (return types of @inngest_client functions) ---
概念 8：ACP（Agentic Commerce Protocol），consumer-shopping protocol
ACP 适合完整购物场景：发现商品、构建 cart、checkout、确认、fulfillment、dispute、refund。它不是通用 machine-payment protocol，而是 commerce lifecycle protocol。
典型 ACP flow 是：
- agent 通过 discovery 找商品；
- merchant 或 payment processor 生成 scoped token / checkout primitive；
- agent 在 spend cap 和 mandate 范围内发起 checkout；
- commerce layer 管理履约、receipt、refund 和 dispute；
- settlement rail 最终移动资金。
付款前必须有 input guardrail：
# Tool input guardrail: refuse the checkout if the user can't authorize the spend
def guard_checkout(ctx, tool_input):
if tool_input["amount_cents"] > ctx.context.spend_cap_cents:
raise ValueError("Spend cap exceeded")
ACP 的强项是 consumer trust：商家、cart、配送、退货和 dispute 都有位置。弱项是它不是最轻的 API micropayment rail。
概念 9：AP2（Agent Payments Protocol），authorization layer
AP2 表达 intent 和 mandate。它告诉系统：用户授权 agent 在什么范围内花钱。没有 mandate 的 cart 不应该 checkout。
# Guardrail: refuse any cart that has no preceding Intent Mandate
def require_mandate(ctx, cart):
if not cart.get("mandate_id"):
raise ValueError("Missing Intent Mandate")
AP2 适合回答争议中的核心问题：“这笔支出有没有人类授权？”Intent Mandate 记录任务范围，Cart Mandate 记录具体 cart，Payment Mandate 记录具体付款。链条越完整，审计和争议越清楚。
AP2 不移动资金。它通常与 ACP、MPP、cards、bank rails 或 x402 组合。
概念 10：x402，HTTP-native settlement protocol
x402 适合 API-paying agent。server 先返回 402 Payment Required 和 payment requirements；client 按要求生成支付证明，然后重试 request。agent 不需要走 cart、checkout、fulfillment，因为商品就是 HTTP resource。
# Pattern 1: wrap an MCP server's tools with x402 payment ability
# Pattern 2: direct x402 calls as @function_tool
# Guardrail: refuse any x402 call that would exceed the session cap
x402 的优点是轻、快、贴近 HTTP，适合 machine-to-machine micropayments。限制是 dispute/refund/chargeback 不是它的核心；如果用户需要完整消费保护，通常需要 commerce layer 或更强的 settlement/merchant model。
概念 11：MPP（Machine Payments Protocol），session-based settlement
MPP 适合持续 session：一次授权，很多小额调用，在 session cap 内结算。它把“每次都签名付款”的摩擦变成“先开一个 tab，再按量扣费”。
适用场景包括：长期 research agent 调用付费数据源、enterprise agent 在工作流中多次访问 metered services、内部 agents 之间按 session 结算。MPP 的核心不是 cart，而是 session cap、duration、metering 和 closeout。
第 4 部分：Composition rules，什么时候组合哪些协议
概念 12：Minimum viable agent-payment stack
最小 stack 不是“一个付款 API”。至少需要：
- discovery：agent 知道买什么；
- authorization：系统知道 agent 被允许买；
- settlement：钱真正移动；
- audit：以后能解释为什么付款、谁授权、多少钱、哪个 merchant、哪个 run。
commerce layer 是否需要，取决于有没有完整购物 lifecycle。API 调用可能不需要；实物商品、订阅、企业采购通常需要。
概念 13：协议跨层组合，同层竞争
跨层组合很正常：AP2 + ACP + card rails，MCP + x402，AP2 + MPP。同层协议通常竞争：一个 settlement flow 不会同时由 x402 和 MPP 主导，除非你明确设计 bridge。
这条规则能避免架构混乱。不要问“ACP 还是 x402？”先问：“这是 commerce 层问题还是 settlement 层问题？”若答案不同，它们可能组合；若答案相同，它们才竞争。
概念 14：成本和延迟如何迫使选择
经济阈值决定 protocol choice。小额高频 API calls 对每次 settlement 的手续费和 latency 极其敏感，因此 x402 或 MPP 更合适。低频高额购物对 dispute、refund、merchant of record 和 customer support 更敏感，因此 ACP / UCP + card/bank rail 更合适。
一个简单判断：如果失败后用户会问“货没到怎么办？”就需要 commerce layer。如果失败后用户只会问“API call 为什么多收了 $0.02？”settlement + audit 可能足够。
第 5 部分：Decision lab，五个 worked examples
Decision 1：Consumer shopping agent（ChatGPT Instant Checkout pattern）
四层都在场：discovery 找商品，AP2 或 scoped token 授权，ACP 处理 cart/checkout，card rails 或 merchant settlement 移动资金。关键风险是超额购买、错误 merchant、错误 cart、refund/dispute path 缺失。guardrail 必须在 checkout tool 之前执行。
Decision 2：API-paying research agent（x402-only pattern）
agent 发现付费 API，确认 session cap，遇到 402 Payment Required 后付款并重试。没有 cart、没有 fulfillment、没有 merchant of record，因此 commerce layer 可省略。关键风险是小额调用累计超支，所以 cap、per-request audit 和 usage reporting 必须强。
Decision 3：Enterprise procurement agent（AP2 + composed stack）
企业采购需要审批、预算、供应商、发票和 audit。AP2 表达 authorization，ACP/UCP 或 direct B2B API 处理 commerce，MPP/card/bank rail settlement。这里最重要的是 human approval、budget owner、vendor identity、invoice reconciliation 和 procurement policy。
Decision 4：Multi-agent marketplace（AP2 + x402 + ERC-8004 pattern）
多个 agents 之间交易时，identity、reputation、authorization 和 settlement 都要明确。AP2 处理 mandate，x402 处理 micropayments，ERC-8004 或相邻协议处理 agent identity / reputation。这里的风险不只是支付失败，而是“你到底在和谁交易”。
Decision 5：Non-Stripe、non-OpenAI stack（证明 framework 可迁移）
这套分层不依赖 Stripe 或 OpenAI。Google ADK、Coinbase wallet、direct merchant APIs 和 x402 也能按相同方式组合。
# Shared result models come from the Pydantic sidebar in Part 3.
# --- Illustrative stand-ins for the payment rails (real APIs differ) ---
# -----------------------------------------------------------------------
# Layer 2 (Authorization): a Coinbase smart-contract wallet gives the agent its
# on-chain identity and its spend caps.
# Layer 2 (Authorization): an AP2 Intent Mandate, signed by the user at session start.
# Layer 1 (Discovery) + Layer 4 (Settlement) as one tool.
# ADK's @function_tool is the analog of the SDK's @function_tool.
# The agent itself: a Google ADK Agent, the direct analog of the SDK's Agent.
# 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.
这个 Decision 的意义是：framework travels。只要四层清楚，SDK 和 vendor 可以换。
第 6 部分：Production concerns，系统上线后真正会杀你的东西
概念 15：三层 spend-limit enforcement
spend limits 至少要有三层：
- wallet/payment-method caps。 agent 自己改不了，由 wallet、processor 或 chain enforce。
- SDK tool input guardrail。 付款 tool 执行前拦截超额、无 mandate、wrong merchant、wrong category。
- application business rules。 tenant budget、policy、approval threshold、risk tier。
只靠 agent-level output guardrail 是错误的，因为它在付款之后才运行。
# Set ONCE when the wallet is deployed. The agent cannot change this.
# Set once via the Stripe Dashboard or API. The caps live in Stripe's infrastructure.
# Tool INPUT guardrail: pre-payment check. Runs BEFORE the tool executes.
# Tool OUTPUT guardrail: post-payment check. Runs AFTER the tool executes.
# Attach BOTH guardrails to every payment-authorizing tool.
input guardrail 阻止付款发生；output guardrail 只能检查 receipt 或最终回答。两者不是替代关系。
概念 16：Agent identity hygiene：keys、wallets 和 audit logs
不要让所有 agents 共用一个 wallet 或 key。按 agent class、tenant、risk tier 分离身份。一个 low-risk summarizer 不应该能使用 procurement agent 的 wallet；一个 tenant 的 agent 不应该使用另一个 tenant 的 key。
# Wrong: one wallet shared across agents
# Right: a separate wallet per agent class
# Read the current key version from the vault. The version changes when the key rotates.
# Old transactions, signed with the previous version, stay valid until they expire.
# New transactions use the current version.
# Every payment-authorizing action logs to durable storage BEFORE the action completes.
audit log 至少记录：run ID、agent ID、tenant ID、mandate ID、merchant/service ID、amount、currency、rail、key version、tool input、guardrail decision、settlement result、webhook event IDs。没有这些字段，事故后无法解释。
概念 17：四个协议中的 dispute 和 refund mechanics
支付系统不只有 happy path。必须设计 duplicate payment、partial refund、merchant failure、API overcharge、chargeback、mandate revoked、wallet key leaked、webhook replay、settlement delayed。
Commerce layer 与 settlement layer 的责任要分清。ACP/UCP 负责购买 lifecycle 和 merchant-facing dispute；x402/MPP 负责资金移动和 proof；AP2 证明授权；application audit 把它们连成可解释链条。
若产品需要退款、争议、发票、履约证明和 customer support，只靠 settlement 不够。你需要 commerce layer。
概念 18：FastAPI 和 Inngest webhook plumbing：关闭 request/response loop
webhook 是支付系统的事实来源之一。FastAPI 接收 webhook、验证签名、写入 event；Inngest 或 durable workflow 处理重试、等待、争议和回调。不要在 webhook handler 中直接完成所有业务逻辑。
# The Inngest function that handles the dispute: fully durable and retryable.
# The Inngest function that was waiting. if_exp correlates the wait to this mandate.
# Illustrative seller-side imports (see note above).
# Configure the middleware once at app startup.
# Your business logic. The middleware enforces payment before this runs.
生产 checklist：
- 验证 webhook signature；
- 用 provider event ID 做 idempotency；
- 先写 durable event / audit，再返回 2xx；
- workflow 用 correlation key 匹配 waiting run；
- 对 duplicate webhook 做 no-op；
- dispute/refund path 与 original payment path 共享 audit context。
第 7 部分：Closing，本课真正教的是什么
概念 19：Layered composition 的纪律
本课真正教的不是四个缩写，而是分层组合纪律。agent 能付款后，错误不再只是“回答错了”，而是“花错钱了”。因此，discovery、authorization、commerce、settlement、guardrails、audit、webhooks 和 dispute 都必须有明确边界。
最危险的 architecture 是“agent 有一个万能 pay() tool”。它既不知道 discover 的内容是否可信，也不知道人类授权范围，也不知道 merchant lifecycle，也不知道 settlement rail 的失败语义。正确 architecture 把 pay() 拆成层，每层都有可审计的 authority。
Cheat sheet：一页 framework
四层 stack（记住）
Discovery → Identity and Authorization → Commerce → Settlement。
每层协议（2026 年首选）
Discovery：MCP、A2A、directories。Authorization：AP2、SPT、wallet policy、TAP、ERC-8004。Commerce：ACP、UCP、direct merchant APIs。Settlement：x402、MPP、cards、bank rails、stablecoins、Lightning。
四种 canonical compositions
consumer shopping：四层全用。API-paying：discovery + authorization + settlement。enterprise procurement：authorization + commerce + settlement + audit。multi-agent marketplace：identity + reputation + authorization + settlement。
三层 spend-limit enforcement（必须）
wallet/payment rail cap、SDK input guardrail、application rule。三层都要有。任何一层缺失都会在事故中暴露。
经济阈值（记住）
高频小额偏向低摩擦 settlement；低频高额偏向强授权、commerce lifecycle 和争议机制。协议选择由经济现实驱动，不由 acronym 偏好驱动。
Dispute model（常常是最强约束）
如果用户需要 refund、dispute、invoice、fulfillment proof 和 customer support，你需要 commerce layer。settlement alone 不够。
生产上线前 checklist
mandate、spend caps、wallet isolation、key rotation、audit log、webhook verification、idempotency、refund path、dispute path、monitoring、eval、incident runbook、legal/finance review。
Quick reference：压缩决策树
先问 agent 买的是商品还是 API？需要 cart 和 fulfillment 吗？用户授权是一次性还是 session？金额高不高？频率高不高？是否需要 dispute/refund？是否有 merchant of record？答案决定四层组合。
如果是 consumer product purchase：优先 ACP/UCP + AP2/SPT + card/bank rail。如果是 API micropayment：优先 x402 或 MPP。如果是 enterprise procurement：AP2 mandate + commerce/procurement API + invoice/rail + durable audit。如果是 agent marketplace：identity/reputation layer 必须先解决。
10 分钟复习：19 个概念一行版
- agent commerce 打破人类点击付款的假设。
- 单一协议无法覆盖 discovery、authorization、commerce 和 settlement。
- OpenAI Agents SDK 把各协议包装成 tools、guardrails 和 context。
- Discovery 告诉 agent 能买什么。
- Authorization 证明 agent 被允许花钱。
- Commerce 管完整购买 lifecycle。
- Settlement 让钱真正移动。
- ACP 是 consumer-shopping commerce protocol。
- AP2 是 mandate-based authorization layer。
- x402 是 HTTP-native settlement。
- MPP 是 session-based settlement。
- 最小 stack 至少需要 discovery、authorization、settlement 和 audit。
- 协议跨层组合，同层竞争。
- 成本和 latency 决定 settlement 选择。
- spend limits 要在 payment rail、SDK input guardrail 和 application rules 三层 enforce。
- agent identity 要隔离 keys、wallets 和 audit logs。
- dispute/refund path 必须设计。
- webhook plumbing 要验证、幂等、durable、可 correlation。
- 核心纪律是 layered composition。
Design-review template：审查任何 agent-commerce architecture 时要问什么
Architecture questions
四层分别用什么？每层 authority 在哪里？agent 能否绕过 authorization？settlement rail 是否知道 mandate？commerce layer 是否知道 refund/dispute path？
Economic questions
单笔金额多少？调用频率多少？每次 settlement fee 和 latency 如何？模型成本和支付手续费哪个更大？失败重试会放大成本吗？
Operational questions
谁查看 audit？key 如何轮换？mandate 如何撤销？重复 webhook 如何 no-op？tenant budget 如何重置？incident owner 是谁？
Webhook and async-callback questions
webhook 是否验证签名？是否幂等？是否先写 durable event？waiting workflow 如何用 correlation key 匹配回调？timeout 怎么处理？
Failure-mode questions
重复付款、超额付款、merchant failure、API overcharge、用户撤销授权、wallet key 泄露、provider outage、chargeback、partial refund、stale price 时怎么办？
Track-readiness questions
Reader 理解分层即可。Beginner 跑通 demo。Intermediate 需要组合协议和 guardrails。Advanced 必须具备 audit、webhook、refund、dispute、CI eval 和 incident response。
References
ACP（Agentic Commerce Protocol）
重点读 merchant、cart、checkout、fulfillment、refund、dispute。
AP2（Agent Payments Protocol）
重点读 intent、mandate、signature、revocation、authorization scope。
x402
重点读 HTTP 402 flow、payment proof、retry、settlement rail、API pricing。
MPP（Machine Payments Protocol）
重点读 session cap、持续调用、settlement window、revoke。
Adjacent protocols
A2A、ERC-8004、TAP、wallet policy、stablecoin rails、identity protocols 都可能是相邻层。
OpenAI Agents SDK
重点读 function tools、run context、tool input guardrails、tracing、handoffs。
Related Agent Factory crash courses
先学 Build Agents、Digital FTE、Production Worker、Eval-Driven Development 和 Deployment，再把付款能力接入生产。
Operational and contract-layer tools
需要 vault、key rotation、audit database、webhook verifier、durable workflow、incident runbook 和 legal/finance review。