メインコンテンツまでスキップ
中級

コマースエージェントのブループリント(Anthropic リファレンス)

What you'll learn
  • 2 エージェント構成(ショッピングと加盟店)と、Anthropic がインテントルーターやドメイン別サブエージェントを採用しなかった理由を理解する
  • 書き込みのステージングというガードレールを学ぶ:モデルのツール呼び出しが資金を動かしたりストアを変更したりすることは一切なく、すべての書き込みは人間が承認するサーフェスで終わる
  • 3 つの実行パス(Messages API、Agent SDK、Managed Agents)と、同じコアのコードがその 3 つすべてにどう組み込まれるかを確認する
  • 実際の業務システムに触れるあらゆるエージェントに応用できる 3 つのパターンを真似る:サーバー発行の ID、フェンスで囲まれたサードパーティのテキスト、プロンプトとスキルの分離

2026 年 9 月 2 日、Anthropic は anthropics/commerce-agents を公開しました。Claude 上でショッピングエージェントと加盟店エージェントを構築するための、Apache 2.0 ライセンスのリファレンスブループリントです。動作する 2 つのエージェント、4 つの業種別の例(小売、旅行、通信、エンターテインメント)に加え、決定的に重要なものとして、プロンプトではなくコードで実装されたガードレールのパターン一式が含まれています。Anthropic は、このリポジトリはリファレンス実装であり、製品としてメンテナンスするつもりはなく、外部からのコントリビューションも受け付けないと明言しています。

注目すべきは、ショッピングボットが作れるようになったことではありません。注目すべきは構造です。実際の業務システムに触れるエージェントをどう構成すべきかについて、きわめて主張のはっきりした考え方が示されています。以下の内容はすべて、在庫、顧客レコード、銀行業務、運用ツールなど、実際のバックエンドに書き込む必要のあるあらゆるエージェントに応用できます。

分割:1 つではなく 2 つのエージェント​

Anthropic は、ショッピングエージェント 1 つ(顧客向け)と加盟店エージェント 1 つ(スタッフ向け)を提供します。それぞれが独自のバックエンドインターフェース(StorefrontBackend と MerchantBackend)と、独自のスキル群を持ちます。意図的に、次のものは作りませんでした。

  • サブエージェントに振り分けるインテントルーター
  • ドメイン別のサブエージェント(「カートエージェント」+「返品エージェント」+「検索エージェント」)
  • 消費者向けとスタッフ向けの両方の作業を行う、単一の巨大なエージェント

代わりに採ったのは、対象ユーザーごとに 1 つの統合エージェントを、スキルとツールを備えた標準的なエージェントループで動かす構成です。効果的なコマースエージェントの構造の記事にあるガイダンスは次のとおりです。「エージェントがほとんどのターンで必要とするものは、一般にシステムプロンプトに入れる」。したがってショッピングエージェントでは、カタログ検索はほぼ毎ターン使われるのでプロンプトに置かれます。「それ以外はスキルに入れる」。カスタマーケア、パーソナライゼーション、返品はスキルです。

これは強い主張です。インテントルーターやドメイン別サブエージェントは、多くのチュートリアルでデフォルトのアーキテクチャとされています。Anthropic は、対象ユーザーが 1 種類で、セッションが密接に結びついているなら、それはやめたほうがよいと言っているのです。

要となるガードレール:ステージングされた書き込み​

Pro tip
  • ブループリントで最も重要な一文:「モデルのツール呼び出しは、資金を動かしたり、事業を変更したりしない。」すべての変更は、サーバーが制御する承認ステップを通ります。このリポジトリから 1 つだけ持ち帰るなら、これを持ち帰ってください。

ブループリントは安全性をプロンプトではなくコードで強制します。その仕組みは 3 つの部分からなります。

Guided walkthrough1 of 3
  1. サーバーは、モデルに渡したすべての商品 ID、SKU、キャンペーン ID、価格 ID をセッションごとに記録します。書き込みとレンダリングは、その記録にある ID のみを受け付けます。モデルが SKU を幻覚で作り出しても、ハーネスが拒否します。プロンプトエンジニアリングは不要です。

ブループリントは、ほかにも 2 つの古典的な落とし穴に対処しています。

  • 規制対象のコンテンツ: 手数料、開示事項、消費者に表示される価格については、モデルはどの商品を開示するかを選び、文言はサーバーが提供する承認済みの文面から来ます。モデルが開示文を書くことはありません。
  • サードパーティのテキストのサニタイズ: ユーザー生成コンテンツ(レビュー、販売者のメモ、メッセージ)は、モデルに届く前に「フェンスで囲まれたテキスト」のマーカーで包まれるため、プロンプトに指示を紛れ込ませることはできません。

決済:明示的にスコープ外​

ブループリントは注文を確定せず、カードに課金しません。チェックアウトは、ホストアプリケーションが完了できるようにレンダリングされます。Anthropic の言葉では、これは「決済処理、不正対策ルール、認証情報をエージェントの外に置く」ためです。発表には Visa、Mastercard、Accenture がパートナーとして名を連ねていますが、決済ステップは既存のチェックアウトか、エージェント向け決済プロバイダーの中にあり、モデルのツールの範囲には決して入りません。

これもまた主張のはっきりした一線です。一撃でお金を失いかねないなら、モデルは触れない。

3 つの実行パス、1 つのコア​

リポジトリはすべてのエージェントを、コアパッケージ(型、バックエンドインターフェース、プロンプト、ツールの契約)と、コアをさまざまな提供サーフェスに適合させる個別のランタイムパッケージに分割しています。

Messages API — リファレンスのループ

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):
# yields: text_delta | tool_call | ui | cart_update | turn_complete
...
await agent.update_memory(messages, session)

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
# prints staged changes and waits for y/n approval

Managed Agents(ベータ)— ホスト型

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

# The manifest declares tools + a storefront MCP server;
# Anthropic hosts the loop.

同じ core/ のコードが 3 つすべての下で動きます。これこそが実際に持ち運べるパターンです。エージェントの契約(ツール、プロンプト、バックエンドインターフェース)を、提供側のハーネスから切り離しておく。 半年後に Messages API から Managed Agents に乗り換えても、変わるのはランタイムパッケージだけです。

メモリ:コンテキストの中には置かない​

長期メモリ(好み、過去の注文、サービスメモ)は、モデルのコンテキストではなく、既存のデータベースに永続化されます。抽出は会話の終了後に非同期で行われるため、メモリの更新のためにホットパスでレイテンシを払う必要はありません。次のターンでは、ランタイムが関連するメモリをシステムプロンプトに流し込みます。

コマースを作らない人でも、これは心に留めておく価値があります。毎ターン会話の要約をコンテキストに詰め込むのは、よくあるパフォーマンス上の失敗です。ブループリントの構造、つまり書き込みは非同期、読み込みはターンの開始時、のほうが低コストです。

4 つの業種(とそれらが異なる理由)​

examples/ には 4 つの業種のエンドツーエンドのデモが含まれており、それぞれにそのまま真似できる構造上の特徴があります。

  • 小売 — 基本のケース。標準的なカタログ、カート、チェックアウト。
  • 旅行 — 日付に紐づく在庫(航空券の座席は期限が切れる)、複数区間を比較する旅程の提示。
  • 通信 — アカウントのコンテキスト(「現在のプランは X です」)、プランの比較表、規制対象の手数料の開示。
  • エンターテインメント — チケットの時間制ホールド、キャンセル待ち、会場の座席マップ。

プロダクトがコマースではなくても、これらの特徴(期限のある在庫、規制対象の開示、時間制のホールド)のいずれかを持つなら、自分のエージェントを設計する前に、該当する業種を読んでおく価値があります。

午後のうちに動かす​

クローンしてインストールし、1 つの業種を実行する

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  # add ANTHROPIC_API_KEY

(cd examples && npm ci)

python scripts/run_demo.py retail
# API on :8000, storefront on :3000

リポジトリは ruff check . && ruff format --check . && pytest && python scripts/check.py で検証され、包括的なチェックには python scripts/verify_all.py が用意されています。

知っておきたい用語​

Enter キーまたはスペースキーでカードを裏返します。左右の矢印キーでカードを移動できます。用語を表示しました。
1 / 5

理解度チェック​

Check yourself

0/4
  1. ブループリントが、「確認なしに注文を確定しないこと」のようなプロンプト上の指示に頼らず、すべての書き込みをステージングするのはなぜですか?
  2. 加盟店エージェントのアーキテクチャは、多くのチュートリアルが教える一般的な「ルーター + サブエージェント」のパターンとどう違いますか?
  3. ブループリントでは、顧客の長期メモリはどこに置かれますか?
  4. ブループリントは「注文を確定せず、カードに課金しない」とされています。それはなぜですか?

出典と参考文献​

次に読む​