Multi-Agent eCommerce System Specification

Version: 1.0
Date: February 4, 2026
Framework: A2A (Agent-to-Agent)
UI Framework: Gradio

Overview

The Multi-Agent eCommerce System is an example implementation demonstrating a distributed agent architecture for handling online shopping workflows. The system simulates a realistic eCommerce experience through specialized agents that coordinate to provide search, cart management, checkout, and order tracking capabilities.

This specification defines the behavior, architecture, and implementation requirements for a multi-agent system that routes customer requests through a master orchestration agent to specialized sub-agents, each responsible for specific eCommerce operations.

Purpose

The purpose of this system is to:

Demonstrate multi-agent coordination patterns using the A2A framework
Illustrate separation of concerns in eCommerce workflows
Provide a working example of agent specialization and routing
Showcase tool integration with specialized agents
Serve as a reference implementation for building distributed agent systems

Core Principles

Agent Specialization: Each agent has a single, well-defined responsibility
Tool Binding: Tools are explicitly bound to the agents that use them
Stateful Workflows: The system maintains state across multi-step interactions
Pure Delegation: The master agent routes requests but does not execute business logic
User-Friendly Interface: Gradio provides an accessible web-based chat interface

System Architecture

Agent Hierarchy

┌─────────────────────────────┐
│   Master eCommerce Agent    │
│   (Orchestrator/Router)     │
└──────────┬──────────────────┘
           │
           ├─────────────────┬──────────────────┬────────────────────┐
           │                 │                  │                    │
           ▼                 ▼                  ▼                    ▼
    ┌──────────┐      ┌──────────┐      ┌──────────────┐    ┌──────────────┐
    │  Search  │      │   Cart   │      │   Checkout   │    │ Order Status │
    │  Agent   │      │  Agent   │      │    Agent     │    │    Agent     │
    └────┬─────┘      └────┬─────┘      └──────┬───────┘    └──────┬───────┘
         │                 │                   │                   │
         ▼                 ▼                   ▼                   ▼
    [search_      [add_to_cart]      [checkout]          [get_order_status]
     products]

Agent Definitions

1. Master eCommerce Agent

Role: Orchestrator and request router
Responsibilities:

Analyze incoming user requests to determine intent
Route requests to the appropriate specialized sub-agent
Aggregate responses from multiple agents when necessary
Maintain conversational context across agent handoffs
Provide helpful guidance when user intent is unclear

Does NOT:

Execute eCommerce operations directly
Access eCommerce tools
Maintain product or order state (delegates to sub-agents)

Routing Logic:

Product search queries → Search Agent
Cart operations (add/remove/view) → Cart & Checkout Agent
Checkout/payment operations → Cart & Checkout Agent
Order status inquiries → Order Status Agent
General inquiries → Responds directly with guidance

2. Search Agent

Role: Product discovery and search
Responsibilities:

Process product search requests
Filter and rank search results
Present product information clearly
Handle search refinement and filtering

Available Tools:

search_products(query: str, category: str = None, max_results: int = 10) -> List[Product]

Tool Behavior:

Returns products matching search query
Supports optional category filtering
Returns product details: ID, name, description, price, category, stock status

3. Cart & Checkout Agent

Role: Shopping cart management and purchase completion
Responsibilities:

Add/remove products from cart
Display current cart contents and total
Process checkout requests
Validate cart state before checkout
Handle payment processing (simulated)

Available Tools:

add_to_cart(product_id: str, quantity: int = 1) -> CartStatus
checkout(payment_method: str = "credit_card") -> OrderConfirmation

Tool Behavior:

add_to_cart: Validates product availability, updates cart, returns new cart state
checkout: Validates non-empty cart, creates order, clears cart, returns order details

Validation Rules:

Product must exist and be in stock before adding to cart
Checkout requires at least one item in cart
Checkout validates total inventory availability

4. Order Status Agent

Role: Order tracking and history
Responsibilities:

Retrieve order status by order ID
Display order details (items, total, status)
Explain order statuses to users
Handle order-related inquiries

Available Tools:

get_order_status(order_id: str) -> OrderDetails

Tool Behavior:

Returns complete order information including status
Statuses: "pending", "processing", "shipped", "delivered", "cancelled"

Product Catalog

The system includes 10 example products across 3 categories:

Electronics

Product ID: ELEC001
- Name: Wireless Bluetooth Headphones
- Description: Premium noise-cancelling over-ear headphones with 30-hour battery life
- Price: $149.99
- Stock: 25 units
- Category: Electronics
Product ID: ELEC002
- Name: 4K Smart TV 55"
- Description: Ultra HD smart television with HDR and built-in streaming apps
- Price: $599.99
- Stock: 15 units
- Category: Electronics
Product ID: ELEC003
- Name: Laptop Stand (Aluminum)
- Description: Ergonomic adjustable laptop stand for improved posture
- Price: $49.99
- Stock: 50 units
- Category: Electronics

Home & Garden

Product ID: HOME001
- Name: Coffee Maker (12-cup)
- Description: Programmable drip coffee maker with thermal carafe
- Price: $79.99
- Stock: 30 units
- Category: Home & Garden
Product ID: HOME002
- Name: Memory Foam Pillow
- Description: Contoured memory foam pillow for neck and spine support
- Price: $34.99
- Stock: 100 units
- Category: Home & Garden
Product ID: HOME003
- Name: LED Desk Lamp
- Description: Adjustable LED lamp with multiple brightness levels and USB charging port
- Price: $39.99
- Stock: 40 units
- Category: Home & Garden

Sports & Outdoors

Product ID: SPORT001
- Name: Yoga Mat (6mm)
- Description: Non-slip exercise mat with carrying strap
- Price: $24.99
- Stock: 75 units
- Category: Sports & Outdoors
Product ID: SPORT002
- Name: Water Bottle (32oz Insulated)
- Description: Stainless steel vacuum-insulated water bottle, keeps cold 24h
- Price: $29.99
- Stock: 60 units
- Category: Sports & Outdoors
Product ID: SPORT003
- Name: Resistance Bands Set
- Description: Set of 5 resistance bands with different tension levels and door anchor
- Price: $19.99
- Stock: 85 units
- Category: Sports & Outdoors
Product ID: SPORT004
- Name: Running Shoes (Men's)
- Description: Lightweight running shoes with responsive cushioning
- Price: $89.99
- Stock: 45 units
- Category: Sports & Outdoors

Tool Specifications

1. search_products

Purpose: Search for products by query and optional category filter

Signature:

def search_products(
    query: str,
    category: str = None,
    max_results: int = 10
) -> List[Dict[str, Any]]

Parameters:

query (str, required): Search term to match against product names and descriptions
category (str, optional): Filter results by category ("Electronics", "Home & Garden", "Sports & Outdoors")
max_results (int, optional, default=10): Maximum number of results to return

Returns: List of product dictionaries with the following structure:

{
    "product_id": str,
    "name": str,
    "description": str,
    "price": float,
    "stock": int,
    "category": str
}

Behavior:

Case-insensitive search across product names and descriptions
Returns empty list if no matches found
Results sorted by relevance (exact matches first, then partial matches)
Respects max_results limit
Category filter is exact match, case-sensitive

Example Calls:

# Simple search
search_products("headphones")
# Returns: [ELEC001]

# Category-filtered search
search_products("mat", category="Sports & Outdoors")
# Returns: [SPORT001]

# Search with no results
search_products("smartphone")
# Returns: []

2. add_to_cart

Purpose: Add a product to the shopping cart

Signature:

def add_to_cart(
    product_id: str,
    quantity: int = 1
) -> Dict[str, Any]

Parameters:

product_id (str, required): Unique identifier of the product
quantity (int, optional, default=1): Number of units to add

Returns: Cart status dictionary:

{
    "success": bool,
    "message": str,
    "cart": {
        "items": [
            {
                "product_id": str,
                "name": str,
                "price": float,
                "quantity": int,
                "subtotal": float
            }
        ],
        "total": float,
        "item_count": int
    }
}

Behavior:

Validates product exists in catalog
Validates sufficient stock is available
If product already in cart, increases quantity
Updates cart total automatically
Returns error if product not found or insufficient stock

Error Cases:

Product ID not found: Returns {"success": false, "message": "Product not found"}
Insufficient stock: Returns {"success": false, "message": "Insufficient stock available"}
Invalid quantity (< 1): Returns {"success": false, "message": "Quantity must be at least 1"}

Example Calls:

# Add single item
add_to_cart("ELEC001")
# Returns: {success: true, cart: {items: [...], total: 149.99, item_count: 1}}

# Add multiple items
add_to_cart("HOME002", quantity=2)
# Returns: {success: true, cart: {items: [...], total: 69.98, item_count: 2}}

3. checkout

Purpose: Complete purchase of items in cart

Signature:

def checkout(
    payment_method: str = "credit_card"
) -> Dict[str, Any]

Parameters:

payment_method (str, optional, default="credit_card"): Payment method for the order. Accepted values: "credit_card", "debit_card", "paypal", "apple_pay"

Returns: Order confirmation dictionary:

{
    "success": bool,
    "message": str,
    "order": {
        "order_id": str,  # Format: ORD-YYYYMMDD-XXXX
        "items": [
            {
                "product_id": str,
                "name": str,
                "price": float,
                "quantity": int
            }
        ],
        "total": float,
        "payment_method": str,
        "status": str,  # Always "pending" immediately after checkout
        "created_at": str  # ISO 8601 timestamp
    }
}

Behavior:

Validates cart is not empty
Validates all cart items are still in stock
Generates unique order ID
Deducts inventory from stock
Clears the cart upon successful checkout
Records order with "pending" status
Returns error if cart is empty or stock validation fails

Error Cases:

Empty cart: Returns {"success": false, "message": "Cart is empty"}
Stock unavailable: Returns {"success": false, "message": "One or more items no longer available"}
Invalid payment method: Returns {"success": false, "message": "Invalid payment method"}

Order ID Format: ORD-YYYYMMDD-XXXX where XXXX is a sequential 4-digit number

Example Calls:

# Standard checkout
checkout()
# Returns: {success: true, order: {order_id: "ORD-20260204-0001", total: 149.99, status: "pending", ...}}

# Checkout with specific payment method
checkout(payment_method="paypal")
# Returns: {success: true, order: {order_id: "ORD-20260204-0002", payment_method: "paypal", ...}}

4. get_order_status

Purpose: Retrieve status and details of a specific order

Signature:

def get_order_status(
    order_id: str
) -> Dict[str, Any]

Parameters:

order_id (str, required): Unique order identifier

Returns: Order details dictionary:

{
    "success": bool,
    "message": str,
    "order": {
        "order_id": str,
        "items": [
            {
                "product_id": str,
                "name": str,
                "price": float,
                "quantity": int
            }
        ],
        "total": float,
        "payment_method": str,
        "status": str,  # One of: pending, processing, shipped, delivered, cancelled
        "created_at": str,
        "updated_at": str,
        "tracking_number": str  # Only present if status is "shipped" or "delivered"
    }
}

Behavior:

Looks up order by order ID
Returns complete order information including current status
Returns error if order ID not found

Order Statuses:

pending: Order placed, payment processing
processing: Payment confirmed, preparing for shipment
shipped: Order dispatched, in transit
delivered: Order received by customer
cancelled: Order cancelled by customer or system

Error Cases:

Order not found: Returns {"success": false, "message": "Order not found"}
Invalid order ID format: Returns {"success": false, "message": "Invalid order ID format"}

Example Calls:

# Check order status
get_order_status("ORD-20260204-0001")
# Returns: {success: true, order: {order_id: "ORD-20260204-0001", status: "processing", ...}}

# Order not found
get_order_status("ORD-99999999-9999")
# Returns: {success: false, message: "Order not found"}

A2A Framework Integration

Agent Configuration

Each agent is configured as an A2A agent with the following structure:

from a2a import Agent, Tool

# Define tools
search_tool = Tool(
    name="search_products",
    description="Search for products by name or description",
    function=search_products,
    parameters={
        "query": {"type": "string", "required": True},
        "category": {"type": "string", "required": False},
        "max_results": {"type": "integer", "required": False, "default": 10}
    }
)

# Create specialized agent
search_agent = Agent(
    name="SearchAgent",
    description="Specialized agent for product search and discovery",
    tools=[search_tool],
    instructions="""
    You are a product search specialist. Your job is to help users find products.
    Use the search_products tool to find relevant items.
    Present results clearly with product details, prices, and availability.
    Ask clarifying questions if the search is too broad.
    """
)

# Create master orchestrator agent
master_agent = Agent(
    name="MasterEcommerceAgent",
    description="Main orchestrator for all eCommerce operations",
    sub_agents=[search_agent, cart_agent, checkout_agent, order_status_agent],
    instructions="""
    You are the master eCommerce agent. Route customer requests to specialized agents:
    - Product searches → SearchAgent
    - Cart operations → CartAgent
    - Checkout → CheckoutAgent
    - Order status → OrderStatusAgent
    
    Do not execute operations yourself. Always delegate to the appropriate agent.
    Provide clear guidance when user intent is ambiguous.
    """
)

Agent Communication Protocol

Agents communicate using the A2A message passing protocol:

# Master agent receives user message
user_message = "I'm looking for headphones"

# Master agent determines intent and routes
intent = analyze_intent(user_message)  # Returns "search"

# Master delegates to Search Agent
response = master_agent.delegate(
    agent=search_agent,
    message=user_message,
    context={"user_id": session_id}
)

# Search Agent executes tool and responds
search_results = search_agent.execute_tool(
    tool="search_products",
    parameters={"query": "headphones"}
)

# Response flows back through master to user
final_response = master_agent.format_response(search_results)

State Management

The system maintains state at multiple levels:

Session State (per user):
- Current cart contents
- Conversation history
- User preferences
Global State:
- Product catalog and inventory
- Order history
- Order status tracking
Agent State:
- Last executed action
- Pending operations
- Context from previous interactions

State is persisted using an in-memory store for this example implementation, but the architecture supports external state stores (Redis, database) for production use.

Gradio UI Specification

Interface Layout

The Gradio interface consists of:

Chat Interface (Primary):
- Message history display
- Text input for user messages
- Submit button
- Clear conversation button
System Information Panel (Sidebar):
- Current cart summary (item count, total)
- Recent order status
- Active agent indicator
Debug Panel (Optional, collapsible):
- Agent routing decisions
- Tool invocations
- Response times

Gradio Implementation Structure

import gradio as gr

def chat_interface(message, history):
    """Process user message and return response"""
    # Route through master agent
    response = master_agent.process(message)
    
    # Update history
    history.append((message, response))
    
    # Update cart display
    cart_info = get_current_cart()
    
    return history, cart_info

# Create Gradio interface
with gr.Blocks() as demo:
    gr.Markdown("# Multi-Agent eCommerce System")
    
    with gr.Row():
        with gr.Column(scale=3):
            chatbot = gr.Chatbot(
                label="Chat with eCommerce Agents",
                height=500
            )
            
            with gr.Row():
                msg = gr.Textbox(
                    label="Your message",
                    placeholder="Try: 'Show me electronics' or 'Add headphones to cart'",
                    scale=4
                )
                submit = gr.Button("Send", scale=1)
            
            clear = gr.Button("Clear Conversation")
        
        with gr.Column(scale=1):
            cart_display = gr.JSON(
                label="Current Cart",
                value={"items": [], "total": 0.00}
            )
            
            gr.Markdown("### Quick Actions")
            view_cart = gr.Button("View Full Cart")
            checkout_btn = gr.Button("Checkout")
    
    # Event handlers
    submit.click(
        chat_interface,
        inputs=[msg, chatbot],
        outputs=[chatbot, cart_display]
    )
    
    clear.click(
        lambda: None,
        outputs=[chatbot]
    )

UI Behavior

Real-time Updates: Cart display updates automatically after cart operations
Typing Indicators: Shows which agent is processing the request
Error Handling: Displays user-friendly error messages in chat
Conversation Context: Maintains context across multiple messages
Multi-turn Interactions: Supports follow-up questions and refinements

Example User Flows in UI

Flow 1: Product Search and Purchase

User: "I need headphones"
SearchAgent: "I found premium Wireless Bluetooth Headphones for $149.99..."

User: "Add them to my cart"
CartAgent: "Added Wireless Bluetooth Headphones to your cart. Total: $149.99"

User: "Checkout with PayPal"
CheckoutAgent: "Order confirmed! Order ID: ORD-20260204-0001. Total: $149.99"

Flow 2: Multi-item Shopping

User: "Show me products under $30"
SearchAgent: "Here are products under $30: Yoga Mat ($24.99), Water Bottle ($29.99)..."

User: "Add the yoga mat and water bottle"
CartAgent: "Added 2 items. Cart total: $54.98"

User: "What's in my cart?"
CartAgent: "Your cart: Yoga Mat ($24.99), Water Bottle ($29.99). Total: $54.98"

Implementation Requirements

Technology Stack

Language: Python 3.9+
Agent Framework: A2A (Agent-to-Agent)
UI Framework: Gradio 4.0+
State Management: In-memory dictionary (extensible to Redis/DB)
Testing: pytest for unit tests, pytest-asyncio for agent tests

Project Structure

ecommerce-multiagent/
├── agents/
│   ├── __init__.py
│   ├── master_agent.py
│   ├── search_agent.py
│   ├── cart_agent.py
│   ├── checkout_agent.py
│   └── order_status_agent.py
├── tools/
│   ├── __init__.py
│   ├── search_products.py
│   ├── add_to_cart.py
│   ├── checkout.py
│   └── get_order_status.py
├── data/
│   ├── __init__.py
│   ├── products.py          # Product catalog
│   └── state_manager.py     # State management
├── ui/
│   ├── __init__.py
│   └── gradio_app.py        # Gradio interface
├── tests/
│   ├── test_agents.py
│   ├── test_tools.py
│   └── test_integration.py
├── requirements.txt
├── README.md
└── main.py                  # Entry point

Dependencies

a2a-framework>=1.0.0
gradio>=4.0.0
pydantic>=2.0.0
pytest>=7.0.0
pytest-asyncio>=0.21.0

Installation and Setup

Clone repository
Install dependencies: pip install -r requirements.txt
Run application: python main.py
Access UI at http://localhost:7860

Configuration

Create config.yaml:

agents:
  master:
    name: "Master eCommerce Agent"
    model: "gpt-4"  # or claude-3-opus, etc.
  
  search:
    name: "Search Agent"
    model: "gpt-4"
    max_results: 10
  
  cart:
    name: "Cart & Checkout Agent"
    model: "gpt-4"
  
  order:
    name: "Order Status Agent"
    model: "gpt-4"

ui:
  host: "0.0.0.0"
  port: 7860
  share: false
  debug: true

state:
  storage: "memory"  # Options: memory, redis, sqlite
  session_timeout: 3600

Testing Requirements

Unit Tests

Each tool must have comprehensive unit tests:

def test_search_products_basic():
    """Test basic product search"""
    results = search_products("headphones")
    assert len(results) > 0
    assert results[0]["product_id"] == "ELEC001"

def test_add_to_cart_success():
    """Test successful cart addition"""
    result = add_to_cart("ELEC001", quantity=1)
    assert result["success"] == True
    assert result["cart"]["item_count"] == 1

def test_checkout_empty_cart():
    """Test checkout with empty cart"""
    result = checkout()
    assert result["success"] == False
    assert "empty" in result["message"].lower()

Integration Tests

Test agent coordination:

async def test_search_and_purchase_flow():
    """Test complete search-to-purchase flow"""
    # Search
    search_response = await master_agent.process("find headphones")
    assert "ELEC001" in search_response
    
    # Add to cart
    cart_response = await master_agent.process("add to cart")
    assert "cart" in cart_response
    
    # Checkout
    checkout_response = await master_agent.process("checkout")
    assert "ORD-" in checkout_response

Agent Behavior Tests

Verify correct agent routing:

def test_master_routes_to_search():
    """Verify master routes search queries to Search Agent"""
    intent = master_agent.analyze_intent("show me laptops")
    assert intent["target_agent"] == "SearchAgent"

def test_master_routes_to_cart():
    """Verify master routes cart operations to Cart Agent"""
    intent = master_agent.analyze_intent("add to cart")
    assert intent["target_agent"] == "CartAgent"

Test Coverage Requirements

Minimum 80% code coverage
All tools must have tests for success and error cases
Agent routing logic must be fully tested
State management must be tested for concurrency

User Scenarios

Scenario 1: First-time Browsing

User Goal: Explore products and make first purchase

Steps:

User: "What products do you have?"
Master → Search Agent: Shows categories and featured products
User: "Show me electronics"
Search Agent: Displays all electronics with details
User: "Tell me more about the headphones"
Search Agent: Provides detailed product information
User: "I'll take them"
Master → Cart Agent: Adds to cart
User: "Checkout"
Master → Checkout Agent: Completes purchase
Checkout Agent: Returns order confirmation

Expected Outcome: User successfully browses, selects, and purchases product

Scenario 2: Price-Based Shopping

User Goal: Find affordable products within budget

Steps:

User: "Show me items under $30"
Search Agent: Filters and displays qualifying products
User: "Add the yoga mat and resistance bands"
Cart Agent: Adds both items ($44.98 total)
User: "What's my total?"
Cart Agent: Shows cart summary
User: "Remove the resistance bands"
Cart Agent: Updates cart ($24.99 total)
User: "Checkout with credit card"
Checkout Agent: Processes order

Expected Outcome: User finds budget items, manages cart, completes purchase

Scenario 3: Order Tracking

User Goal: Check status of previous order

Steps:

User: "Where is my order ORD-20260204-0001?"
Master → Order Status Agent: Retrieves order details
Order Status Agent: Shows order status and tracking
User: "When will it arrive?"
Order Status Agent: Provides delivery estimate

Expected Outcome: User gets clear order status information

Scenario 4: Multi-Category Shopping

User Goal: Purchase items from different categories

Steps:

User: "I need workout gear and a coffee maker"
Search Agent: Shows relevant products from both categories
User: "Add the yoga mat, water bottle, and coffee maker"
Cart Agent: Adds 3 items from 2 categories
User: "Checkout"
Checkout Agent: Processes multi-category order

Expected Outcome: Seamless cross-category shopping experience

Success Criteria

Functional Success Criteria

SC-001: Users can search for products using natural language queries and receive relevant results in under 2 seconds
SC-002: Users can add products to cart and receive immediate confirmation with updated cart total
SC-003: Users can complete checkout with any supported payment method and receive order confirmation
SC-004: Users can check order status using order ID and receive current status information
SC-005: Master agent correctly routes 100% of requests to appropriate specialized agent
SC-006: System maintains cart state across multiple interactions within a session
SC-007: All tool operations return results within 1 second under normal load

Quality Success Criteria

SC-008: Agent responses are natural and conversational, not robotic
SC-009: Error messages are user-friendly and actionable
SC-010: UI loads in under 3 seconds on standard broadband
SC-011: System handles concurrent users without state corruption
SC-012: Agent routing decisions are logged for debugging and analysis

User Experience Success Criteria

SC-013: 90% of users can complete a purchase in under 5 minutes
SC-014: Users receive helpful guidance when queries are ambiguous
SC-015: Cart updates are reflected immediately in UI
SC-016: Conversation history is preserved for session duration

Error Handling

Tool-Level Errors

Each tool must handle and return errors gracefully:

{
    "success": false,
    "message": "Clear error description",
    "error_code": "PRODUCT_NOT_FOUND",  # Optional
    "suggested_action": "Try searching for a different product"  # Optional
}

Agent-Level Errors

Agents should catch tool errors and provide user-friendly responses:

# Instead of showing raw error
"Error: Product ELEC999 not found"

# Agent response
"I couldn't find that product. Would you like me to search for similar items?"

System-Level Errors

Master agent handles routing failures:

# If sub-agent unavailable
"I'm having trouble with the search function right now. Please try again in a moment."

# If ambiguous intent
"I'm not sure if you want to search for products or check an order. Could you clarify?"

Error Recovery

Retry Logic: Failed tool calls retry once automatically
Graceful Degradation: If specialized agent fails, master provides basic assistance
State Preservation: Errors don't corrupt cart or order state
User Notification: Users are always informed when something goes wrong

Performance Requirements

Response Time: Agent responses in under 2 seconds for 95% of requests
Tool Execution: All tools execute in under 1 second
Concurrent Users: Support at least 10 concurrent sessions without degradation
Memory Usage: Total system memory under 500MB for base deployment
Startup Time: Application ready to serve requests in under 10 seconds

Security Considerations

While this is an example implementation, consider:

Input Validation: All tool inputs validated for type and range
SQL Injection Prevention: Use parameterized queries if database added
Session Isolation: Each user session has isolated state
Rate Limiting: Prevent abuse through excessive requests
Payment Security: Simulated payments only - never handle real payment data

Future Enhancements

Potential expansions for this example:

Additional Agents:
- Product Recommendation Agent
- Customer Support Agent
- Inventory Management Agent
Advanced Features:
- Persistent state (database integration)
- User authentication and profiles
- Order history and reordering
- Product reviews and ratings
- Wishlist functionality
Enhanced Tools:
- Advanced search filters (price range, rating)
- Batch operations (add multiple items)
- Order cancellation and returns
- Shipment tracking integration
UI Improvements:
- Product image display
- Rich cart visualization
- Order timeline view
- Mobile-responsive design

Appendix A: Example Interactions

Example 1: Simple Purchase

User: hi
Master: Hello! Welcome to our store. I can help you search for products, manage 
        your cart, complete checkout, or check order status. What can I help you 
        with today?

User: show me electronics
Search Agent: Here are our electronics:

1. Wireless Bluetooth Headphones - $149.99
   Premium noise-cancelling with 30-hour battery
   Stock: 25 units

2. 4K Smart TV 55" - $599.99
   Ultra HD with HDR and streaming apps
   Stock: 15 units

3. Laptop Stand (Aluminum) - $49.99
   Ergonomic adjustable stand
   Stock: 50 units

Would you like more details on any of these?

User: add the headphones
Cart Agent: Great choice! I've added the Wireless Bluetooth Headphones to your cart.

Cart Summary:
- Wireless Bluetooth Headphones x1 - $149.99
Total: $149.99

Ready to checkout?

User: yes checkout with paypal
Checkout Agent: Perfect! Processing your order with PayPal...

✓ Order Confirmed!
Order ID: ORD-20260204-0001
Total: $149.99
Payment: PayPal
Status: Pending

Your order is being processed. You can check its status anytime by asking 
about order ORD-20260204-0001.

Example 2: Price Comparison

User: what's your cheapest product?
Search Agent: Our most affordable product is the Resistance Bands Set at $19.99.

It's a complete set with 5 different tension levels and a door anchor, 
perfect for home workouts. We have 85 units in stock.

Would you like to know more about it or see other budget-friendly options?

User: show me everything under $30
Search Agent: Here are all products under $30:

1. Resistance Bands Set - $19.99 (Sports & Outdoors)
2. Yoga Mat (6mm) - $24.99 (Sports & Outdoors)
3. Water Bottle (32oz) - $29.99 (Sports & Outdoors)

All are in stock and ready to ship!

User: add all three
Cart Agent: Added 3 items to your cart:

- Resistance Bands Set x1 - $19.99
- Yoga Mat (6mm) x1 - $24.99
- Water Bottle (32oz) x1 - $29.99

Cart Total: $74.97

Would you like to proceed to checkout?

Example 3: Order Tracking

User: check order ORD-20260204-0001
Order Status Agent: Order Details for ORD-20260204-0001:

Status: Shipped 📦
Items:
- Wireless Bluetooth Headphones x1 - $149.99

Total: $149.99
Payment: PayPal
Ordered: Feb 4, 2026
Tracking: TRACK-98765432

Your package is on its way! Expected delivery: Feb 6, 2026

User: when exactly will it arrive?
Order Status Agent: Based on the tracking information, your order is currently 
in transit and should arrive by end of day on February 6, 2026.

The carrier typically delivers between 9 AM and 8 PM. You can track your 
package in real-time using tracking number: TRACK-98765432

Appendix B: Agent Prompt Templates

Master Agent System Prompt

You are the Master eCommerce Agent, responsible for coordinating specialized 
agents to help customers shop.

Your sub-agents:
1. SearchAgent - Product search and discovery
2. CartAgent - Cart management
3. CheckoutAgent - Purchase completion  
4. OrderStatusAgent - Order tracking

ROUTING RULES:
- Product queries (search, browse, find) → SearchAgent
- Cart operations (add, remove, view cart) → CartAgent
- Purchase operations (checkout, buy, pay) → CheckoutAgent
- Order inquiries (status, tracking, where is) → OrderStatusAgent
- Greetings and general help → Respond directly

IMPORTANT:
- Never execute eCommerce operations yourself
- Always delegate to the appropriate specialized agent
- Provide clear guidance if user intent is unclear
- Maintain friendly, helpful tone
- Keep responses concise

When routing, pass full context to the sub-agent.

Search Agent System Prompt

You are the Search Agent, specialized in helping customers find products.

Your tools:
- search_products(query, category, max_results)

Guidelines:
1. Use search_products for all product queries
2. Present results clearly with prices and availability
3. Highlight key product features
4. Ask clarifying questions for vague searches
5. Suggest alternatives if no matches found
6. Mention categories when relevant

Format product listings clearly:
- Product name and price
- Brief description
- Stock status

Be enthusiastic about products but honest about limitations.

Cart Agent System Prompt

You are the Cart Agent, managing shopping cart operations.

Your tools:
- add_to_cart(product_id, quantity)

Guidelines:
1. Confirm each item added with updated total
2. Validate products exist before adding
3. Show clear cart summaries when requested
4. Handle quantity updates gracefully
5. Warn if stock is limited
6. Suggest checkout when cart has items

Always show:
- Item names and quantities
- Individual prices
- Cart total

Be encouraging about purchases but don't be pushy.

Checkout Agent System Prompt

You are the Checkout Agent, handling purchase completion.

Your tools:
- checkout(payment_method)

Guidelines:
1. Validate cart is not empty before checkout
2. Support all payment methods: credit_card, debit_card, paypal, apple_pay
3. Confirm order details before processing
4. Provide clear order confirmation with order ID
5. Explain next steps after purchase
6. Handle errors gracefully

Always include in confirmations:
- Order ID
- Total amount
- Payment method
- Order status
- What happens next

Be clear and reassuring during checkout.

Order Status Agent System Prompt

You are the Order Status Agent, tracking customer orders.

Your tools:
- get_order_status(order_id)

Guidelines:
1. Look up orders by order ID
2. Explain status clearly: pending, processing, shipped, delivered
3. Provide tracking numbers when available
4. Give delivery estimates when applicable
5. Handle order not found gracefully
6. Suggest contacting support for complex issues

Status explanations:
- Pending: Payment processing
- Processing: Preparing shipment
- Shipped: In transit
- Delivered: Received

Be clear and proactive with order information.

Appendix C: Testing Checklist

Pre-Deployment Testing

Deployment Checklist

Version History

v1.0 (2026-02-04): Initial specification
- Defined 4-agent architecture
- Specified 10 product catalog
- Documented 4 tools with A2A integration
- Defined Gradio UI requirements
- Established success criteria and testing requirements

License

This specification is provided as an example for educational purposes. Implementations may use any license appropriate for their use case.

Contact & Support

For questions about this specification:

Create an issue in the project repository
Refer to A2A framework documentation
Consult Gradio documentation for UI questions

End of Specification

FilesExpand file tree

ECOMMERCE_MULTIAGENT_SPEC.md

Latest commit

History

ECOMMERCE_MULTIAGENT_SPEC.md

File metadata and controls

Multi-Agent eCommerce System Specification

Overview

Purpose

Core Principles

System Architecture

Agent Hierarchy

Agent Definitions

1. Master eCommerce Agent

2. Search Agent

3. Cart & Checkout Agent

4. Order Status Agent

Product Catalog

Electronics

Home & Garden

Sports & Outdoors

Tool Specifications

1. search_products

2. add_to_cart

3. checkout

4. get_order_status

A2A Framework Integration

Agent Configuration

Agent Communication Protocol

State Management

Gradio UI Specification

Interface Layout

Gradio Implementation Structure

UI Behavior

Example User Flows in UI

Implementation Requirements

Technology Stack

Project Structure

Dependencies

Installation and Setup

Configuration

Testing Requirements

Unit Tests

Integration Tests

Agent Behavior Tests

Test Coverage Requirements

User Scenarios

Scenario 1: First-time Browsing

Scenario 2: Price-Based Shopping

Scenario 3: Order Tracking

Scenario 4: Multi-Category Shopping

Success Criteria

Functional Success Criteria

Quality Success Criteria

User Experience Success Criteria

Error Handling

Tool-Level Errors

Agent-Level Errors

System-Level Errors

Error Recovery

Performance Requirements

Security Considerations

Future Enhancements

Appendix A: Example Interactions

Example 1: Simple Purchase

Example 2: Price Comparison

Example 3: Order Tracking

Appendix B: Agent Prompt Templates

Master Agent System Prompt

Search Agent System Prompt

Cart Agent System Prompt

Checkout Agent System Prompt

Order Status Agent System Prompt

Appendix C: Testing Checklist

Pre-Deployment Testing

Deployment Checklist

Version History

License

Contact & Support