AI Agent for Inventory Inquiries: Store Availability, Restock Alerts, and Alternatives

Why Inventory Visibility Matters

When a customer asks "Do you have this in blue, size large?" and does not get an immediate answer, they leave. An inventory inquiry agent provides instant stock checks across all locations, notifies customers when items return to stock, and suggests alternatives for unavailable products — turning a potential lost sale into a conversion.

Building the Inventory Data Layer

The agent needs access to real-time inventory data across all channels: warehouse, stores, and in-transit stock.

flowchart TD
    Q{"What matters most<br/>for your team?"}
    DIM1["Time to first<br/>production deploy"]
    DIM2["Total cost of<br/>ownership at scale"]
    DIM3["Debuggability and<br/>observability"]
    DIM4["Ecosystem and<br/>community support"]
    PICK{Score the<br/>four axes}
    A(["Pick<br/>Option A"])
    B(["Pick<br/>Option B"])
    Q --> DIM1 --> PICK
    Q --> DIM2 --> PICK
    Q --> DIM3 --> PICK
    Q --> DIM4 --> PICK
    PICK -->|Speed and ecosystem| A
    PICK -->|Control and TCO| B
    style Q fill:#4f46e5,stroke:#4338ca,color:#fff
    style PICK fill:#f59e0b,stroke:#d97706,color:#1f2937
    style A fill:#0ea5e9,stroke:#0369a1,color:#fff
    style B fill:#059669,stroke:#047857,color:#fff

from agents import Agent, Runner, function_tool
from typing import Optional

# Simulated multi-location inventory
INVENTORY = {
    "SKU-001": {
        "name": "Merino Wool Jacket",
        "locations": {
            "warehouse-east": {"S": 12, "M": 8, "L": 0, "XL": 5},
            "warehouse-west": {"S": 3, "M": 15, "L": 7, "XL": 2},
            "store-portland": {"S": 0, "M": 2, "L": 1, "XL": 0},
            "store-seattle": {"S": 1, "M": 0, "L": 3, "XL": 1},
        },
        "category": "Outerwear",
        "price": 189.99,
    },
    "SKU-002": {
        "name": "Down Insulated Parka",
        "locations": {
            "warehouse-east": {"S": 0, "M": 0, "L": 0, "XL": 0},
            "warehouse-west": {"S": 0, "M": 0, "L": 0, "XL": 0},
            "store-portland": {"S": 0, "M": 0, "L": 0, "XL": 0},
            "store-seattle": {"S": 0, "M": 0, "L": 0, "XL": 0},
        },
        "category": "Outerwear",
        "price": 249.99,
        "restock_date": "2026-03-25",
    },
}

RESTOCK_SUBSCRIBERS = {}  # {sku: [email, ...]}

@function_tool
def check_stock(sku: str, size: Optional[str] = None,
                location: Optional[str] = None) -> str:
    """Check inventory for a product, optionally filtered by size and location."""
    product = INVENTORY.get(sku)
    if not product:
        return f"Product {sku} not found in catalog."

    results = []
    for loc, sizes in product["locations"].items():
        if location and location.lower() not in loc.lower():
            continue
        for sz, qty in sizes.items():
            if size and sz.upper() != size.upper():
                continue
            if qty > 0:
                results.append(f"  {loc}: {sz} = {qty} units")

    if not results:
        restock = product.get("restock_date", "unknown")
        return (
            f"{product['name']} ({sku}) is out of stock"
            f"{f' in size {size}' if size else ''}"
            f"{f' at {location}' if location else ''}. "
            f"Expected restock: {restock}."
        )

    total = sum(
        qty for loc_sizes in product["locations"].values()
        for sz, qty in loc_sizes.items()
        if (not size or sz.upper() == size.upper())
        and (not location or True)
    )
    header = f"{product['name']} ({sku}) availability:"
    return header + "\n" + "\n".join(results) + f"\nTotal: {total} units"

Restock Alert System

When an item is out of stock, the agent should offer to notify the customer when it returns.

@function_tool
def subscribe_restock_alert(sku: str, email: str,
                            size: Optional[str] = None) -> str:
    """Subscribe a customer to restock notifications."""
    product = INVENTORY.get(sku)
    if not product:
        return "Product not found."

    key = f"{sku}:{size}" if size else sku
    if key not in RESTOCK_SUBSCRIBERS:
        RESTOCK_SUBSCRIBERS[key] = []

    if email in RESTOCK_SUBSCRIBERS[key]:
        return f"You are already subscribed to restock alerts for {product['name']}."

    RESTOCK_SUBSCRIBERS[key].append(email)
    restock_date = product.get("restock_date", "to be determined")
    return (
        f"Restock alert set for {product['name']}"
        f"{f' in size {size}' if size else ''}. "
        f"We will email {email} when it is back in stock. "
        f"Estimated restock date: {restock_date}."
    )

Suggesting Alternatives

When the requested item is unavailable, the agent should proactively suggest similar products that are in stock.

@function_tool
def find_alternatives(sku: str, max_results: int = 3) -> str:
    """Find in-stock alternatives for an unavailable product."""
    product = INVENTORY.get(sku)
    if not product:
        return "Product not found."

    target_category = product["category"]
    target_price = product["price"]
    alternatives = []

    for alt_sku, alt_product in INVENTORY.items():
        if alt_sku == sku:
            continue
        if alt_product["category"] != target_category:
            continue
        total_stock = sum(
            qty for loc in alt_product["locations"].values()
            for qty in loc.values()
        )
        if total_stock == 0:
            continue
        price_diff = abs(alt_product["price"] - target_price)
        alternatives.append({
            "sku": alt_sku,
            "name": alt_product["name"],
            "price": alt_product["price"],
            "total_stock": total_stock,
            "price_diff": price_diff,
        })

    alternatives.sort(key=lambda x: x["price_diff"])
    if not alternatives:
        return "No in-stock alternatives found in the same category."

    lines = [f"Alternatives to {product['name']}:"]
    for alt in alternatives[:max_results]:
        lines.append(
            f"  - {alt['name']} ({alt['sku']}): "
            f"${alt['price']:.2f}, {alt['total_stock']} units available"
        )
    return "\n".join(lines)

Wiring the Inventory Agent

inventory_agent = Agent(
    name="Inventory Assistant",
    instructions="""You help customers check product availability.

    Workflow:
    1. Identify the product, size, and preferred location
    2. Check real-time stock levels
    3. If in stock, confirm availability and offer to help with purchase
    4. If out of stock, offer restock alerts AND suggest alternatives
    5. For store pickup, confirm the nearest location with stock

    Always be transparent about stock levels. Never promise availability
    without checking. If stock is low (under 3 units), mention it so
    the customer can act quickly.""",
    tools=[check_stock, subscribe_restock_alert, find_alternatives],
)

result = Runner.run_sync(
    inventory_agent,
    "Is the Down Insulated Parka available in Medium?",
)
print(result.final_output)

FAQ

How often should inventory data be refreshed?

For warehouse inventory, a 5-minute cache is acceptable. For in-store inventory, real-time point-of-sale integration is ideal but a 15-minute sync is practical. During high-traffic events like flash sales, reduce cache TTL to 30 seconds or implement event-driven updates where inventory changes push updates immediately.

How do I handle inventory discrepancies between the system and physical stock?

Build a confidence indicator into stock responses. If stock is below a threshold (say 3 units), add a disclaimer that availability may vary. For store pickup orders, implement a hold mechanism where the store confirms the item before the customer arrives. Track discrepancy rates by location to identify stores with inventory accuracy issues.

Should the agent show inventory from all locations or just relevant ones?

Default to showing the customer's nearest locations and online-available warehouse stock. Use the customer's shipping address or IP-based geolocation to prioritize nearby stores. For ship-from-store capable retailers, include all locations since any store could fulfill the order, but sort by proximity.

#InventoryManagement #StockAvailability #RetailAI #RestockAlerts #ECommerce #AgenticAI #LearnAI #AIEngineering