Anthropic’s `commerce-agents`: the blueprint for AI commerce that stays under control
A deep look at how Anthropic split shopping and merchant agents, enforced safety in code, and made long-running commerce sessions practical with caching, compaction, and staged writes.
- Anthropic treats commerce agents as infrastructure, not a demo, so the core problem is bounded authority rather than raw autonomy.
- The repo splits shopping and merchant roles on purpose, which keeps customer intent and internal operations under different levels of control.
- Its most interesting engineering move is not the model call but the runtime discipline around compaction, caching, fencing, and human-approved writes.
- The project argues that credible commerce automation comes from code-enforced guardrails, not prompt-only persuasion.
The sharpest thing about anthropics/commerce-agents is what it refuses to be. It is not a chatbot that happens to shop. It is a control system for commerce, built around the uncomfortable truth that buying, pricing, inventory, and support all have different risk profiles.
That distinction matters. In commerce, an agent that can act is useful. An agent that can act without drifting, leaking, or overreaching is the product.
This is a reference implementation; it is not maintained and does not accept contributions.
The real product is control
Anthropic’s framing is blunt: the blueprint ships the harnesses, patterns, and guardrails an engineering team needs to get a commerce agent running. That means the product is not a single assistant. It is the scaffolding around the assistant.
That scaffolding is what makes the repo interesting. It assumes the hard part of commerce is not language generation. It is deciding what the model can see, what it can remember, and which actions must pause for approval.
Two agents, two jobs, one shared engine
| Approach | Who owns checkout or action | Agent style | Safety model | Best fit |
|---|---|---|---|---|
| Anthropic `commerce-agents` | Merchant-owned; writes can be staged and approved | One shared runtime with shopping and merchant roles | Code-enforced fencing, memory filters, approval gates | Retailers who want control without rebuilding the stack |
| Gateway-style commerce | Platform owns the transaction path | Consumer-facing buyer assistant | Policy lives near the platform | Fast buyer flows inside a controlled marketplace |
| Orchestration frameworks | Developer owns the workflow graph | Many agents or nodes | Safety depends on how the graph is built | Teams that want maximum flexibility |
| Native commerce assistants | Platform-owned merchant helper | Turnkey assistant inside a single ecosystem | Vendor policies and product constraints | Businesses already committed to one platform |
The core design choice is the split between shopping-agent and merchant-agent. Shopping handles product discovery, cart management, and customer intent. Merchant handles internal operations like inventory, pricing, and campaign drafting.
That separation is more than neat packaging. It is a boundary of authority. The customer-facing agent can help. The merchant-facing agent can prepare. Neither should behave like an unbounded operator.
Inside the turn loop
The turn loop in turn.py is where long commerce sessions stay readable. Once history gets too large, older tool results are compacted into a cleared marker instead of being left to flood the context window.
# Conceptual shape of the compaction pattern
latest_user_text = extract_latest_user_text(turn)
latest_exchange = extract_latest_exchange(turn)
if history_is_too_large:
tool_result.content = CLEARED_RESULT
request = build_request(
latest_user_text=latest_user_text,
latest_exchange=latest_exchange,
compacted_history=history,
)
The point is not just to save tokens. It is to preserve structure. The model keeps the current intent, the latest exchange, and a usable conversation skeleton, while stale payload gets trimmed away.
Why the safety layer is code, not just prompt text
The fencing layer in fencing.py treats untrusted input as hostile by default. It wraps data in labels, strips invisible Unicode, and removes forged turn markers that could try to masquerade as assistant instructions.
That is the right posture for commerce. If an attacker can smuggle instructions into product text, customer notes, or tool output, prompt-only defenses are too soft. The repo assumes adversarial input is normal and builds accordingly.
Memory that remembers, but not too much
Memory is handled as a post-turn extraction pass in memory.py. The system classifies durable facts as preferences, constraints, or context, then runs them through a filter that blocks sensitive data such as card numbers or IBANs.
That tradeoff is the whole game. Agents are more useful when they remember. They are more credible when they do not remember the wrong things.
The hidden efficiency trick
The most elegant move in the repo is prompt_assembly.py. Anthropic separates the static system instructions from dynamic state, then places a cache breakpoint so the expensive part of the prompt can be reused across turns.
That turns prompt caching from an API detail into an architectural principle. Commerce sessions are noisy, but not everything in them is volatile. The instructions stay put. The cart changes. The clock moves. The request gets rebuilt only where it should.
# Structural idea, not exact repo code
static_block = assemble_static_instructions()
dynamic_block = assemble_dynamic_state(cart, clock, latest_user_input)
request = [static_block, CACHE_BREAKPOINT, dynamic_block]
response = client.send(request)
How this compares to the rest of the market
Compared with gateway-style assistants, Anthropic’s blueprint keeps the merchant in control of the workflow. Compared with orchestration frameworks, it is simpler on purpose. There is one main loop, a set of reusable skills, and guardrails enforced in code.
That makes it less dramatic than a sprawling agent graph, but more believable for commerce. The architecture is not chasing maximum autonomy. It is chasing permissioned action.
What this repo is really teaching
The lesson here is not that commerce agents are ready to run free. It is that they become credible only when their powers are narrowed, staged, and observable.
Anthropic’s blueprint is a vote for layered control. Let the model help. Let the code decide. In commerce, that is the difference between a demo and infrastructure.





