Commerce agent architecture

Paths are in the reference repo: commerce_common/ is commerce-common/commerce_common/, shopping_agent/ is shopping-agent/core/shopping_agent/, merchant_agent/ is merchant-agent/core/merchant_agent/, and the runtimes are shopping-agent/runtime-messages-api/shopping_agent_runtime/ and merchant-agent/runtime-messages-api/merchant_agent_runtime/.

One loop

• One model owns the conversation. A turn is ShoppingAgent.stream_turn or MerchantAgent.stream_turn (each runtime's orchestrator.py): the model reads the cached prompt, calls tools (one round's calls run concurrently), and ends with text plus presentation calls. There is no router, classifier, or hand-off.
• Every call on every path runs through the role executor (ShoppingToolExecutor in shopping_agent/executor.py, MerchantToolExecutor in merchant_agent/executor.py) over BaseToolExecutor in commerce_common/execution.py. The Messages API runtime, the Agent SDK toolset, and the MCP server call the same execute, which never raises; after max_tool_iterations rounds (commerce_common/config.py) the runtime forces a round without tools.

Where a rule lives