文档
UCP 与 AP2 集成

UCP 与 AP2 集成

UCP 与 Agent Payments Protocol (AP2) 深度集成，通过 AP2 Mandates Extension 为智能体交易提供加密级别的安全保障。

集成概述

UCP + AP2 的协同

UCP 作为商业协议的基础层，定义了 Checkout、Cart、Order 等核心能力。AP2 作为信任层，在这些能力之上添加加密证明机制：

  flowchart LR
    A[UCP Core] --> B[Checkout Capability]
    C[AP2 Extension] --> D[AP2 Mandates]
    B --> E[Secure Checkout]
    D --> E
    E --> F[Verifiable Transaction]

核心价值

特性UCP 基础能力+ AP2 扩展
交易完整性结构化数据加密签名验证
用户意图证明可选授权强制签名授权
支付凭证基础支付方法可验证数字凭证
争议解决订单记录完整证据链
智能体就绪基础支持完全支持

AP2 Mandates 扩展

能力声明

商家在 Profile 中声明支持 AP2：

{
  "capabilities": [
    {
      "name": "dev.ucp.shopping.checkout",
      "version": "2026-01-11",
      "spec": "https://ucp.dev/specification/checkout",
      "schema": "https://ucp.dev/schemas/shopping/checkout.json"
    },
    {
      "name": "dev.ucp.shopping.ap2_mandate",
      "version": "2026-01-11",
      "spec": "https://ucp.dev/specification/ap2-mandates",
      "schema": "https://ucp.dev/schemas/shopping/ap2_mandate.json"
    }
  ]
}

协议流程 

  sequenceDiagram
    participant P as Platform
    participant B as Business
    participant U as User
    participant PP as Payment Processor

    Note over P,B: 1. 协商能力
    P->>B: Get Profile
    B--)P: 返回能力列表（包含 AP2）

    Note over P,B: 2. 创建 Checkout
    P->>B: Create Checkout (激活 AP2)
    B--)P: Checkout + ap2.merchant_authorization

    Note over U: 3. 用户授权
    U->>P: 确认购买

    Note over P: 4. 生成 Mandates
    P->>P: 生成 CheckoutMandate
    P->>P: 生成 PaymentMandate

    Note over P,B: 5. 完成交易
    P->>B: Complete Checkout + Mandates
    B->>PP: 验证 PaymentMandate
    PP--)B: 支付授权
    B--)P: 订单确认

数据结构

CheckoutMandate（商家保护） 

{
  "ap2": {
    "checkout_mandate": "eyJhbGciOiJFUzI1NksiLCJraWQiOiJkaWQ...",
    "merchant_authorization": "eyJhbGciOiJFUzI1NksiLCJraWQ..."
  }
}

PaymentMandate（支付授权） 

{
  "ap2": {
    "payment_mandate": {
      "payment_mandate_id": "pm_12345",
      "payment_details_id": "order_shoes_123",
      "payment_details_total": {
        "label": "Total",
        "amount": {
          "currency": "USD",
          "value": 120.00
        }
      }
    },
    "user_authorization": "eyJhbGciOiJFUzI1NksiLCJraWQ..."
  }
}

术语映射

UCP 概念AP2 概念说明
Checkout ObjectCartMandate商家对购买要约的签名确认
CheckoutMandate用户购买授权用户对购买内容的签名授权
PaymentMandatePaymentMandate用户对支付凭证的授权

集成场景

智能体购物场景

  1. 探索阶段（Cart）

    • 智能体使用 Cart 能力探索商品
    • 无需支付配置，轻量级操作

  2. 购买意向（Checkout + AP2）

    • 转换为 Checkout 会话
    • 激活 AP2 Mandates 扩展
    • 获取商家签名授权

  3. 用户确认（Mandates 生成）

    • 用户在可信界面确认
    • 生成 CheckoutMandate 和 PaymentMandate

  4. 交易完成（验证与执行）

    • 商家验证 Mandates
    • 支付处理器验证 PaymentMandate
    • 完成支付并确认订单

实施指南

平台端 

# 伪代码示例
def create_checkout_with_ap2(cart_id):
    # 1. 创建 Checkout（激活 AP2）
    checkout = ucp_client.create_checkout(
        cart_id=cart_id,
        extensions=["ap2_mandate"]
    )

    # 2. 获取商家授权
    merchant_auth = checkout.ap2.merchant_authorization

    # 3. 用户确认后生成 Mandates
    if user_confirms():
        checkout_mandate = sign_checkout(checkout, merchant_auth)
        payment_mandate = generate_payment_mandate(checkout)

        # 4. 完成交易
        result = ucp_client.complete_checkout(
            checkout.id,
            ap2={
                "checkout_mandate": checkout_mandate,
                "payment_mandate": payment_mandate
            }
        )
    return result

商家端 

# 伪代码示例
def handle_create_checkout(request):
    # 1. 创建 Checkout 会话
    checkout = create_checkout_session(request)

    # 2. 如果协商了 AP2，添加商家授权
    if "ap2_mandate" in negotiated_capabilities:
        checkout.ap2 = {
            "merchant_authorization": sign_checkout(checkout)
        }

    return checkout

def handle_complete_checkout(request):
    # 1. 验证 AP2 Mandates
    if "ap2_mandate" in negotiated_capabilities:
        verify_merchant_authorization(request.checkout)
        verify_checkout_mandate(request.ap2.checkout_mandate)

    # 2. 处理支付
    payment_result = process_payment(
        request.ap2.payment_mandate
    )

    return order_confirmation

相关链接

UCP 规范

AP2 资源

中文站点：

官方资源：

相关协议

架构设计版本管理