代理支付协议 (AP2)

此仓库包含代理支付协议的代码示例和演示。

AP2 简介视频

AP2 在《代理工厂》中

关于示例

这些示例使用了 代理开发工具包 (ADK) 和 Gemini 2.5 Flash。

不过，代理支付协议并不强制要求使用这两者。尽管示例中使用了它们，但您可以自由选择任何您喜欢的工具来构建您的代理。

导航仓库

samples 目录包含一系列精心挑选的场景，旨在展示代理支付协议的关键组件。

这些场景位于 samples/android/scenarios 和 samples/python/scenarios 目录中。

每个场景都包含：

• 一个 README.md 文件，描述场景并提供运行说明。
• 一个 run.sh 脚本，用于简化在本地运行场景的过程。

此演示涉及多种代理和服务器，大部分源代码位于 samples/python/src 中。而那些以 Android 应用作为购物助手的场景，其源代码则位于 samples/android 目录中。

快速入门

前提条件

• Python 3.10 或更高版本
• uv 包管理器

设置

您可以使用 Google API 密钥或 Vertex AI 进行身份验证。

无论采用哪种方式，都可以将所需凭据设置为 shell 中的环境变量，或将它们放入项目根目录下的 .env 文件中。

选项 1：Google API 密钥（推荐用于开发）

1. 从 Google AI Studio 获取 Google API 密钥。

2. 设置 GOOGLE_API_KEY 环境变量。

   • 作为环境变量：

     export GOOGLE_API_KEY='your_key'
     

   • 在 .env 文件中：

     GOOGLE_API_KEY='your_key'
     

选项 2：Vertex AI（推荐用于生产）

1. 配置环境以使用 Vertex AI。

   • 作为环境变量：

     export GOOGLE_GENAI_USE_VERTEXAI=true
     export GOOGLE_CLOUD_PROJECT='your-project-id'
     export GOOGLE_CLOUD_LOCATION='global' # 或您偏好的区域
     

   • 在 .env 文件中：

     GOOGLE_GENAI_USE_VERTEXAI=true
     GOOGLE_CLOUD_PROJECT='your-project-id'
     GOOGLE_CLOUD_LOCATION='global'
     

2. 对您的应用进行身份验证。

   • 使用 gcloud CLI：

     gcloud auth application-default login
     

   • 使用服务账户：

     export GOOGLE_APPLICATION_CREDENTIALS='/path/to/your/service-account-key.json'
     

如何运行一个场景

要运行特定场景，请按照其 README.md 中的说明操作。通常遵循以下步骤：

1. 导航到仓库的根目录。

   cd AP2
   

2. 运行启动脚本以安装依赖项并启动代理。

   bash samples/python/scenarios/your-scenario-name/run.sh
   

3. 打开购物代理的 URL 并开始交互。

安装 AP2 类型包

该协议的核心对象定义在 src/ap2/types 目录中。PyPI 包将在稍后发布。在此之前，您可以使用以下命令直接安装类型包：

uv pip install git+https://github.com/google-agentic-commerce/AP2.git@main

AP2 (Agent Payments Protocol) 快速上手指南

AP2 是谷歌推出的智能体支付协议，旨在让 AI 智能体能够安全、自主地完成支付和购物任务。本指南将帮助你快速在本地运行官方提供的示例场景。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL2 推荐)
• Python 版本：Python 3.10 或更高版本
• 包管理器：uv (官方推荐，比 pip 更快)

提示：如果你尚未安装 uv，可以通过以下命令快速安装：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装步骤

1. 克隆项目

首先，从 GitHub 克隆 AP2 仓库到本地：

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

2. 配置认证凭证

AP2 示例依赖 Google 的生成式 AI 模型（如 Gemini）。你可以选择以下两种方式之一进行认证：

方式一：使用 Google API Key（推荐用于开发测试）

1. 访问 Google AI Studio 获取 API Key。
2. 在项目根目录创建 .env 文件并填入密钥：

echo "GOOGLE_API_KEY='your_key'" > .env

(请将 'your_key' 替换为你实际的 API Key)

方式二：使用 Vertex AI（推荐用于生产环境）

如果你使用的是 Google Cloud Vertex AI，请在 .env 文件中配置以下变量：

cat <<EOF > .env
GOOGLE_GENAI_USE_VERTEXAI=true
GOOGLE_CLOUD_PROJECT='your-project-id'
GOOGLE_CLOUD_LOCATION='global'
EOF

(请替换为你的项目 ID 和区域)

随后需要通过 gcloud 登录或使用服务账号密钥：

gcloud auth application-default login
# 或者导出服务账号密钥路径
# export GOOGLE_APPLICATION_CREDENTIALS='/path/to/your/service-account-key.json'

3. 安装核心类型包

目前协议的核心对象包尚未发布到 PyPI，需直接通过 Git 安装：

uv pip install git+https://github.com/google-agentic-commerce/AP2.git@main

基本使用

AP2 仓库包含多个预设的演示场景（Scenarios），展示了智能体如何执行支付流程。以下是运行一个典型场景的步骤：

1. 选择并进入场景

示例代码主要位于 samples/python/scenarios 目录下。假设我们要运行名为 simple-shopping 的场景（具体名称请查看该目录下的实际文件夹）：

cd samples/python/scenarios/simple-shopping

2. 运行场景脚本

每个场景都提供了一个 run.sh 脚本，它会自动安装该场景所需的依赖并启动智能体服务：

bash run.sh

3. 开始交互

脚本运行成功后，终端会输出一个本地 URL（通常是 Shopping Agent 的地址）。

• 在浏览器中打开该 URL。
• 按照界面提示与智能体对话，体验自动购物和支付流程。

注意：具体每个场景的业务逻辑和交互细节，请参阅对应场景文件夹内的 README.md 文件。