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: 支付授权，包含交易信息和用户签名

使用场景

场景一：人工在场卡支付

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

分步启动

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

1. 启动商户代理

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

2. 启动凭证提供商

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

3. 启动商户支付处理代理

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

4. 启动购物代理

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

交互流程

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

场景二：x402 支付

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

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

高级功能

1. 详细模式 (Verbose Mode)

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

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

详细模式将显示：

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

2. 代理通信日志

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

日志包含三类数据：

代码架构

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，返回形如 {"token": "fake_payment_credential_token_x"}`。
    • 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 描述对外能力（如“查询可用支付方式”“获取收货地址”）。

典型交互顺序（摘要）

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

提示：以上数据键常量定义于 ap2.types 模块；工具间通过 TaskUpdater 产出 DataPart 返回工件，供上游代理继续编排。

扩展开发

1. 创建新的支付方式

要支持新的支付方式，需要：

1. 在 agent.json 中声明扩展支持
2. 实现相应的处理逻辑
3. 更新验证规则

2. 添加新的代理角色

创建新代理需要：

1. 继承 BaseServerExecutor
2. 实现必要的工具函数
3. 配置代理描述文件

故障排除

常见问题

1. Google API Key 错误

   • 确保 API Key 正确设置
   • 检查 API Key 是否有效

2. 端口冲突

   • 确保所需端口（8000-8003）未被占用
   • 可以修改配置文件中的端口设置

3. 依赖安装失败

   • 确保 Python 版本 >= 3.10
   • 尝试清除缓存：uv cache clean

调试技巧

1. 查看 watch.log 文件了解详细的通信过程
2. 使用详细模式获取更多调试信息
3. 检查各个服务的控制台输出

最佳实践

1. 安全性: 始终验证支付授权的签名
2. 错误处理: 实现完善的错误处理机制
3. 日志记录: 记录关键操作用于调试和审计
4. 测试: 在生产环境前充分测试所有支付流程

总结

AP2 提供了一个强大而灵活的代理支付协议框架。通过本教程，您应该能够：

• 理解 AP2 的核心概念和架构
• 成功运行示例项目
• 开发自定义的支付代理
• 处理常见问题和故障

更多详细信息，请参考项目中的具体代码实现和注释。

AP2 (Agent Payments Protocol) 使用教程