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.

9 min read • View on GitHub • More from anthropics

A wide black-ink editorial scene of a commerce control room split into two halves. One side shows a customer-facing shopping assistant at a glass counter with product cards and a cart, while the other side shows a merchant desk with inventory sheets, pricing ledgers, and an approval gate. A shared mechanical engine runs underneath both halves, implying one runtime with different authority levels.
Anthropic’s real bet is not a shopping chatbot. It is a commerce runtime where the code decides who may act, and how far.
Key Takeaways

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.

Anthropic, Project Maintainer · GitHub - anthropics/commerce-agents README

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

ApproachWho owns checkout or actionAgent styleSafety modelBest fit
Anthropic `commerce-agents`Merchant-owned; writes can be staged and approvedOne shared runtime with shopping and merchant rolesCode-enforced fencing, memory filters, approval gatesRetailers who want control without rebuilding the stack
Gateway-style commercePlatform owns the transaction pathConsumer-facing buyer assistantPolicy lives near the platformFast buyer flows inside a controlled marketplace
Orchestration frameworksDeveloper owns the workflow graphMany agents or nodesSafety depends on how the graph is builtTeams that want maximum flexibility
Native commerce assistantsPlatform-owned merchant helperTurnkey assistant inside a single ecosystemVendor policies and product constraintsBusinesses 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.

The repo’s split-brain architecture keeps customer help and merchant action in separate lanes, while reusing the same engine underneath.

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.

A close-up editorial illustration of a prompt assembly pipeline. A thick cached instruction block sits on the left, separated by a visible breakpoint from a thinner dynamic block on the right. Cart state, a small clock, and a latest-user-input card flow into the dynamic side, which then joins a single Claude request output. The image explains that stable instructions are reused while volatile commerce state is rebuilt each turn.
The hidden efficiency trick is structural: keep instructions cached, rebuild only the changing commerce state.

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.