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. 主要アクター

• Shopping Agent（ショッピングエージェント）: メインコーディネーターで、ユーザーのショッピングリクエストを処理し、専門エージェントに委任
• Merchant Agent（マーチャントエージェント）: ショッピングエージェントからの商品クエリを処理
• Merchant Payment Processor Agent（マーチャント決済処理エージェント）: マーチャントに代わって決済を処理
• Credentials Provider Agent（認証情報プロバイダーエージェント）: ユーザーの決済認証情報を管理

2. コアデータ構造

• IntentMandate: 購入意図情報を含む意図認証
• CartMandate: マーチャントが署名した見積もりの正確性を保証するショッピングカート認証
• PaymentMandate: 取引情報とユーザー署名を含む決済認証

使用シナリオ

シナリオ1: 人間在席カード決済

これは最も一般的な決済シナリオで、ユーザーが在席して購入詳細と決済方法を確認します。

ステップバイステップ起動

各サービスを異なるターミナルで実行したい場合：

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. 購入完了: 確認メッセージとデジタルレシートを受信

シナリオ2: x402 決済

x402 互換の決済方法をサポート（完全な AP2 互換バージョンは近日公開予定）。

起動方法はカード決済シナリオと同様ですが、x402 関連のスクリプトと設定を使用します。

高度な機能

1. 詳細モード（Verbose Mode）

エージェントの内部動作を理解するために、詳細モードを有効にできます：

新しい靴を買いたいです。プロセス全体を通して詳細モードを維持し、何をしているかを説明し、すべてのデータペイロードを表示してください。

詳細モードでは以下が表示されます：

• 現在と次のステップの詳細説明
• すべてのデータペイロードの JSON 表現
• 作成、送信、または受信されるマンデートオブジェクト

2. エージェント通信ログ

システムは .logs ディレクトリに詳細なログファイル watch.log を自動作成します。

ログには3つのカテゴリのデータが含まれます：

コードアーキテクチャ

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 コード解説

このエージェントは「デジタルウォレット」として機能し、ユーザーの決済方法と配送先住所の保存/取得、および決済プロセス中の「決済認証トークン」の生成と検証を担当します。コアコードは 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": "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): トークンを生成・保存（メールと決済方法エイリアスをマッピング）。
    • update_token(token, payment_mandate_id): 署名された payment_mandate_id をトークンにバインド（一度のみ書き込み）。
    • verify_token(token, payment_mandate_id): トークンと認証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) 使用チュートリアル