メインコンテンツへ移動
AIチュートリアル

Claude Commerce Agentsでショッピングエージェントとマーチャントエージェントを構築・実行する

Claude Commerce Agentsのインストール方法、小売・旅行・通信・エンターテインメントのデモの実行方法、ショッピングエージェントとマーチャントエージェントをシステムに接続する方法、ランタイムの選択、フローのカスタマイズ、安全対策の適用、実装の検証方法を解説します。

約19分で読了
Claude Commerce Agentsでショッピング・マーチャントエージェントを構築・実行する

Claude Commerce Agents が提供するもの

Claude Commerce Agents は、Claude を基盤に構築された、コマースに特化した 2 つの AI エージェントのリファレンス実装です。企業は顧客向けアプリケーションにショッピングエージェントを組み込むことができ、スタッフはマーチャントエージェントを使ってバックオフィスのワークフローを運用できます。

各エージェントは、プロンプト、スキル、ツールのコントラクト、安全ゲートによって一度定義されます。同じ定義を Messages API、Claude Agent SDK、Managed Agents のいずれでも実行できます。実行可能な 4 つの業種別例で、小売、旅行、通信、エンターテインメントにまたがるアーキテクチャを示しています。

リポジトリ内の企業、製品、ブランド、人はすべて架空のものです。例では注文、カードへの請求、公開中のリスティング更新は行われません。チェックアウトはホストに委譲され、マーチャントによる書き込みは人が承認するまでステージングされたままになります。

2 つのエージェントの役割を理解する

ショッピングエージェント

ショッピングエージェントは、商品の検索や比較、購入計画、カートへの追加、注文やポリシーに関する質問への回答、顧客から提供された情報の記憶など、顧客向けのタスクをサポートします。

5 つのフローは shopping-agent/skills/ にあります。実際のシステムでエージェントを使用するには、関連するカタログ、カート、注文、ポリシーのサービスを対象に StorefrontBackend を実装します。

マーチャントエージェント

マーチャントエージェントは、スタッフによるパフォーマンスの把握、リスティングの管理、在庫や注文アラートへの対応、価格やプロモーションの調整、キャンペーンの下書きを支援します。5 つのフローは merchant-agent/skills/ にあります。

デプロイ環境では、MerchantBackend を実装して、分析、カタログ、在庫、価格設定、キャンペーンのシステムに接続します。すべての書き込みはすぐに適用されず、ステージングされます。ホストアプリケーションは提案された変更を表示し、承認する必要があります。

主なアーキテクチャと機能

  • 共有基盤: commerce-common/ には、両方の役割で使用する設定、フェンシング、メモリ、スキル処理、グラウンディング、プレゼンテーション、イベント、エグゼキューターフレームが含まれています。
  • 複数のランタイム: 同じプロンプト、スキル、ツールのコントラクトを Messages API、Agent SDK、Managed Agents で使用できます。
  • バックエンド抽象化: エージェントのツールはバックエンドインターフェースを呼び出すため、サーバーで認証情報を保持し、業務システムへのアクセスを仲介できます。
  • マーチャント変更のステージング: マーチャントによる書き込みには、ホストアプリケーションの承認画面を通じた承認が必要です。
  • 設定可能な機能: 対応していない機能を無効にすると、そのツール、プロンプトの行、グラウンディングルールが削除されます。
  • 拡張可能なプレゼンテーション: PresentationExtension を通じて、ドメイン固有のインターフェースを追加できます。
  • 実行可能な例: 4 つの業種それぞれに、ストアフロントとマーチャントポータルを提供する 8 つのウェブアプリケーションがあります。

前提条件

Python 3.11 以降とNode.js 22をインストールしてください。ライブモデルとのやり取りを実行するには、Anthropic API キーも必要です。

リポジトリをインストールする

プロジェクトをクローンし、Python 仮想環境を作成して固定された Python 依存関係をインストールし、環境ファイルを作成して、共有 JavaScript ワークスペースをインストールします。

git clone https://github.com/anthropics/commerce-agents.git && cd commerce-agents
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
(cd examples && npm ci)

.env を開き、ANTHROPIC_API_KEY を追加します。Python スクリプトの実行中は、仮想環境を有効にしたままにしてください。

最初のデモを実行する

小売ストアフロントとその API を次のコマンドで起動します。

python scripts/run_demo.py retail

小売 API はポート 8000 で、ストアフロントはポート 3000 で実行されます。ストアフロントの代わりにマーチャントポータルを起動するには、--merchant を追加します。

python scripts/run_demo.py retail --merchant

両方の画面を起動するには --all を使用します。

python scripts/run_demo.py retail --all

利用可能な業種とウェブポートは次のとおりです。

  • 小売: ストアフロント 3000、マーチャントポータル 3100。
  • 旅行: ストアフロント 3001、マーチャントポータル 3101。
  • 通信: ストアフロント 3002、マーチャントポータル 3102。
  • エンターテインメント: ストアフロント 3003、マーチャントポータル 3103。

各例のディレクトリには、推奨プロンプトと、良い回答に含まれるべき内容の説明を記載した README があります。

業種別の例を確認する

小売

ACME の小売例では、商品検索、比較、購入計画、カート、チェックアウトの委譲、メモリを紹介しています。マーチャントポータルには、パフォーマンスダイジェスト、ステージングされた補充、リスティングの修正、SQL ビュー上の分析デリゲートが含まれています。

旅行

ACME Travel では、日付に紐づく在庫と present_itinerary 拡張機能が追加されています。マーチャント側には、稼働率カレンダーと日付範囲に応じた料金変更機能があります。

通信

ACME Mobile では、アカウントコンテキスト、プランマトリクス、サーバーが作成する手数料の開示を紹介しています。マーチャントワークフローでは、規制対象の手数料を保護しながら、プラン構成と価格変更を扱います。

エンターテインメント

ACME Tickets には、時間制限付きの仮押さえ、ウェイトリスト、譲渡、会場マップ、総額手数料の開示が含まれています。マーチャントツールでは、イベントの進行管理、収容枠を生み出す仮押さえの解放、手数料を維持した価格変更を扱います。

Messages API ランタイムを使用する

Messages APIの実装は、ターンループのリファレンス実装です。設定を作成し、バックエンド実装を渡し、ランタイムをショッピングスキルに向け、ターン中に生成されたイベントをストリーミングします。

from pathlib import Path

from shopping_agent import ShoppingAgentConfig
from shopping_agent_runtime import ShoppingAgent

agent = ShoppingAgent(
    backend=your_backend,
    skills_dir=Path("shopping-agent/skills"),
    config=ShoppingAgentConfig(brand_name="Your Store"),
)

async for event in agent.stream_turn(messages, session, state):
    ...

await agent.update_memory(messages, session)

イベントストリームには、text_delta、tool_call、ui、cart_update、turn_completeを含めることができます。マーチャント側では、段階的な書き込みはchange_updateイベントで表されます。

update_memoryによるメモリ抽出は、このランタイムパスに固有です。サンプルホストは、X-Session-Idリクエストヘッダーを通じてセッション識別子を受け取ります。

Agent SDKランタイムを使用する

Agent SDKは、エージェントループを管理しながら、同じプロンプト、スキル、ツールを実行します。ホストはグラウンディング用の読み取りを事前取得し、ターン後に実行される処理はありません。

コンソールから単一のショッピングリクエストを実行します。

python shopping-agent/runtime-agent-sdk/main.py --once "a two-person tent under $250"

マーチャントコンソールを起動します。

python merchant-agent/runtime-agent-sdk/main.py

マーチャントコンソールでは、段階的な変更を適用する前にy/Nによる承認を求めます。

Managed Agentsでデプロイする

Managed Agentsは、同じスキルとコントラクトを使用しながらエージェントをホストします。エージェントはシステムにアクセスするため、ユーザーのMCPサーバーを呼び出します。次のコマンドでデプロイのドライランを実行します。

scripts/deploy_managed_agent.sh shopping-agent/managed-agents/shopping-agent

マーチャントロールには、merchant-agent/managed-agents/配下の同等のパスを使用します。実際のデプロイを行う場合にのみ--liveを追加してください。

独自のコマースエージェントをスキャフォールドする

付属のClaude Codeプラグインを使うと、使用するスタックに合わせたプロジェクトを作成したり、既存のエージェントをレビューしたりできます。リポジトリをローカルにクローンした状態で、プラグインを登録してインストールします。

claude plugin marketplace add anthropics/commerce-agents
claude plugin install commerce-builder@claude-commerce-agents
claude

Claude Code内で、ショッピングアシスタントのスキャフォールドを要求します。

/scaffold-commerce-agent a shopping assistant for our store

このコマンドはテクノロジースタックについて質問し、計画を提示してからプロジェクトを構築します。/add-commerce-flowと/author-commerce-evalsを使って開発を続けます。既存のエージェントを起点にする場合は、/review-commerce-agentを使用します。

エージェントをシステムに接続する

このリポジトリにはMCPコネクターは付属していません。代わりに、両方のエージェントはバックエンドインターフェースを通じて業務システムにアクセスします。各バックエンドメソッドは、現在のセッションのためにホストが保持する認証情報を使い、サーバー側でサービスを呼び出す必要があります。モデルが受け取るのはメソッドの結果だけです。

  1. ロールを選択する: 顧客向けショッピングにはStorefrontBackendを、スタッフ向け業務にはMerchantBackendを実装します。
  2. 読み取り操作をマッピングする: カタログ、ポリシー、分析、在庫、価格、その他のサポート対象の読み取りを、信頼できる情報源のシステムに接続します。
  3. 順序付きフローを維持する: ワークフローに固定された順序が必要な場合は、モデルに依存せず、バックエンドでその順序を強制します。
  4. 書き込みを制御する: ホストの承認画面で承認されるまで、マーチャントによる変更を段階的な状態に保ちます。
  5. チェックアウトを引き渡す: バックエンドからチェックアウトURLを返し、ホストにレンダリングさせます。モデルにURLを決して見せてはいけません。

バックエンドは、サーバー側からコマースプラットフォームや公式コネクターを呼び出すことができます。プロジェクトで言及されている統合先の候補には、分析用データウェアハウス、財務システム、配送ツールなどがあります。Managed AgentsでMCPサーバーを使用する場合も含め、書き込みの前にはプロヴェナンスゲートを置く必要があります。

機能とアイデンティティをカスタマイズする

まずは、役立つ最小限の機能面から始めます。ショッピングのパイロットでは、検索と商品詳細を実装し、スタブメソッドから利用不可の結果を返すことができます。マーチャントのパイロットでは、8つの読み取りメソッドを実装して書き込みを拒否することで、書き込みパスを公開せずにダイジェストとメトリクスを利用できます。

ビジネスに機能がない場合は、対応するenable_*設定をオフにします。これにより、すべてのランタイムパスで関連するツール、プロンプトの内容、グラウンディングルールが削除されます。利用できない機能に依存するフローは、skills/_staged/配下に配置できます。

適切なskills/ディレクトリの下にSKILL.mdを含むディレクトリを追加して、カスタムフローを作成します。ドメイン固有のUIにはPresentationExtensionを使用します。brand_name、assistant_name、brand_voice設定で、どちらのエージェントのアイデンティティもカスタマイズできます。

安全性とデプロイの責任

このプロジェクトは、3つすべてのランタイムパスにおいて、ツール呼び出しの内部でフェンシング、プロヴェナンスゲート、上限、メモリ検証、マーチャント承認を適用します。グラウンディング、分析予算、メモリ抽出はランタイムレベルの機能です。

これらの制御は、デプロイメント固有のセキュリティに代わるものではありません。例には認証がなく、MCPサーバーはループバックにのみバインドされます。本番ホストでは、引き続きID管理、認可、ビジネスルール、コンプライアンス、認証情報の取り扱い、承認ポリシーを管理する必要があります。実際のシステムに接続する前に、安全ガイドを確認してください。

実装を検証する

テストおよびlintツールが必要な場合は、開発要件をインストールします。

pip install -r requirements-dev.txt

フォーマットチェック、lint、テスト、リポジトリチェックを実行します。

ruff check . && ruff format --check . && pytest && python scripts/check.py

デプロイのドライランとWebビルドを含む、完全な検証ワークフローを実行します。

python scripts/verify_all.py

ライブ会話を1件試すには、APIキーを指定して次を実行します。

python scripts/smoke_chat.py --vertical travel

高度なヒント

  • キャッシュの動作を確認する: turn_completeイベント、またはランタイムのモデル呼び出しログからcache_read_input_tokensを読み取ります。2ターン目の値が0の場合、プロンプトのプレフィックスが変更されたことを示します。
  • マーケットプレイスに対応する: 販売者を検索条件として扱い、セッションで特定された事業者にマーチャントエージェントの対象を限定します。
  • アカウント別価格を尊重する: 価格がアカウントや契約によって異なる場合は、セッションのアカウントに適用される価格を返します。
  • チェックアウトを適応させる: チェックアウトを管理していない場合は、カートを無効にするか、見積もり、注文書、またはホスト型チェックアウトページにワークフローを引き継ぎます。
  • プラットフォーム固有のクライアントを使用する: ランタイムはclient=でanthropicクライアントを受け付けます。一方、SDKランタイムはCLI環境からプラットフォーム設定を読み取ります。
  • デプロイの選択肢を確認する: リポジトリでは、GCP Vertex AI、AWS Bedrock、Microsoft Foundry、ゲートウェイへのデプロイについて、デプロイガイドに記載しています。
  • バックエンドのマッピングを確認する: ID管理、認証情報、チェックアウト、注文フロー、商品のオプション、利用できない数値については、バックエンドガイドで説明しています。

結論

Claude Commerce Agentsは、共有プロンプト、スキル、コントラクト、安全制御から、顧客向けショッピングアシスタントと承認ゲート付きマーチャントツールを構築するための実用的なアーキテクチャを提供します。実行可能な業種別実装から始め、プラットフォームに適したランタイムを選択し、適切なバックエンドインターフェースを実装し、未対応の機能を無効にしてから、本番データや書き込み操作に接続する前にシステム全体を検証してください。

このリポジトリはApache License 2.0の下でライセンスされています。リファレンス実装であり、保守されておらず、コントリビューションを受け付けていません。