A Commerce Agent Needs a Proper Brief

A proposal at the end of the season

A mid-sized fashion retailer reaches the end of the season with more stock than it wants. The new collection lands in a few weeks, the warehouse is already tight, and an AI agent has read the sales data and proposed a short promotion. Every item is in stock, the markdown sits inside the permitted range, and the whole thing now waits for somebody to press approve.

The trouble is that a few of those items were selling perfectly well at full price. Others exist only in the sizes nobody wants. And a portion of the range has already been promised to a different channel by a buyer who had good reasons and mentioned them once, in passing. Anyone who has run promotions for a living will want those facts in view before agreeing to anything. That a discount is allowed says nothing about whether it is worth taking.

An agent could still be genuinely useful here. Proposals could be prepared faster, more often, and for the smaller pockets of stock that never justified the analysis before. What the retailer has to supply in return is a description of what the agent is meant to achieve and which cases deserve a closer look. The scale of that work becomes visible the moment a general idea has to become a brief for one particular business.

What the reference kit supplies

On 2 September 2026 Anthropic published a reference kit for building commerce agents. A shopping agent helps customers search, compare and assemble a basket. A merchant agent works on the retailer's side of the counter, supporting analysis and preparing things like price changes and campaigns. Anthropic announcement

Some of the groundwork a development team would otherwise build itself is already there, including technical limits and approval steps. The shopping agent hands the basket to checkout, and the retailer's own application handles the order and the payment. On the merchant side, changes are staged first and applied only through the intended approval. Certain limits are checked again at execution time. Technical documentation

How much time this actually saves depends almost entirely on the systems already in the building. Getting at current stock figures can be a project in itself. The quality of the answers has to prove itself against the retailer's own products and its own customers, who ask questions that no demonstration ever anticipates. A business with clean data and sensible interfaces starts from a very different place than one whose team reconciles three systems to establish whether a jacket exists.

The code is openly licensed under Apache 2.0, and Anthropic is clear that the reference implementation is not maintained. Whoever uses it looks after their own version and carries the running cost of model usage and integration. Then there is the human cost of reviewing proposals and sorting out the ones that go wrong. Even a modest deployment needs a named answer to the question of who does that. Repository

Purpose and unwritten knowledge

For our retailer the useful work starts with the purpose of the promotion. Improve sell-through sounds like an objective until somebody asks what is pressing hardest just now. Space for the new collection, cash in the next few weeks, or margin on what remains. Each answer points at different items and different reductions, and only one of them is the reason this promotion exists.

Sales may have a solid case for going wide. Buying may know that one label will be wanted again in a month. The finance director would like to see what survives after the likely costs. All three can read the same figures correctly and still recommend different things, because they are weighing different consequences of one decision.

A well built agent could set out several options side by side, show where the recommendation flips if returns run higher than expected, and ask for the figures it does not have. All of that depends on reaching the relevant information. A fluent, confident rationale is not evidence that this retailer's costs and constraints were part of the calculation. Prose has never been a reliable indicator of arithmetic.

How much margin the business is willing to give up for early warehouse space is a judgement someone with authority has to make. A managing director can take it personally or delegate it through the responsibilities that already exist. Accepting lower revenue to clear the floor in time can be entirely sensible, provided the purpose then travels with the promotion. Otherwise the same campaign is criticised three months later for its thin margin, which was the price everyone agreed to pay for something else.

A retailer with clear promotion rules and settled responsibilities has done a great deal of this work already. Those rules can be carried into the implementation and tested against the actions the agent is expected to take. Where practice lives mostly in the experience of two or three long-serving colleagues, rather more will need saying out loud.

The buyer, for instance, knows that a joint campaign with one label is planned for next month, so its products stay out of other promotions even though they are selling slowly. In a corridor conversation this is a single sentence, and it has never once appeared in a report. If the agent is to respect it, somebody has to tell it. A reliably maintained exclusion list may be worth more here than a cleverer sales analysis.

A bounded brief

From all of this a bounded brief for the first attempt can be written. The agent prepares proposals for selected seasonal stock, aimed at freeing enough warehouse space before the new delivery arrives. Certain items are excluded. An agreed commercial floor holds, and planned campaigns are respected. Where information needed for the judgement is missing, the proposal is parked for clarification rather than pushed through. That is a statement of what the retailer requires. Whether it can be delivered reliably is something the retailer's own cases will decide.

Staying at the preparation stage for a while is a perfectly respectable ambition. The development team learns from the questions and corrections where information is missing or a step needs rethinking. Over a few months it becomes clear which situations repeat and whether any of them deserve wider authority.

Anthropic notes in its documentation that business rules, permissions and the specific values behind technical limits belong to each implementation, and that the defaults in the reference code are there for demonstration. For our retailer, that means deciding which values suit its brief and who is allowed to change them. Safety documentation

Approval in practice

When the markdown arrives for approval, the person responsible has to see, without a research project, whether it matches what was agreed. A campaign name and a list of new prices will not carry that weight.

What helps is the state of the data and the assumptions underneath the recommendation. Were expected returns taken into account. Are any items already committed elsewhere. Where the answer is uncertain, the proposal should say so rather than present a smooth number. Attaching every available figure is no substitute, since the reviewer mainly needs easy access to the handful of things their decision turns on, and a way to check where those came from.

There is also the small matter of volume. A weekly analysis can quietly become a stream of daily proposals, each of which someone must read, query and decide. In a business with a small commercial team that effort can swallow the time the agent was supposed to save. Batching proposals or narrowing the brief may be the sensible response. Either way, review time is part of the cost of running this, even though it appears on no software invoice.

It also has to be possible to park an unclear case. If asking a question becomes tiresome enough, a plausible proposal will be waved through more or less automatically, and the approval on record will tell you very little about how carefully anyone looked.

When circumstances change

A few days after launch, the new collection is delayed. The pressure in the warehouse eases while the discounted items keep selling. The promotion still sits within every technical limit that was set for it. What has changed is the reason it exists in the first place, which no limit was ever asked to monitor.

Checking the discount ceiling will not catch this. The retailer would need the delivery date treated as a live condition and somebody named to hear about it when the date moves. Whether that person holds the reduction, trims it or ends the promotion depends on the situation in front of them. They need the authority to make that call and a practical route to carry it out, ideally one that does not involve a support ticket.

Technical changes deserve the same attention. A different model or an altered pipeline can produce different results from the same inputs. Anthropic covers evaluation and production operation in some detail in its accompanying technical piece, and the retailer will want to extend that with its own cases. A good one would be a proposal where the delivery date shifts between preparation and approval. Technical discussion

What counts at the end

At the end of the season, higher sell-through on its own is not a verdict. Some of that stock would have found buyers anyway. Discounts may have pulled sales forward or steered customers towards items that contribute less. The retailer needs a defensible comparison to estimate what the agent actually added, and, since space was the stated aim, whether the warehouse cleared in time.

Once development, model usage and support are counted, the honest finding may be that only the analysis pays for itself for now, because preparing promotions still takes too much correcting. Limiting the deployment to that is a result rather than a defeat, and it gives the retailer a reason to see whether the most common errors can be fixed at reasonable cost. Any later decision to widen the brief then rests on evidence from its own operation.

For a first attempt, the retailer wants a task whose purpose it can explain and whose consequences it can follow. That is enough to find out what the agent takes on and what stays with the people who were doing it before. Existing responsibilities are a reasonable place to start, and wherever information or rules are missing, a few concrete proposals will make it obvious.

In the case of the markdown, it means recording why the promotion was approved. If all that survives is a list of prices, nobody can judge, once the delivery slips, whether the thing still makes sense. Someone who knows the purpose and the assumptions can carry on deciding. A proper brief keeps hold of the reasoning that used to live in a conversation between buying and sales, and on that basis the agent can gradually be trusted with more.