commerce-architecture

コマースエージェントのアーキテクチャ

参照リポジトリ内のパスは次のとおりです。commerce_common/ は commerce-common/commerce_common/、shopping_agent/ は shopping-agent/core/shopping_agent/、merchant_agent/ は merchant-agent/core/merchant_agent/、ランタイムは shopping-agent/runtime-messages-api/shopping_agent_runtime/ および merchant-agent/runtime-messages-api/merchant_agent_runtime/ です。

1つのループ

• 会話を担当するモデルは1つです。1ターンは ShoppingAgent.stream_turn または MerchantAgent.stream_turn（各 ランタイムの orchestrator.py）です。モデルはキャッシュ済みのプロンプトを読み、ツールを呼び出し（1ラウンド内の呼び出しは 並行実行されます）、テキストとプレゼンテーション呼び出しで終了します。ルーター、分類器、引き継ぎはありません。
• すべての経路におけるすべての呼び出しは、commerce_common/execution.py の BaseToolExecutor を介して、 ロール実行器（shopping_agent/executor.py の ShoppingToolExecutor、 merchant_agent/executor.py の MerchantToolExecutor）を通ります。Messages API ランタイム、Agent SDK のツールセット、 MCP サーバーは同じ execute を呼び出し、この関数が例外を発生させることはありません。 max_tool_iterations ラウンド（commerce_common/config.py）を経過すると、ランタイムはツールを使わないラウンドを強制します。

ルールの配置場所

適用されるルール	配置場所	参照先
1つの呼び出しの引数を入力している間	そのツールの説明	各ロールの tools/registry.py にある build_tools
ほとんどのターンでのカートとチェックアウト、段階的書き込みの契約、プレゼンテーションの文法、ツールの順序、信頼ルール	静的プロンプト	各ロールの prompt.py にある build_static_system
複数ステップの手順が必要な少数のリクエスト	スキル。必要に応じて読み込み	shopping-agent/skills/、merchant-agent/skills/

コアとなる一連の処理でほとんどの会話に必要なルールは、より下位のレイヤーに移します。この表がレイヤー構造を示す唯一の説明です。

スキル

• スキルは SKILL.md を格納したディレクトリです。フロントマターには name と description があり、その後に本文が続きます （commerce_common/skills.py の parse_skill_md）。説明ではリクエストの種類を示し、発話例は含めません。
• 静的プロンプトにはインデックスのみを含めます（SkillRegistry.index_block。名前順にソート）。load_skill は 1つの本文を返します（commerce_common/execution.py の _load_skill）。Agent SDK では、 ensure_project_skills が同じディレクトリを .claude/skills/ にリンクし、 SKILL_TOOL_ADAPTER がモデルに SDK の Skill ツールを指定します （commerce_common/agent_sdk.py）。ホスト型マニフェストでは、agent.yaml の skills[] にディレクトリを記載します。

バックエンドインターフェース

デプロイメントでは、ロールごとに抽象クラスを1つ実装します。システムにアクセスするのは、そのクラスだけです。

• StorefrontBackend (shopping_agent/backend.py)：抽象メソッドは11個で、カタログ（2）、カート（4）、設定（1）、注文（2）、ポリシー（1）、フルフィルメント（1）です。get_account_context、get_disclosure、checkout_handoff にはデフォルト実装があります。注文を確定したり、資金を移動したりするメソッドはありません。checkout_handoff は決済が行われる場所（ホスト型のチェックアウトURL、または販売者ごとに1つのURL）を指定し、ホスト側でそれを表示します。
• MerchantBackend (merchant_agent/backend.py)：抽象メソッドは16個で、読み取り（8個：パフォーマンス3、カタログ2、在庫と注文状況2、価格設定1）と変更ライフサイクル（8個：5つの stage_*、get_pending_changes、apply_change、discard_change）です。execute_analysis_query、get_analysis_schema、get_merchant_context にはデフォルト実装があります。
• サイズ、色、ティア別に販売する商品またはリスティングは、options を持つファミリーレコードです。各バリアントは option_values と variant_of を持つレコードです。カートへの追加、価格設定や再入荷の書き込みにはバリアントのIDを使用し、ゲートではファミリーレコードを使用します。docs/backends.md には、一般的なカタログモデルとの対応関係と、プラットフォームで提供できない数値の返却方法が記載されています。
• 適格性、価格設定、在庫、数量のルールはバックエンドで適用されます。ゲートでは出所と上限を確認します（commerce-trust-safety）。バックエンドから返されるすべてのデータは、モデルが読み取る前にフェンスで保護されます。
• まだ接続されていないシステムは、失敗するメソッドとして表現します（merchantメソッドは merchant_agent/changes.py の ChangeNotApplicable を送出します）。ツールは登録されたままなので、プロンプトのバイト列は変わりません。ビジネスでそもそも提供していないシステムは対象外にします。ロールの設定にある enable_* スイッチをオフにすると、そのシステムのツール（absent_tools()）、プロンプト行、3つすべての経路でのグラウンディングルールが削除され、エグゼキューターもそれらの名前を拒否します。それを必要とするスキルは skills/_staged/ に保留され、そのデプロイメントではバイト列が固定されます。NotOffered (shopping_agent/backend.py) は、システム自体は稼働しているものの、ストアが取り扱わない特定の商品または販売者を示す、より限定的なシグナルです。
• ShoppingAgent / MerchantAgent の executor_class=、SDKツールセット、およびMCPサーバーの build_server には、デプロイメント固有の domain_error マッピングや結果の文言を定義するため、ロールのエグゼキューターのサブクラスを指定します。

委譲先

2回目のモデル呼び出しは、DelegateExtension (commerce_common/delegation.py) の1つの形式を取ります。委譲先が受け取るのは概要と DelegationContext 内のハンドルだけで、会話やエグゼキューターは受け取りません。返すのは result_model に対して検証された単一の結果です。書き込み、表示、別の委譲先の呼び出しはできません。commerce_common/execution.py の _run_delegate は、1ターンあたりの呼び出し回数を max_delegate_calls_per_turn で制限します。MerchantAgent は extra_delegates を受け取り、組み込みのインスタンスは run_analysis です（commerce-merchant-operations）。ShoppingAgent は委譲先を登録しません。

モデルのフィールド

model はターンループを実行し、memory_model はターン後の抽出を実行します（commerce_common/config.py の BaseAgentConfig）。analysis_model は委譲先を実行し、None の場合は model を使用します（merchant_agent/config.py の MerchantAgentConfig）。SDKランタイムは config.model をオプションにコピーし、マニフェストでは model: を設定します。値は独自の評価に基づいて選択してください。

禁止事項

• リクエストごとに tools[] や静的プロンプトを変更しないでください（commerce-prompt-caching）。
• 多くのターンで適用するルールをスキルに入れたり、1つのツールだけに関するルールをプロンプトに入れたりしないでください。
• 上限や権限をプロンプトテキストだけで適用しないでください。エグゼキューターまたはバックエンドで適用してください。
• モデルに価格、数値、条件を作成させないでください。コンポーネントはサーバーレコードから結合します（commerce-ui-tools）。
• ドメインツールをコアパッケージに追加しないでください。業種固有の実装では PresentationExtension を通じてUIを追加し、それ以外は独自のコード内に保持します。