快速上手

本指南基于开源仓库 google-agentic-commerce/AP2。 运行其中的场景脚本即可启动参考购物代理、商家代理、凭证提供方以及 x402 兼容的支付服务，完整体验一次人到场（Human Present）的 AP2 结算。

环境要求

• Python 3.10+
• uv 0.4+
• 在 Google AI Studio 申请的 Google API Key
• macOS、Linux 或 WSL2（脚本会拉起多个后台进程）

ℹ️ 为何使用 uv？ 官方样例随仓库提供 uv 项目配置。运行脚本时会自动创建 虚拟环境、安装 ap2-samples 包并启动所有所需的代理服务。

1. 克隆仓库

git clone https://github.com/google-agentic-commerce/AP2.git
cd AP2

重点关注以下目录：

├── docs/                 # 白皮书、路线图与背景资料
├── samples/
│   ├── python/           # 人到场、x402 与凭证相关场景
│   └── android/          # 可选的 Android 购物界面
└── src/ap2/types/        # AP2 对象的 Python 参考类型

2. 配置 Google API Key

Python 样例依赖 Agent Development Kit (ADK) 与 Gemini 2.5 Flash。在运行前先导出 或写入 .env：

# 方式一：环境变量
export GOOGLE_API_KEY="your_key"

# 方式二：仓库根目录的 .env 文件
echo "GOOGLE_API_KEY=your_key" > .env

3. 运行人到场 x402 场景

cd samples/python/scenarios/a2a/human-present/x402
bash run.sh

脚本会自动完成：

1. 创建 .venv/ 并通过 uv 安装 ap2-samples 包。
2. 在端口 8001–8003 启动商家代理、凭证提供方、商家支付处理代理。
3. 通过 adk web 拉起购物代理，并在终端输出本地访问地址（如 http://localhost:3333）。

打开终端提示的地址，与购物助手对话、触发推荐并确认购买。流程中会生成：

• Intent Mandate：授权购物代理在限定范围内代表用户行事。
• Cart Mandate：汇总最终购物车并收集用户签名。
• Payment Mandate：由支付处理方与结算轨道共享，用于完成结算。

按 Ctrl+C 可终止脚本，所有后台进程会被自动清理。

4. 查看授权凭证与日志

脚本会在当前场景目录生成 .logs/ 文件夹，包含：

• watch.log —— 实时记录代理间的请求与响应，便于调试交互流程
• 终端输出 —— 显示生成的 Intent / Cart / Payment Mandate 以及结算凭证摘要

可根据日志提示复制 JSON 片段，使用 jq 等工具深入分析签名、哈希与策略轨迹。

5. 尝试其他场景

• samples/python/scenarios/a2a/human-present/cards/ —— 传统卡支付流程，仍使用 AP2 三类授权凭证。
• samples/android/scenarios/digital-payment-credentials/ —— 演示 Android 端持有支付 凭证的方式。
• 其他 run.sh 均附带 README，说明所需环境变量与预期结果。

下一步

• 阅读 核心对象模型，将 AP2 集成进自有智能体。
• 查阅 支付轨道指南，了解 x402 如何映射到 AP2 结算行为。
• 参考 常见问题，获取策略、合规与生产化上线建议。