AP2 (Agent Payments Protocol) 使用教程

概述

AP2 (Agent Payments Protocol) 是一个用于代理支付的协议，支持人工在场和人工不在场的商务流程。本教程将详细介绍如何使用 AP2 Python 示例项目。

项目结构

samples/python/
├── src/ap2/                    # AP2 核心代码
├── scenarios/                  # 使用场景示例
│   └── a2a/human-present/     # 人工在场支付场景
│       ├── cards/             # 卡支付示例
│       └── x402/              # x402 支付示例
├── pyproject.toml             # 项目配置
└── README.md                  # 项目说明

环境要求

Python 3.10+
uv 包管理器
Google API Key (用于 AI 功能)

安装步骤

1. 安装 uv 包管理器

如果您还没有安装 uv，请访问 uv 安装指南进行安装。

2. 克隆项目并安装依赖

# 克隆项目
git clone https://github.com/google-agentic-commerce/AP2.git# 进入项目目录
cd AP2/samples/python# 安装依赖
uv sync

3. 配置 Google API Key

从 Google AI Studio 获取 API 密钥，然后选择以下方式之一进行配置：

环境变量

export GOOGLE_API_KEY=your_api_key_here

核心概念

1. 关键角色 (Key Actors)

Shopping Agent (购物代理): 主要协调者，处理用户购物请求并委托给专门的代理
Merchant Agent (商户代理): 处理来自购物代理的产品查询
Merchant Payment Processor Agent (商户支付处理代理): 代表商户处理支付
Credentials Provider Agent (凭证提供商代理): 管理用户支付凭证

2. 核心数据结构

IntentMandate: 意图授权，包含购买意图信息
CartMandate: 购物车授权，由商户签名确保报价准确性
PaymentMandate: 支付授权，包含交易信息和用户签名

使用场景

场景一：人工在场卡支付

这是最常见的支付场景，用户在场确认购买详情和支付方式。

分步启动

如果您希望在不同终端中运行各个服务：

启动商户代理

# AP2/samples/python
uv run --package ap2-samples python -m roles.merchant_agent

启动凭证提供商

# AP2/samples/python
uv run --package ap2-samples python -m roles.credentials_provider_agent

启动商户支付处理代理

# AP2/samples/python
uv run --package ap2-samples python -m roles.merchant_payment_processor_agent

启动购物代理

# AP2/samples/python
uv run --package ap2-samples adk web src/roles

交互流程

访问界面: 打开浏览器访问 http://0.0.0.0:8000/dev-ui
选择代理: 从下拉菜单选择 shopping_agent
发起请求: 输入购买意图，如 "我想买一个咖啡机"
产品搜索: 购物代理委托商户代理查找匹配产品
创建购物车: 商户代理创建 CartMandate 并分享给购物代理
选择产品: 从展示的产品中选择
链接凭证提供商: 连接您的首选凭证提供商
选择支付方式: 从可用支付方式中选择
创建支付授权: 购物代理创建 PaymentMandate 并请求签名
OTP 验证: 输入模拟 OTP 123
完成购买: 收到确认消息和数字收据

场景二：x402 支付

支持 x402 兼容的支付方式（即将推出完整的 AP2 兼容版本）。

启动方式类似卡支付场景，但使用 x402 相关的脚本和配置。

高级功能

1. 详细模式 (Verbose Mode)

要了解代理内部工作原理，可以启用详细模式：

我想买一双新鞋。请在整个过程中保持详细模式，解释你在做什么，并显示所有数据载荷。

详细模式将显示：

当前和下一步的详细说明
所有数据载荷的 JSON 表示
创建、发送或接收的授权对象

2. 代理通信日志

系统会自动创建详细的日志文件 watch.log，位于 .logs 目录中。

日志包含三类数据：

类别	包含内容
原始 HTTP 数据	HTTP 方法、URL、JSON 请求体和响应体
A2A 消息数据	从 A2A 消息的 TextPart 提取的请求指令和 DataParts 中的数据
AP2 协议数据	在消息 DataParts 中识别的授权对象

代码架构

1. 消息构建器

A2aMessageBuilder 类用于构建 A2A 消息：

builder = A2aMessageBuilder()
message = builder.add_text("Hello").add_data("key", data).build()

2. 基础服务执行器

BaseServerExecutor 提供了代理的基础功能：

处理请求和响应
管理扩展
工具解析和执行

3. 支付验证

系统包含支付授权验证逻辑，确保交易安全性：

def validate_payment_mandate_signature(payment_mandate: PaymentMandate) -> None:if payment_mandate.user_authorization is None:raise ValueError("User authorization not found in PaymentMandate.")

4. Credentials Provider Agent 代码解释

该代理扮演“数字钱包”，负责存储/检索用户的支付方式与收货地址，并在支付流程中生成并验证“支付凭证令牌（token）”。核心代码位于 samples/python/src/roles/credentials_provider_agent/：

启动入口：__main__.py
- 加载本地 agent.json 描述为 agent_card。
- 以端口 8002 启动服务，RPC 路径为 /a2a/credentials_provider。
- 创建 CredentialsProviderExecutor 并传入支持的扩展列表。
执行器：agent_executor.py
- CredentialsProviderExecutor 继承自 BaseServerExecutor，通过系统提示约束“只输出工具调用，不与用户闲聊”。
- 注册的工具包括：
  - handle_get_shipping_address
  - handle_search_payment_methods
  - handle_create_payment_credential_token
  - handle_signed_payment_mandate
  - handle_get_payment_method_raw_credentials
工具集：tools.py
- 公用数据键：
  - 收货地址键：CONTACT_ADDRESS_DATA_KEY
  - 支付授权键：PAYMENT_MANDATE_DATA_KEY
  - 商户可接受的支付方式数据键：PAYMENT_METHOD_DATA_DATA_KEY
- 关键处理函数：
  - handle_get_shipping_address
    - 输入：user_email
    - 动作：从账户管理器查询对应收货地址，产出到 CONTACT_ADDRESS_DATA_KEY。
  - handle_search_payment_methods
    - 输入：user_email 与一组 PaymentMethodData（商户可接受的条件，如卡网络等）。
    - 动作：调用内部匹配逻辑（_payment_method_is_eligible）筛选用户账户中符合商户条件的支付方式，返回 {"payment_method_aliases": [...]}。
  - handle_create_payment_credential_token
    - 输入：user_email, payment_method_alias。
    - 动作：为所选支付方式生成一次性“支付凭证令牌 token，返回形如 `。
  - handle_signed_payment_mandate
    - 输入：PaymentMandate（包含 payment_mandate_id 与支付相应细节中的 token）。
    - 动作：将签名后的 payment_mandate_id 绑定到此前生成的 token，用于后续校验。
  - handle_get_payment_method_raw_credentials
    - 输入：PaymentMandate（含 payment_mandate_id 与 token）。
    - 动作：验证 token 与 payment_mandate_id 的一致性，返回底层原始支付凭证（例如卡网络、DPAN/密文等），供支付处理方完成扣款。
账户与令牌管理：account_manager.py
- 内存数据库模拟多个账户，示例包含：
  - 用户的 shipping_address
  - 多种 payment_methods（如 CARD、BANK_ACCOUNT、DIGITAL_WALLET），卡片含网络与账单地址等。
- 令牌生命周期：
  - create_token(email, alias): 生成并保存 token（映射邮箱与支付方式别名）。
  - update_token(token, payment_mandate_id): 将签名后的 payment_mandate_id 绑定到 token（只写一次）。
  - verify_token(token, payment_mandate_id): 校验 token 与授权 ID 是否匹配，返回该支付方式的“原始凭证”。
- 账户查询能力：
  - get_account_shipping_address(email)
  - get_account_payment_methods(email)
  - get_payment_method_by_alias(email, alias)
代理能力声明：agent.json
- capabilities.extensions 声明支持 AP2 扩展和示例卡网络扩展。
- skills 描述对外能力（如“查询可用支付方式”“获取收货地址”）。

典型交互顺序（摘要）

购物代理提供商户可接受的 PaymentMethodData 与 user_email，调用 search_payment_methods 以获取可用 payment_method_aliases。
选择一个 payment_method_alias，调用 create_payment_credential_token 获得 token。
购物代理生成 PaymentMandate 并请求用户签名，签名完成后回传，凭证提供商用 signed_payment_mandate 将 payment_mandate_id 绑定到 token。
商户支付处理代理在完成支付前，调用 get_payment_method_raw_credentials，使用 token + payment_mandate_id 验证并换取底层原始支付凭证。