😸

AIエージェントの支払いのためのプロトコル「AP2」 のデモコードを試してみました。(Windows環境)

に公開
Windows
AP2
tech

Google が発表したAIエージェントの支払いのためのプロトコル「AP2」 のデモコードを試してみました。

今後、エージェントで、支払いが可能になることが予想され、プロダクトへの導入の可能性が高まっています。

そもそも、AP2が何かよくわかっておりませんでしたので、今回試して理解を深めようと思い、公式リポジトリのデモコードを試してみました。

私がWindowsユーザーでございまして、公式のGitHub の README　に従って実施しましたが、Windows環境の場合、READMEの通りには、実行できなかった点がございました。

AP2とは

  • Perplexicityの説明

Agent Payments Protocol（AP2）を簡単に言うと、
AIが人の代わりに安全にお金を支払うための共通ルールです。
もう少し具体的に表現すると、次のようになります。
目的：AIエージェントがユーザーの代わりに「買う」「契約する」といった行動を安全に実行できるようにする。
仕組み：暗号署名付きの「Mandate（委任契約）」を使って、取引が正しいか、誰の意思かを機械的に証明する。
特徴：クレジットカード、銀行振込、ステーブルコインなど、あらゆる決済方式に対応可能なオープン規格である。
役割：AIエージェント時代の決済を支える「デジタル経済の共通言語」。
端的にまとめると、
AP2とは、AIがユーザーに代わって安心して支払いを行えるようにする世界共通の決済ルールです

  • 公式の説明

https://ap2-protocol.org/

https://github.com/google-agentic-commerce/AP2

(一部抜粋)

AP2とは
エージェント決済プロトコル（AP2）は、新興のエージェントエコノミーのためのオープンプロトコルです。開発者、加盟店、そして決済業界にとって、安全で信頼性が高く、相互運用可能なエージェントコマースを実現するために設計されています。このプロトコルは、オープンソースの Agent2Agent（A2A）プロトコルの拡張機能として利用可能であり、現在、さらなる統合が進められています。

Mandate とは

  • 以下サイトによる説明

https://masouken.com/マンデ―トとは

マンデート（mandate）とは、英語を直訳すると、権限・命令・指令・任務のほか、職務執行令状・委任統治といった意味を持つ言葉です。広く使われる意味としては「権限」が一般的であり、実際には「誰かから誰かに対して与えられた権限」といった意味で使用します。

東京証券取引所の『証券用語集』によると、マンデートは「証券会社や銀行などの金融機関が、企業が株式の発行（募集）・企業の上場・シンジケートローンの組成などで資金調達を行う際に、その企業から業務の委任を受けること」とされています。

上記のようにマンデートは、金融だけでなく、政治・裁判・M&Aシーンなど、さまざまな専門分野で使われる言葉です。

  • Perplexicityの説明

Mandate（マンデート）の実体は「暗号署名付きのデジタル契約データ」です。
その中でも Payment Mandate は、実際の支払い命令を表すデータ構造体（JSON）として存在します。
AP2の中では、Payment Mandateは次のような流れで生成・利用されます:

  1. Intent Mandate：ユーザーの意図・条件を構造化して署名。
  2. Cart Mandate：実際の取引内容（商品・金額など）を確定し署名。
  3. Payment Mandate：決済処理システムに提出する正式な「支払い命令書」。
    この3つのMandateが鎖（chain）として連結され、

誰が・何を・どの条件で承認したかを後から完全に追跡可能にします。

要は、実態は、暗号化された署名付きJSON形式のデジタル契約データで、これをエージェント同士がやりとりして、やり取りの信頼性を担保しながら、自動で購入できるようにしているという理解です。

環境

  • Windows 環境
  • ターミナル
    • Git Bash ターミナル
  • AP2
    • v0.1.0

事前準備

  • Google AI Studio API　もしくは、、Google Cloud からAPIキーを発行
    • 以下のGItHubリポジトリのREADMEに沿って設定しました。
    • Google AI Studio　からAPIキーを発行する方法と、Google Cloud から発行する方法の説明が記載がありました。今回は、Google Cloud から発行したAPIキーを利用しました。

https://github.com/google-agentic-commerce/AP2?tab=readme-ov-file#quickstart

  • Python のバージョン管理ライブラリの uv をセットアップ
    • Python の仮想環境を作成する最新のライブラリで、各Python のライブラリ、モジュールのインストールが高速。
    • 公式の手順に沿ってインストールします。

https://docs.astral.sh/uv/getting-started/installation/#installation-methods

  • VsCodeのインストール

https://code.visualstudio.com/download

  • Git のセットアップ
  • Git Bash ターミナル(Mac や WSLの場合は不要です。)
    • 以下のサイトが大変わかりやすいです。

https://prog-8.com/docs/git-env-win

AP2のソースコードをローカルに持ってくる

  • AP2のREAD.mdに沿って、環境をセットアップします。

https://github.com/google-agentic-commerce/AP2

  • ローカルの任意のディレクトリにクローンします。
    ※ 上記記載のサイトにセットアップ方法が詳しく記載ありまして、SSH認証の設定されている場合以下のコードでクローンを実施
# SSH用
git clone git@github.com:google-agentic-commerce/AP2.git
  • AP2ディレクトリに移動して、bash samples/python/scenarios/a2a/human-present/cards/run.sh をターミナルで実行します。
    • このbash スクリプトで、以下のエージェントが自分のローカルで 起動します。
      • Shopping Agent：ユーザー操作の窓口（ブラウザUI）
      • Merchant Agent：販売側のエージェント
      • Card Processor：決済処理を担当する
      • Credentials Provider：各エージェントに資格情報を渡す

Windows 環境でのエラーの対処

※ README 通り実行すると、Windows の場合エラーが発生しました。

Windows 環境の改行コードに関するエラー

bash samples/python/scenarios/a2a/human-present/cards/run.sh samples/python/scenarios/a2a/human-present/cards/run.sh: line 2: $'\r': command not found samples/python/scenarios/a2a/human-present/cards/run.sh: line 6: $'\r': command not found : invalid optioncenarios/a2a/human-present/cards/run.sh: line 8: set: - set: usage: set [-abefhkmnptuvxBCHP] [-o option-name] [--] [arg ...] samples/python/scenarios/a2a/human-present/cards/run.sh: line 9: $'\r': command not found samples/python/scenarios/a2a/human-present/cards/run.sh: line 14: $'\r': command not found samples/python/scenarios/a2a/human-present/cards/run.sh: line 52: syntax error near unexpected token $'{\r'' 'amples/python/scenarios/a2a/human-present/cards/run.sh: line 52: cleanup() {

  • 改行コードに関するエラーがでました。Windowsのコマンドプロンプト/Power shell に対応していないようだったので、git bah ターミナルに変更しました。(エディタで改行コードを変えるとコマンドプロンプト/Power Shell のままでも実行できるかもしれません。)

Windows環境で bashファイル内の、uv の仮想環境のアクティベイトするコードでエラー

$ source .venv/bin/activate
bash: .venv/bin/activate: No such file or directory

  • bashファイルの中のuv で仮想環境にアクティベイトするコードが Linux 環境のコードだったため、 Windows用のディレクトリ構造に変更して(.venv/Scripts 配下に activate がある)、再度 bash スクリプトを実行しました。
  • 以下の画像の箇所を変更しました。

  • 変更コード
source .venv/Scripts/activate

デモ手順全体

README記載の手順

https://github.com/google-agentic-commerce/AP2/blob/main/samples/python/scenarios/a2a/human-present/cards/README.md#executing-the-example

以下がREADMEに記載のある手順で、これを実施していきました。

ショッピングエージェントとのやり取り
このセクションでは、サンプルとの一般的なやり取りについて説明します。

  1. エージェント開発キットUIの起動：コンピュータでブラウザを開き、0.0.0.0:8000/dev-uiにアクセスします。左上隅のドロップダウンshopping_agentから選択します。Select an agent
  2. 最初のリクエスト：ショッピングエージェントの端末で、会話を開始するように求められます。「コーヒーメーカーを購入したい」のように入力してください。
  3. 製品検索: ショッピング エージェントはマーチャント エージェントに委任し、マーチャント エージェントはユーザーの意図に一致する製品を検索し、CartMandates に含まれるオプションを提示します。
  4. カート作成：マーチャントエージェントは1つ以上のCartMandateカートを作成し、ショッピングエージェントと共有します。各CartMandateはマーチャントによって署名され、ユーザーへのオファーが正確であることを保証します。
  5. 製品の選択ショッピング エージェントは、選択できる製品のセットをユーザーに提示します。
  6. 資格情報プロバイダーのリンク: ショッピング エージェントは、利用可能な支払い方法にアクセスするために、優先する資格情報プロバイダーをリンクするように要求します。
  7. お支払い方法の選択：カートを選択すると、ショッピングエージェントが認証情報プロバイダーエージェントから利用可能なお支払い方法のリストを表示します。お支払い方法を選択してください。
  8. PaymentMandateの作成：ショッピングエージェントはカートと取引情報をPaymentMandateにまとめ、署名を求めます。PaymentMandateを使用して支払いを開始します。
  9. OTPチャレンジ：加盟店決済処理業者がOTPを要求し、エージェントに模擬OTPを提供するよう求め>られます。123
  10. 購入完了: OTP が提供されると、支払いが処理され、確認メッセージとデジタル領収書が届きます。

用語の整理

主要な登場人物

https://github.com/google-agentic-commerce/AP2/blob/main/samples/python/scenarios/a2a/human-present/cards/README.md#key-actors

このサンプルは次のものから構成されます:

  • Shopping Agent(ショッピング エージェント):ユーザーのショッピング リクエストを処理し、タスクを専門のエージェントに委任するメイン オーケストレーター。
  • Merchant Agent(マーチャント エージェント):ショッピング エージェントからの製品クエリを処理するエージェント。
  • Merchant Payment Processor Agent(加盟店支払い処理エージェント):加盟店に代わって支払いを受け取るエージェント。
  • Credentials Provider Agent(認証情報プロバイダーエージェント)：認証情報プロバイダーは、ユーザーの支払い認証情報を保有します。そのため、主に2つの役割を果たします。
    • ショッピングエージェントに、ユーザーのウォレットで利用可能な支払い方法のリストを提供します。
    • ショッピングエージェントと販売者の決済プロセッサ間の決済を容易にします。

ブラウザで表示されるShopping エージェントとそのサブエージェント

  • Shopping エージェント = 「root_agent」

  • Shopping Agent のサブエージェントに、「shopper」「shipping_address_collector」、「payment_method_collector」エージェントがいることが確認できました。

  • Copilot に、Sopping Agent(root_agent)とサブエージェント、ツールの関係を階層構造で図示してもらいました。

root_agent (RetryingLlmAgent)
├── Tools
│   ├── create_payment_mandate
│   ├── initiate_payment
│   ├── initiate_payment_with_otp
│   ├── send_signed_payment_mandate_to_credentials_provider
│   ├── sign_mandates_on_user_device
│   └── update_cart
│
└── Sub Agents
    ├── shopper (RetryingLlmAgent)
    │   └── Tools
    │       ├── create_intent_mandate
    │       ├── create_cart
    │       ├── get_cart_mandate
    │       └── update_cart_mandate
    │
    ├── shipping_address_collector (RetryingLlmAgent)
    │   └── Tools
    │       ├── contact_picker_tools
    │       └── address関連ツール
    │
    └── payment_method_collector (RetryingLlmAgent)
        └── Tools
            ├── get_payment_methods
            └── payment関連ツール

共通コンポーネント
├── remote_agents/
│   ├── credentials_provider_client
│   └── merchant_agent_client
└── artifact_utils (共通ユーティリティ)

登場するMandate(マンデート)

  • Perplexicityの説明　(再掲)

Mandate（マンデート）の実体は「暗号署名付きのデジタル契約データ」です。
その中でも Payment Mandate は、実際の支払い命令を表すデータ構造体として存在します。
AP2の中では、Payment Mandateは次のような流れで生成・利用されます:

  1. Intent Mandate：ユーザーの意図・条件を構造化して署名。
  2. Cart Mandate：実際の取引内容（商品・金額など）を確定し署名。
  3. Payment Mandate：決済処理システムに提出する正式な「支払い命令書」。

この3つのMandateが鎖（chain）として連結され、誰が・何を・どの条件で承認したかを後から完全に追跡可能にします。

デモ手順実施

※README記載の手順に従って実行します。
https://github.com/google-agentic-commerce/AP2/blob/main/samples/python/scenarios/a2a/human-present/cards/README.md#executing-the-example

1. エージェント開発キットUIの起動

  • 以下のコマンドをターミナルで実行します。
bash samples/python/scenarios/a2a/human-present/cards/run.sh
  • サーバーが起動しました。

  • 以下のURLをブラウザから開きました。
    ※READMEには、0.0.0.0:8000/dev-ui　にアクセスするように記載がありますが、ブラウザから確認するには、以下のURLで確認できました。
http://127.0.0.1:8000/dev-ui/
or
http://localhost:8000/dev-ui/
  • ショッピングエージェントとのやり取りを開始できます。
  • 立ち上がった画面のサイドバーにあるプルダウンから shopping_agent を選択します

2. 最初のリクエスト

  • READMEに従って、「コーヒーメーカーを購入したい」と質問します。商品の詳細を求められるので回答します。

  • Shopping エージェント(root_agent)がtransfer_to_agentという関数を実行して回答してくれました。

  • transfer_to_agentというShopping エージェント(root_agent)がツールとして呼び出してる関数名が表示されています。google adk というGoogle のエージェント開発用ライブラリの transfer_to_agent 関数を実行しています。
  • transfer_to_agent関数は、以下のライブラリのソースにあるように「質問を別のエージェントに転送」する関数でした。

AP2\.venv\Lib\site-packages\google\adk\tools\transfer_to_agent_tool.py
transfer_to_agent関数 
質問を別のエージェントに転送します。

このツールは、ユーザーの質問に対して、エージェントの説明に従い
より適切に回答できる別のエージェントへ制御を引き渡します。

3. 製品検索

  • 次に、何ターンかやりとりすると、サブエージェントである「shopper」エージェントが登場して、新たな回答が出ました。コーヒーメーカーの種類や仕様、価格など条件を細かくエージェントが聞いてくれました。


  • ここで、サブエージェント「shopper_agent」がcreate_intent_mandateという関数を実行しています。「Intent Mandate(意図の委任状)を用いて、エージェントが特定の商品を検索し、販売者と交渉することを認可」するために必要なIntent Mandate(意図の委任状)を作成している関数と思っております。サブエージェント「shopper_agent」も「販売店に共有します」と回答し確認を求めてきています。

  • サブエージェント「shopper_agent」のツールとしての関数のようでした。

samples\python\src\roles\shopping_agent\subagents\shopper\tools.py
create_intent_mandate 関数
  訳
  """IntentMandateオブジェクトを作成します。

  引数:
    natural_language_description: ユーザーの意図の説明。
    user_cart_confirmation_required: ユーザーがカートを確認する必要があるかどうか。
    merchants: 許可されたマーチャントのリスト。
    skus: 許可されたSKUのリスト。
    requires_refundability: 商品が返金可能である必要があるかどうか。
    tool_context: ADKが提供するツールコンテキスト。

  戻り値:
    1日間有効なIntentMandateオブジェクト。
  • IntentMandate について、GitHubソースを検索すると、以下に説明がありました。どうやら、Merchant Agents　とやり取りするために必要なオブジェクトのようです。
https://github.com/google-agentic-commerce/AP2/blob/main/samples/python/scenarios/a2a/human-present/cards/README.md#scenario

IntentMandateは、
加盟店エージェント(Merchant Agents)と適切な情報を共有するために引き続き活用されます。
これは、有人対応フローと無人対応フローの一貫性を維持するためです。
人間が立ち会うすべての購入には、購入を承認するユーザー署名の PaymentMandate が付きます。

4. カート作成

ここはUI上に表示されないようです。
Perplexcityの説明を整理

  • 販売者側エージェント（merchant_agent）は、　サブエージェントshopper_agentから送られてきた Intent Mandate（意図の委任状） を受け取ります。
  • カート作成（CartMandate 生成）は、販売者側エージェント（merchant_agent）がバックエンドで実行します。
  • そのためユーザーUIには表示されず、表面的には「find_products」関数が先に見えるように感じます。
  • CartMandate（カート委任状）とは、販売者が「この商品をこの価格で販売できます」と正式に提示したデータ
  • 署名付き” というのは、販売者（マーチャント）が自分の電子署名を付けており、
    「この情報は確かに私たち（販売者）が出した見積りです」 と証明した上で、サブエージェントshopper_agentに共有します。

5. 製品の選択

  • 今度は、find_products関数を実行しています。
  • すると、ドキュメント記載のある「Shopping エージェント(たぶんサブエージェントshopper_agentと同じと類推)は、選択できる製品のセットをユーザーに提示」してくれました。
  • 任意の商品の番号を入力しました。

  samples\python\src\roles\shopping_agent\subagents\shopper\tools.py 
  find_products 関数
  ユーザーの意図に合った商品を見つけるため、マーチャントエージェントを呼び出します。

  引数:
    tool_context: ADKから提供されるツールコンテキスト
    debug_mode: エージェントがデバッグモードかどうか

  戻り値:
    CartMandateオブジェクトのリスト

  例外:
    RuntimeError: マーチャントエージェントが商品を提供できなかった場合
  • 今度は、update_chosen_cart_mandate関数というものが実行されて、配送住所の入力を求められました。

  • デモ用なので、テスト用の住所を入力します。すると、Shopping エージェント(root_agent)に戻って、「デジタルウォレットに関する認証」について質問がきました。

6. 資格情報プロバイダーのリンク

  • 「デジタルウォレットで」と回答すると、認証情報プロバイダーに関する説明と確認を求められます。テスト用なので、はいと返します。

  • Shopping エージェント(root_agent)のサブエージェントである「shipping_address_collector」という新たなエージェントが動き、そのあと、Shopping エージェント(root_agent)に戻ってなにやら動いています。

7. お支払い方法の選択

  • 続いて、Shopping エージェント(root_agent)のサブエージェントである「payment_method_collector」という新たなサブエージェントが動き、購入内容、配送先住所(デモ用)が表示されています。次に、「支払い方法」を選択するように要求されるので、任意の番号を答えます。

8. PaymentMandateの作成

  • 途中で、create_payment_mandateという関数が走っているので、「PaymentMandate」というものの作成が行われていると思います。
  • すると、Shopping エージェント(root_agent)エージェントが、注文商品の最終確認を求めました。

9. OTPチャレンジ

  • READMEの手順の「OTPチャレンジ：加盟店決済処理業者がOTPを要求し、エージェントに模擬OTPを提供するよう求められます。123」とあるので、おそらくこの確認コードを入力するやり取りのことと思われます。記載の通り「123」とデモ用コードを入れます。

  • Perplexicity の回答

OTPチャレンジとは、「ワンタイムパスワード（OTP）を使った認証の要求」のことです。
特にAgent Payments Protocol（AP2）などの安全な決済システムで用いられます。

10. 購入完了

  • 支払いが完了したとのことです。

参考サイト

Discussion