In partnership with
Where would you put the human checkpoint in an AI shopping agent?
If you picked D, this edition is for you. Anthropic open-sourced its commerce-agents blueprint last week, and it is built around that checkpoint.
The merchant agent can stage price and listing changes all day, but it cannot push them live until a human approves, and there's no prompt you can type to get around that.
So today we run the whole thing on localhost and then try to break it.
But first, some catchup:
DevTools of the Week
htmx lets you drive AJAX, swaps and other browser behaviour straight from HTML attributes, no framework required. Version 4 moves the internals to fetch() and keeps the attribute API almost identical to 2.x.
Polars is a fast DataFrame library for Python and Rust, built on Arrow and a lazy query engine. In 2.0, LazyFrame collect() runs on the streaming engine by default, so large queries use far less memory.
Modes are declarative agents you define in config, an instruction set, a model and MCP tools, callable from the Portal CLI or API. One handy use is routing cheap grunt work like bulk file reads out of your main coding agent to a smaller model.
What you're shipping
The commerce-agents repo ships 2 agents, a shopping agent for customers and a merchant agent for the back office, and the demo script boots either or both.
We're going with the merchant side because that's where the guardrails are.
Step 1: get it running
You'll need Python 3.11+ and Node 22.
Plain retail would give you the customer storefront; --merchant swaps that for the portal, and --all runs both.
Don't skip the npm ci line, the portal won't load without it.
This won't run identically on every machine, and that's normal. Common deviations:
If ports 3100 or 8000 are taken, the script moves to the next free port and tells you in the terminal, so use whatever it prints.
If pip won't build a dependency on your Python (the repo wants 3.11+), pin to 3.12 with brew install [email protected] and rebuild the venv with that binary.
If you get a 401 from the Anthropic API, it's almost always a stale key in your shell environment overriding .env, so run echo $ANTHROPIC_API_KEY first and unset it if anything prints.
Checkpoint: on whichever port, open the merchant portal in your browser and confirm you can chat with the agent and it returns real catalog data.
Step 2: try to reference a product that doesn't exist
Ask it to change the price of a product using an id it hasn't shown you, made up on the spot.
Input:
change the price of "fake-nonexistent-sku" to a different amount
Expected reply: a refusal. It tells you there's no listing with that id in the catalog, so there's nothing to reprice, and asks for a real product name or id plus the price you want.
Output:
Why: the agent only acts on listings it pulled from the catalog.
An id it never found has nothing behind it, and the backend checks that before any staged write, regardless of how the request is worded.
docs/safety.md in the repo lists every gate with its module and file paths.
Checkpoint: a made-up product gets rejected.
If it stages a change against it anyway, something in your setup deviates from the reference repo, worth filing an issue.
Step 3: try to apply a price change without approving it
Pick a product the agent has shown you (AR-2102 works) and stage a small, in-range change.
Input:
change the price of sku_101 to $95
Expected reply: the agent stages the change and gives you a change id, something like [staged change ####, from your run].
Now immediately type: apply that change
Expected reply: refused, awaiting host approval.
Now go to the merchant approval screen in the app (not the chat) and click approve on that change id. Come back to chat and type apply that change again.
This time it goes through.
Checkpoint: 2 refusals become one success only after you clicked the approve button.
If typing "I approve this" in chat ever makes it apply, that's a bug worth filing too.
Step 4: try to push a price that's obviously too big
Input:
change the price of sku_101 to $50
Expected reply: rejected immediately at staging, before it even generates a change id.
It explains that $50 breaks AR-2102's guardrails: the allowed range tops out at $32.40, and the 20% move cap from the current $24.00 tops out at $28.80, so the most it will stage is $28.80.
Those numbers are in a config file, try rewording the request 5 different ways.
It won't matter, the check runs in code after the model responds, and the model's opinion doesn't come into it.
Checkpoint: oversized change dies at staging every time, no matter how you phrase the ask.
(These figures assume AR-2102 is still at $24.00, so reboot the demo if you approve the step 3 change.)
Step 5: automate the same checks
The guardrails you just tested by hand (grounding, caps, the approval gate) live in the repo's test suites, and pytest runs them.
python scripts/verify_all.py runs the full CI gate on top of that, adding the linter, a static check, deploy dry runs and the web builds.
Green run means you have something you can hand to someone else. Run it again any time you touch a prompt or a gate, before you consider it shippable again.
At this point you have a working demo.
Strip it down to whichever vertical you need, point it at your own catalog, and the guardrails carry over untouched.
My take
What surprised me building this is how much of it isn't agent-specific at all.
You fence the input before the model sees it, you only let a write through when the data behind it was grounded, the caps live in code rather than in a prompt, and approval is a piece of backend state.
That's least-privilege access control, applied to a model instead of a service account, and it's the same discipline we already trust for every other system that touches money.
I've built enough tools now to know the refusal logic is always what gets cut under deadline pressure.
This blueprint forces you to write it first, as config, before the agent ever sees a cart.
If you're building anything that touches money or a live listing, steal these 4 patterns even if you never clone the repo.
Until next time,
Vaibhav 🤝🏻
If you read till here, you might find this interesting
#AD 1
Let AI engineers tell you what's worth reading
Everyone has an opinion about AI. Very few people have shipped it.
TLDR AI is curated by Anthropic and ex-Google engineers who know the difference between a breakthrough and a press release. Every day they cut the field's output down to the handful of stories worth your attention: new models, real research, and tools you'll actually use.
It's the difference between following AI and understanding it.
Free, daily, and read by 1.1M+ engineers, researchers, and founders. Subscribe for free.
#AD 2
One idea shouldn't take six rewrites to post.
Posting everywhere means rewriting one idea six times, so you post to one, or none. SureThing turns one idea into native posts for every platform.
