Commerce Recommendation Agent Stage 1: Functional Requirements

Table of Contents

Why Agent Requirements Are Different

Traditional software lives in a comfortable world of deterministic inputs and outputs. Agent systems break this contract entirely – you’re defining a problem space and providing success criteria for non-deterministic reasoning. The same user intent expressed differently should reach the same outcome, but the path will vary.

Most agent tutorials skip requirements entirely and jump straight to chaining LLM calls. That’s why most agent projects never leave the demo stage. Without clear requirements, you can’t make architectural decisions, evaluate success, or distinguish between “the LLM hallucinated” and “we never defined correct behavior.”

This article defines the functional requirements for the Commerce Recommendation Agent, our shoe recommendation agent built on On.com’s product catalog using Google ADK. Every architectural decision in Stage 2 traces back to a requirement established here.

This article is part of the Commerce Recommendation Agent lab project.

The Core Job to Be Done

The Commerce Recommendation Agent has one primary job: match customers to running shoes through conversational context-gathering. A customer might say “I need something for long runs” or “My current shoes hurt after 10 miles” – different surface expressions of related needs, requiring different information-gathering strategies and product matches.

Success looks like:

• Customer feels understood: the recommendation matches stated and implied needs
• Reasoning is transparent: the customer can see why these shoes were picked and what trade-offs exist between options
• Comparisons are explicit: if we recommend the Cloudmonster for cushioned long runs, we explain why we didn’t recommend the Cloudsurfer

Scope boundaries:

• Does: Conversational shoe recommendation within On.com’s running shoe catalog
• Does not: Handle transactions, manage inventory, provide post-purchase support, recommend apparel/accessories
• Out-of-scope requests: Gracefully acknowledge the boundary and redirect

We’re building on On.com’s real product catalog because toy datasets teach nothing about production challenges – real catalogs have model overlap, subtle spec differences, and marketing language that doesn’t map cleanly to functional attributes.

User Personas

Three core personas stress-test different agent capabilities.

Dimension	Data-Driven Runner	Injury-Anxious Beginner	Specific Problem Solver
Knowledge Level	Expert - knows terminology	Novice - uncertain, fearful	Mixed - knows their pain, not the cause
Question Style	Specific criteria upfront	Vague, emotionally driven	Concrete problem description
Recommendation Format	Detailed comparison of options	Strong single pick + one backup	Root-cause analysis → targeted solution
Key Failure Mode	Being too basic or too agreeable	Interrogation or condescension	Premature conclusions or medical advice

The Data-Driven Runner

• Profile: Knows terminology (pronation, heel-to-toe drop, stack height). Arrives with specific criteria like “neutral daily trainer with 8-10mm drop”
• What they need: Validation and nuanced comparison, not education. If both Cloudflow and Cloudsurfer match their specs, articulate the difference
• Failure modes: Being too basic (“Let me explain what pronation means”) or too agreeable without engaging their expertise

The Injury-Anxious Beginner

• Profile: Uncertain, often fearful. Says things like “I want to start running but I don’t want to get hurt”
• What they need: Gentle diagnostic questions that build confidence without jargon. Don’t ask “What’s your preferred heel-to-toe drop?” – ask “Do you land on your heel first or more on your midfoot?”
• Guidance style: Strong single recommendation with clear reasoning, plus one backup. Multiple similar options will paralyze them
• Failure modes: Interrogation (ten technical questions in a row) or condescension (oversimplified language that sounds like talking to a child)

The Specific Problem Solver

• Profile: Arrives with a concrete pain point: “My knees hurt on downhills” or “I get blisters after 5K”
• What they need: Root-cause investigation before product recommendations. Knee pain on downhills might be impact-related, form-related, or fit-related
• Diagnostic approach: Ask narrowing questions (“Does this happen in all shoes or just your current pair?”) and acknowledge uncertainty when appropriate
• Failure modes: Premature conclusions or overstepping into medical advice

These personas require different conversation strategies, question prioritization, and language adaptation. The agent must recognize which persona it’s talking to (often within 2-3 turns) and adjust – not through hardcoded flows, but through flexible reasoning.

Conversation Flows

These define how the agent moves from initial contact to recommendation. They’re patterns, not rigid scripts.

flowchart TB
    A[Initial Contact] --> B{Intent Detection}
    B -->|Clear criteria| C[Direct Request]
    B -->|Vague intent| D[Exploratory]
    B -->|Too vague| E[Insufficient Info]
    E -->|Context gathered| B
    C --> F[Recommendation]
    D --> F
    F --> G{User Satisfied?}
    G -->|Yes| H[Done]
    G -->|Adjustments needed| I[Correction & Refinement]
    I --> F

Direct Request

• Trigger: User knows what they want (“I need a neutral daily trainer”)
• Agent job: Validate terms, gather 1-2 refining questions, surface options with rationale
• Key requirement: Efficiency. If someone says “neutral daily trainer for 40 miles per week,” you have enough to recommend. Don’t ask about race goals unless it would change the product match

Exploratory

• Trigger: Vague starting point (“I’m looking for new running shoes”)
• Agent job: Open with broad diagnostic questions, narrow incrementally
• Key requirement: Avoid the 20-questions failure mode. Summarize periodically (“Got it – road running, 3-4 times a week, some knee discomfort. Let me focus on impact protection options”) to let the user correct misunderstandings

Correction and Refinement

• Trigger: Post-recommendation feedback (“These are too expensive,” “Something with more cushion”)
• Agent job: Adjust constraints, re-rank options, explain trade-offs introduced by the new constraint
• Key requirement: Memory and context preservation. “Something cheaper” means cheapest shoes that still match all original requirements, not just the cheapest in the catalog

Insufficient Information

• Trigger: Impossibly vague requests (“What’s the best shoe?”)
• Agent job: Recognize the context gap, guide toward better information
• Tone: Helpful, not pedantic. “The best shoe depends on your running style and goals. Let me ask a few questions to point you in the right direction”

Non-negotiable across all flows: Conversation state persistence across turns. If the user mentioned marathon training in turn 2, the agent must recall that context in turn 6.

What Makes a “Good” Recommendation

flowchart TD
    A["🚩 Red Flags (Auto-Fail Gate)"] -->|Pass| B
    A -->|"Contradicts constraints, fabricated specs,\nmedical claims, phantom products"| X[Rejected]
    B["📏 Quantitative Criteria (Mechanically Verifiable)"] -->|Pass| C
    B -->|"Missing constraint match, no rationale,\nno differentiation"| Y[Needs Improvement]
    C["🎯 Qualitative Criteria (Human Judgment)"] --> D[Quality Recommendation]
    C -->|"Poor language adaptation,\nfalse certainty, hidden trade-offs"| Y

Quantitative Criteria (mechanically verifiable)

• Constraint matching: Every recommendation meets all stated constraints (price, type, etc.)
• Cited rationale: Recommendations reference relevant product attributes from the catalog
• Differentiation: Multiple options are distinguished (“here’s why each fits differently”), not “here are three great shoes”
• Trade-off acknowledgment: Explicitly state what you gain and lose with each option

Qualitative Criteria (human judgment)

• Language adaptation: Technical specs for the Data-Driven Runner, plain language for the Beginner
• Honest uncertainty: “I’d lean toward the Cloudsurfer, but the Cloudflow could also work depending on your priority” beats false certainty
• Trade-off honesty: If maximum cushioning and maximum ground feel conflict, say so directly

Red Flags (auto-fail scenarios)

• Contradicts stated constraints: Recommending a stability shoe when the user said “neutral”
• Fabricated product specs: Inventing stack heights, drop measurements, or features not in the catalog
• Medical claims: Diagnosing overpronation or prescribing corrective footwear crosses a liability line
• Phantom products: Recommending shoes that don’t exist in the catalog

These criteria become our test suite in later stages. The difference between a production agent and a demo is whether you can measure success objectively.

Edge Cases and Failure Modes

Edge Cases

• Conflicting requirements: “Maximum cushion but also ground feel” is a contradiction. The agent should catch this early and ask the user to prioritize, rather than making a nonsense recommendation or silently optimizing for one constraint
• No perfect match: Sometimes the user wants something that doesn’t exist. Present the closest match with an honest explanation of the gap, rather than hallucinating a product or recommending a poor fit without acknowledgment
• Non-shoe questions: “What socks should I wear?” is out of scope. Redirect gracefully while staying helpful: “I specialize in running shoes, but if you tell me your distance, I can recommend shoes for that volume”
• Ambiguous multi-intent: “I need trail shoes and also something for the gym” contains two needs. Sequence them: handle trail shoes first, then acknowledge the gym need and clarify if running-based gym workouts fall in scope

Failure Modes to Design Against

• Conversation loops: Asking the same question repeatedly due to poor state tracking
• Premature confidence: Recommending before gathering sufficient context
• Redundant questioning: Asking for information the user already provided
• Silent scope creep: Answering questions outside the agent’s domain instead of redirecting

Each maps to specific requirements for state management, retrieval accuracy, prompt design, and conversation control. The goal isn’t handling every scenario perfectly – it’s failing gracefully and recognizing when the agent is outside its competence zone.

Success Metrics

Dev Metrics (functional correctness)

• Constraint matching: Do all recommended shoes meet stated criteria (type, price, use case)?
• Memory correctness: Does the agent incorporate context from earlier turns?
• Data correctness: Are product specs (stack height, drop, weight) accurate vs. source catalog?

Production Metrics (real usage behavior)

• Conversation completion rate: Conversations reaching a recommendation vs. abandoned
• Recommendation acceptance: Would a knowledgeable shoe fitter agree with the recommendation?
• Average conversation length: 15+ turns suggests over-caution or redundant questioning
• Scope boundary adherence: Correct redirects for out-of-scope questions vs. hallucinated answers

Qualitative Evaluation (human judgment)

• Persona-based testing: Run each persona through realistic conversations and evaluate adaptation
• Adversarial red-teaming: Hit the agent with contradictory constraints, vague questions, rapid topic changes, and out-of-scope requests
• Expert review: Have a running store employee or coach evaluate recommendation quality

A recommendation might pass all functional tests but feel robotic. A conversation might feel great but recommend the wrong shoes. Multi-faceted metrics with clear thresholds give us the complete picture.

From Requirements to Architecture

flowchart LR
    subgraph Requirements
        P[User Personas]
        CF[Conversation Flows]
        RC[Recommendation Criteria]
        EC[Edge Cases]
        SM[Success Metrics]
    end
    subgraph "Architectural Concerns"
        LA[Language Adaptation]
        CS[Conversation Strategy]
        STM[State Management]
        CP[Context Persistence]
        CR[Catalog Retrieval]
        TA[Trade-off Articulation]
        SB[Scope Boundary Detection]
        GD[Graceful Degradation]
        IN[Instrumentation]
        TI[Test Infrastructure]
    end
    P --> LA
    P --> CS
    CF --> STM
    CF --> CP
    RC --> CR
    RC --> TA
    EC --> SB
    EC --> GD
    SM --> IN
    SM --> TI

Every design choice in Stage 2 maps back to these requirements:

• User personas require flexible language adaptation and conversation strategy selection – no single hardcoded question flow
• Conversation flows require robust state management that persists context across turns and allows corrections
• Recommendation criteria require accurate catalog retrieval and the ability to articulate trade-offs
• Edge cases require scope boundary detection and graceful handling of ambiguous or conflicting inputs
• Success metrics require instrumentation and test infrastructure from the start

Stage 2 will address: What goes in the system prompt vs. tool implementations vs. retrieval systems? How do we manage conversation state? What does the agent loop look like? How do we structure the catalog for retrieval?

We’ve defined the problem. Now we can build the solution.

Follow the full build at the Commerce Recommendation Agent lab project page.