At the first internal demonstration of the meal assistant, Ruan Botha typed the request his team had heard most often in shopper interviews: "supper for four tonight, one child is allergic to peanuts, keep it under R400, we already have rice." The reply proposed a chicken stir-fry "with a peanut-free satay-style sauce" and offered a basket.
The basket held a jar of satay sauce made with peanuts, because that was the product closest to the words "satay-style sauce" in the search index. It held a 1 kg bag of rice, and fresh coriander that the shopper's nearest store had sold out of at lunchtime. The total was R455.
Ubuntu Grocer, where this happened, is a composite: a fictional South African grocery retailer whose scenario draws on lessons from real enterprise retail-agent delivery. Its people, systems and figures are illustrative and describe no single organisation. It runs supermarkets, a convenience format and an app and web store with same-day and next-day delivery and click-and-collect, and its loyalty programme is Ubuntu Rewards. This series follows the meal assistant in that app.
Lindiwe Dube, head of digital commerce, owns the outcome the assistant exists for: more shoppers leaving with a basket they trust. A parent who finds peanuts in a basket built for an allergic child does not file a bug report. They stop using the feature. Yet nothing in that demonstration failed because of the model. The plan was sensible and the reply even mentioned the allergy. Every failure happened after the model had finished writing.
That is the argument of this series. The agent is the smallest part of the system that makes it useful.
The model is one box among six concerns
When Pieter van Wyk, the principal architect, redrew the assistant after the demonstration, he drew four layers between the shopper's request and her review, wrapped in governance and operations: six concerns in all. The model occupied one small box in the second layer.
Trusted context is what the model must be given because it cannot know it: the catalogue with allergen and pack-size attributes, current prices, stock at the shopper's store, the shopper's profile and what is already in the cupboard. The model could not know the satay sauce contained peanuts unless a product attribute said so and something read it. Part 5 argues that the catalogue is the real knowledge base for this kind of agent.
Bounded decisions means the model interprets and proposes inside a workflow that decides what happens next. The allergy and the R400 budget are not instructions for the model to remember. Code filters every candidate product against the allergy and checks the whole basket against the budget, the subject of Part 4.
Execution against retail systems is where a plan becomes a basket: matching products, choosing pack sizes, computing quantities, applying substitution rules and writing to the basket service the app already uses.
Recovery is what happens when a model call times out at month-end or stock disappears between the plan and the basket. A good recovery path returns an honest partial basket ("no fresh coriander at your store; here are two options") rather than an error or an invented line.
Governance covers authority, privacy (an allergy is health information about a child), security and evaluation. Operations covers tracing, capacity, token cost and who gets paged. Our article agentic AI sits on a stack describes a stack of AI techniques; this one is the production system for one commercial journey.
The only component that fails fluently
Most components fail loudly. A pricing service that is down returns an error; a search that hangs trips a timeout. A model that is wrong returns a well-formed, confident sentence.
That asymmetry is the most useful design fact in agentic retail, and it led Ubuntu Grocer to a rule: any fact in a reply that matters commercially must come from a system of record, and the model may only phrase it. Prices come from the pricing service at the moment the basket is built. Availability comes from the availability service for the shopper's store or fulfilment slot. Allergen status comes from product attributes, checked in code. Quantities come from arithmetic, not from the model's sense of what four people eat.
It also explains a pattern we see in reviews of retail-agent programmes. Because the model speaks for the whole system, every failure underneath it reaches the shopper in the model's voice. A missing allergen attribute, a stale price or a lagging stock feed all look like "the AI got it wrong". Teams then tune prompts to fix defects that live in data and integration, and the defects remain.
Authority follows the same logic. The meal assistant may propose; the shopper confirms. Nothing reaches checkout without an explicit action by the shopper, and the agent never initiates payment. Our article on why agent capability is not agent authority sets out the general model. Here the line is simple to draw, and every later design choice depends on it.
The arithmetic of a journey
A single shopper message does not make a single call. When Ruan's team walked one request through the redesigned journey on a whiteboard, the orchestrator needed fourteen kinds of call to produce one reply, in the illustrative breakdown below. Only three of them reached a model.
Two consequences follow.
The first is that quality multiplies. Suppose, for illustration, that six stages each produce a correct result 95% of the time: interpreting intent, matching products, applying constraints, checking stock, computing quantities and writing the basket. The basket is correct only when all six are, and 0.95 multiplied by itself six times is about 0.74. Roughly one basket in four has something wrong with it, while every team truthfully reports 95%. Improving intent interpretation alone to 99% moves the journey to about 77%. The weakest layer sets the ceiling, and it is rarely the model.
The second is that latency adds and its tail compounds. The calls are mostly sequential, so the 95th-percentile latency (p95) of the journey is worse than the p95 of any step. If each of fourteen calls has a 5% chance of being slow, 1 minus 0.95 to the fourteenth power is about 0.51: half of all replies hit at least one slow call. Part 7 explains why you load-test the journey rather than an endpoint, and Part 9 treats tokens as a capacity dependency.
Ubuntu Grocer's composite architecture
The rest of this series refers back to one architecture. It is a vendor-neutral composite: every box has public equivalents on every major cloud, and any product we name is a dated example, not the platform a real programme used.
The front ends sit behind a content delivery network (CDN) edge with a web application firewall (WAF) (Part 13). The backend-for-frontend (BFF) API owns the session and creates a journey ID when a conversation starts. Every later call carries it as an attribute on every span, alongside the standard W3C Trace Context traceparent header that links each request's spans (Part 11).
The journey orchestrator is a deterministic workflow. It calls three bounded agent steps in a fixed order (meal planning, ingredient-to-product matching, and a basket agent that proposes changes and cannot check out), gives them only the context they need and mediates every call to the retail services. Part 6 assigns decision rights to each action.
Every model call passes through an AI gateway for routing, quotas, token accounting and fallback, to a stronger model for ambiguous reasoning or smaller ones for classification, each with capacity in more than one location (Part 10).
The retail services existed before the assistant and still do the commercial work: catalogue and search index (keyword and vector), pricing, availability per store or fulfilment node, substitution rules, preference profile, and the existing basket and checkout. Sipho Nkosi owns the catalogue and product data.
Underneath sit shared infrastructure with readiness probes and autoscaling (Part 12) and OpenTelemetry-style observability. Ayesha Patel, the site reliability engineering (SRE) lead, runs an SRE assistant that is read-only by default (Part 14). Thandeka Mokoena, the security architect, owns the edge controls.
Where the effort actually goes
In Pieter's re-plan, prompts and model selection were a small share of the remaining work. Most sat elsewhere: allergen and pack-size attributes in the catalogue, constraint enforcement in code, integration with the basket service, journey-level load testing, tracing and a review screen for the shopper. The design has trade-offs worth stating plainly.
A workflow with bounded agent steps is less flexible than an agent that picks its own next step. A question outside the journey, such as "what goes with bobotie for dessert?", needs an explicit route. Ubuntu Grocer accepts that cost because a basket change is a commercial action, and a grocery basket is mostly known steps with one or two uncertain ones. Our Not Every Workflow Needs an Agent series sets out when the unknown genuinely forces an agent-led design.
Validation costs time. Checking every candidate against allergens and stock, and the basket against the budget, adds calls and milliseconds. The alternative is a faster wrong answer.
The AI team cannot deliver this alone. The catalogue, SRE, security, basket and checkout owners all hold part of the outcome. A programme that staffs only the agent gets an impressive demonstration and a fragile product, the gap described in the demo is not the delivery.
After the redesign, the same request produced a different result. The matcher removed every product with a peanut allergen attribute before ranking, so the plan used a tomato-based sauce. The whole basket passed the budget check. Rice was left out because the shopper had said she had it. Coriander was out of stock at her store, so flat-leaf parsley appeared as a marked substitution for her to accept or remove. The total was R372. The model had not changed.
How this series is organised
The fifteen parts run in four arcs, each teaching one mechanism through Ubuntu Grocer.
| Arc | Parts | The question it answers |
|---|---|---|
| The value journey | 1 to 3 | How does a sentence become a basket? Part 2 traces the journey; Part 3 handles units and pack sizes. |
| Catalogue and decisions | 4 to 6 | What must be true about constraints, product data and authority before the agent decides? |
| Production engineering | 7 to 12 | Will it hold on a month-end Friday, and can you see why when it does not? |
| Governance and operations | 13 to 15 | Who controls it, who runs it, and what shows it is ready? Part 15 closes with a checklist. |
Questions to take into your architecture review
- Which of the six concerns in your stack has a named owner, and which does not?
- For each commercial fact in a reply (price, stock, allergen status, quantity), which system of record supplies it, and can the model change it?
- How many calls does one shopper message make, and how many reach a model?
- What is the correct-basket rate measured on whole journeys, not per component?
- Where are allergies and budgets enforced, and what happens if the model ignores them?
- When a step fails, does the shopper see an error, an invented line or an honest partial basket?
- Can the agent reach checkout or payment by any path without an explicit shopper action?
- Does one journey ID travel with every call, from the front end to the basket service?
Key points
- The language model is one small box among six concerns: trusted context, bounded decisions, execution, recovery, governance and operations.
- The model is the only component that fails fluently. Commercial facts must come from systems of record; the model only phrases them.
- Quality multiplies across stages. The weakest layer sets the ceiling, and it is rarely the model.
- One shopper message triggers many calls. Test, trace and measure the journey, not the model.
- The agent proposes and the shopper confirms. Nothing reaches checkout without explicit shopper action.
CloudNala's point of view
Most retail-agent programmes we review spend their first months on the part that already works. The model is good enough; what is missing is the catalogue data, constraint code, basket integration and operational visibility that turn a fluent reply into a basket a shopper can trust. We would rather see a modest model inside a well-built system than a frontier model on a catalogue nobody owns. If your plan has more prompt engineering in it than product data work, it is upside down.
Next: Part 2, From conversation to cart: the basket is the outcome. All parts are on the series page.
Background reading: W3C Trace Context (W3C Recommendation, checked on 5 November 2026).
How CloudNala can help
CloudNala runs Agentic Retail Reviews for retailers building conversational shopping or basket-building assistants. We map your journey onto the production stack, find the layers that lack an owner or a system of record, and set out the catalogue, constraint, integration and operational work needed before the agent can be trusted with a shopper's basket.
Work with CloudNala
CloudNala helps organisations move from technology ambition to practical execution across cloud, AI, data, platform engineering and digital services.
Whether you are exploring AI, modernising your cloud environment, building a public-sector digital service, or turning an idea into a working MVP, we can help you shape the roadmap and deliver the next step.
Book an Agentic Retail Review or write to us at consult@cloudnala.co.za