How simplifyai4u/commerce-agents-claude works
The repository provides two commerce agents: customer-facing shopping and staff-facing merchant operations. A user turn enters through one of three runtimes—Messages API, Agent SDK, or Managed Agents—and uses shared prompts, skills, tools, and safety controls against a deployment-provided commerce backend. Shopping supports discovery through cart and checkout-summary staging; merchant work spans business analysis through staged changes and human approval. Memory and presentation are shared runtime concerns. The README documents the main capability flows; sampled orchestrators and adapters support the runtime wiring shown here, but several implementations were not sampled.
Main entry points: merchant_agent_runtime/orchestrator.py Merchant turn loop · shopping_agent_runtime/orchestrator.py Shopping turn loop · merchant_agent/executor.py Merchant executor · shopping_agent/executor.py Shopping executor
Components 29
Shared runtime
- Durable memory
commerce-common/commerce_common/memory.py - Grounding
commerce-common/commerce_common/grounding.py - Presentation events
commerce-common/commerce_common/presentation.py
Shopping agent
- Shopping skills
shopping-agent/skills - Shopping prompt
shopping-agent/core/shopping_agent/prompt.py - Shopping tool contracts
shopping-agent/core/shopping_agent/tools/registry.py - Shopping executor
shopping-agent/core/shopping_agent/executor.py - Storefront backend
shopping-agent/core/shopping_agent/backend.py - Shopping guardrails
shopping-agent/core/shopping_agent/gates.py
Merchant agent
- Merchant skills
merchant-agent/skills - Merchant prompt
merchant-agent/core/merchant_agent/prompt.py - Merchant tool contracts
merchant-agent/core/merchant_agent/tools/registry.py - Merchant executor
merchant-agent/core/merchant_agent/executor.py - Merchant backend
merchant-agent/core/merchant_agent/backend.py - Staged changes
merchant-agent/core/merchant_agent/changes.py - Merchant guardrails
merchant-agent/core/merchant_agent/gates.py - Analysis delegate
merchant-agent/runtime-messages-api/merchant_agent_runtime/analysis.py
Runtime adapters
- Shopping turn loop
shopping-agent/runtime-messages-api/shopping_agent_runtime/orchestrator.py - Shopping SDK adapter
shopping-agent/runtime-agent-sdk/shopping_agent_sdk/agent.py - Merchant turn loop
merchant-agent/runtime-messages-api/merchant_agent_runtime/orchestrator.py - Merchant SDK adapter
merchant-agent/runtime-agent-sdk/merchant_agent_sdk/agent.py
Managed interfaces
- Storefront MCP server
shopping-agent/managed-agents/storefront-mcp-server/storefront_mcp_server.py - Merchant MCP server
merchant-agent/managed-agents/merchant-mcp-server/merchant_mcp_server.py - Scheduled digest
merchant-agent/managed-agents/scheduled-digest/run_morning_digest.py
Other components
- Customer
- Store operator
- Claude Messages API
- Claude Agent SDK
- Host approval surface
Connections 35
- Customer → Shopping turn loop: sends turn
- Shopping turn loop → Claude Messages API: requests completion
- Shopping turn loop → Shopping prompt: builds context
- Shopping turn loop → Shopping executor: dispatches tools
- Shopping turn loop → Storefront backend: prefetches reads
- Shopping turn loop → Durable memory: reads and extracts
- Shopping turn loop → Presentation events: renders events
- Shopping prompt → Shopping skills: indexes skills
- Shopping executor → Shopping tool contracts: uses contracts
- Shopping executor → Storefront backend: calls commerce
- Shopping executor → Shopping guardrails: enforces gates
- Shopping executor → Durable memory: serves memory tools
- Shopping SDK adapter → Claude Agent SDK: runs turns
- Shopping SDK adapter → Storefront MCP server: connects tools
- Storefront MCP server → Shopping executor: dispatches calls
- Store operator → Merchant turn loop: sends turn
- Merchant turn loop → Claude Messages API: requests completion
- Merchant turn loop → Merchant prompt: builds context
- Merchant turn loop → Merchant executor: dispatches tools
- Merchant turn loop → Merchant backend: prefetches context
- Merchant turn loop → Durable memory: reads and extracts
- Merchant turn loop → Presentation events: renders events
- Merchant prompt → Merchant skills: indexes skills
- Merchant executor → Merchant tool contracts: uses contracts
- Merchant executor → Merchant backend: calls commerce
- Merchant executor → Merchant guardrails: enforces gates
- Merchant executor → Staged changes: stages changes
- Merchant executor → Durable memory: serves memory tools
- Merchant turn loop → Analysis delegate: delegates analysis
- Merchant SDK adapter → Claude Agent SDK: runs turns
- Merchant SDK adapter → Merchant MCP server: connects tools
- Merchant MCP server → Merchant executor: dispatches calls
- Staged changes → Host approval surface: requests approval
- Host approval surface → Staged changes: approves staged
- Scheduled digest → Merchant backend: reads merchant data