commerce-merchant-operations

Merchant agent

参照リポジトリ内のパス：merchant_agent/ は merchant-agent/core/merchant_agent/、merchant_agent_runtime/ は merchant-agent/runtime-messages-api/merchant_agent_runtime/、merchant_agent_sdk/ は merchant-agent/runtime-agent-sdk/merchant_agent_sdk/、commerce_common/ は commerce-common/commerce_common/ です。

機能

merchant agent は、1 つの MerchantBackend（merchant_agent/backend.py）を介して、バックオフィスでオペレーターと連携します。 5 つのフローは、merchant-agent/skills/ にあるスキル、performance-insights、catalog-listings、inventory-operations、 pricing-promotions、marketing-campaigns です。commerce_common/ の仕組みは共有されていますが、プロンプト、ツール、ゲート、 エグゼキューターは独自のもので、すべてのツール結果は MERCHANT_FENCE（merchant_agent/fencing.py）内に返されます。

ステージ済み変更の契約

1. すべての書き込みは stage_* ツール（stage_listing_update、stage_price_update、stage_inventory_action、stage_promotion、 stage_campaign）を使用します。各ツールはステージ済みレコードと注記を返し、change_update イベントを発行します。また、 stage_shows_preview が有効な場合（デフォルトでは有効。merchant_agent/config.py）、ランナーが使用する present_change_preview を通じて change_preview カードを発行します（MerchantToolExecutor、merchant_agent/executor.py）。 MCP サーバーでは、エグゼキューターのイベントがオペレーターに届かないため、この機能を無効にします。そのため、ホスト型エージェントは present_change_preview を呼び出します。このツールは以前の変更も再表示します。apply_change がプラットフォームに書き込むまで、 ライブ状態は変更されません。
2. ステージングで受け付けるのは、このセッション中にツールが返したリスティング ID とキャンペーン ID のみです。コンテンツを編集する場合は、 get_listing による読み取りも必要です。apply_change と discard_change が受け付けるのは、ステージングまたは get_pending_changes が返した変更 ID のみです（merchant_agent/gates.py）。プレビューカードを表示しても、承認済みにはなりません。
3. merchant_agent/changes.py の check_guardrails は、変更のステージング時（ChangeLedger.stage またはバックエンドの同等処理）と、 check_apply_change（merchant_agent/gates.py）内での再確認時に実行されます。再確認には、適用時点で有効な設定が使われます。 上限は merchant_agent/config.py の max_items_per_change、max_price_delta_pct、max_promotion_discount_pct、 max_restock_quantity、max_campaign_budget、max_listing_field_chars です。デフォルト値はデモ用です。
4. protected_fields はステージングできません。price_bearing_fields は価格上限の判定対象となるフィールドです。 listing_update_blocked_fields は、自由形式のリスティング更新に含めることができません。別の名称で価格を設定するドメイン （1 泊料金、月額料金、ティア価格など）では、これらのタプルを置き換えずに項目を追加します。
5. require_host_approval のデフォルトは True です。apply_change が成功するのは、MerchantSessionState.approved_change_ids に含まれる ID のみです。この値を書き込めるのはホストコードだけです。リポジトリ内の 3 つの承認方法は、ポータルの /changes/{change_id}/apply ルート （examples/demo_common/merchant.py）、MerchantToolset.host_approve（merchant_agent_sdk/merchant_tools.py。merchant-agent/runtime-agent-sdk/main.py が 変更ごとにプロンプトで確認）、およびホスト型マニフェストの apply_change に対する always_ask です。最後の方法では、MCP サーバーの設定で require_host_approval=False が設定されています（default_config がそうなっています）。渡す設定でも同様に設定しないと、すべての適用が保留されます。 チャットに承認を入力しても、何も設定されません。
6. require_host_approval と approval_surface は静的プロンプトと拒否メッセージに反映されるため、デプロイごとに設定します。どちらかを変更した場合は再デプロイが必要です（commerce-prompt-caching）。approval_surface には実際の承認方法を指定してください。
7. システムがサポートしていない変更種別では、ChangeNotApplicable（merchant_agent/changes.py）が発生し、エグゼキューターがそれを中継します。ツールの登録は解除されません。適用済みおよび破棄済みの変更も監査証跡として引き続き参照でき、それぞれに MerchantSessionContext.operator のオペレーターが記録されます。本番環境のホストでは、認証情報をもとにこの値を設定します。

グラウンディングと後続処理

• パフォーマンスに関する質問では get_business_snapshot が必須となり、変更リクエストに適用を示すフレーズが含まれていて、今のセッションで変更が何もステージングされていない場合は get_pending_changes が必須となります（merchant_agent/grounding.py の GROUNDING_RULES、merchant_agent/config.py の語彙とフラグ。これらは追加のみで、置き換えられることはありません）。
• change_requested に一致したターンが、stage_* の試行も present_suggestions による終了処理もなく、通常のテキストだけで終わった場合は、ユーザーメッセージとして STAGING_FOLLOWTHROUGH_REMINDER が一度送られます（merchant_agent/gates.py。merchant_agent_runtime/orchestrator.py と merchant_agent_sdk/agent.py で適用）。このリマインダーのテキストはメモリ抽出から除外されます。
• present_metrics は、スナップショット、クエリされた系列、キャンペーン、または記録された分析のいずれかに各項目を照合し、それ以外は注記を添えて除外します（merchant_agent/enrichment.py の resolve_metrics）。そのため、カードにモデルが生成した数値が含まれることはありません。

分析デリゲート

• デフォルトでオフの enable_analysis を有効にすると、merchant_agent_runtime/analysis.py の build_analysis_delegate が構築する DelegateExtension である run_analysis が登録されます。デリゲートのツールは、送信ツール、進捗確認ツール、ANALYSIS_READ_TOOLS（merchant_agent/analysis.py）、およびバックエンドが MerchantBackend.execute_analysis_query を実装している場合のクエリツールです（その場合、analysis_sql_only によって系列ごとの読み取りはオフになります）。デリゲートはステージングツールを持たず、その結果は seen_analyses に記録され、独立したメトリクスカードとして表示されます。
• バックエンドで実行される前に、check_analysis_sql はコメントを含まない単一の SELECT 以外をすべて拒否します。読み取り専用ロールとマーチャントのスコープ設定はバックエンドが担います。analysis_query_timeout_s と cap_analysis_table（max_analysis_rows、max_analysis_table_chars）が各クエリを制限し、analysis_timeout_s、max_analysis_iterations、max_delegate_calls_per_turn が実行を制限します。
• analysis_use_code_execution はホスト型サンドボックスをマウントし、Anthropic API でのみ動作します（Anthropic 上でホストされる Foundry デプロイメントを含む）。クエリメソッドはどこでも動作します（docs/deployment.md）。Agent SDK では、同じ契約を、ツールが読み取り専用ツールに限定されたサブエージェントとして実装します（merchant_agent_sdk/agent.py の build_analysis_agent）。
• スケジュールされたダイジェストは、同じエージェントによるヘッドレスの1ターンです（merchant-agent/managed-agents/scheduled-digest/run_morning_digest.py）。

メモリとコンポーネント

• メモリは merchant_id をキーにします（merchant_agent/executor.py の memory_subject）。merchant_agent/memory.py の抽出プロンプトでは、オペレーターが業務の運営について述べた内容のみを許可し、出品情報、レビュー、購入者のメッセージ、メトリクスに由来する情報と、特定可能な顧客に関する情報は除外します。書き込みフィルター、保持期間、削除、消去、enable_memory は共通ルールです（commerce-trust-safety）。
• 組み込みコンポーネント（merchant_agent/enrichment.py）は present_metrics、present_digest、present_change_preview、present_suggestions です。ホストの承認が必要な場合、プロンプトでは、どのチップも承認や適用を行わないと説明します。各業種では、垂直分野固有のコンポーネント（例では present_occupancy_calendar、present_plan_mix、present_event_pacing）を拡張機能として追加します（commerce-ui-tools）。

マーケットプレイス

• 多数の販売者のコンテンツには、共通のフェンスが適用されます。販売者ごとのラベルはなく、フェンスを回避できる販売者もいません。ショッピングのデプロイメントでは、販売者は検索軸（SearchFilters.attributes）であり、コンポーネントに表示されます。また、プラットフォームと販売者の規約が異なる場合、search_policies の結果には、どちらの規約なのかが示されます。
• 出所情報と上限はセッションごとに設定されるため、セッションでは、そのセッション内のツールが返した出品情報に対してのみ変更をステージングできます。
• 購入者と販売者のメッセージは、フェンスで区切られた内容としてモデルに渡されます。変更が承認されたと書かれたメッセージがあっても、承認済みの印は付きません。
• メモリの対象は、merchant_id をキーとするオペレーター自身のビジネスです。買い物客の情報は、その買い物客をキーにします。