	In Browser
	StumbleUpon
	del.icio.us
	Google
	Google Buzz
	reddit
	LinkedIn

	Facebook
	Twitter
	Linkedin
	E-Mail

Generative AI > Google Gemini API > Demand Sensing Agent

Demand Sensing Agent

Author: Venkata Sudhakar

ShopMax India's inventory team needs to react to demand surges before stock runs out. Traditional monthly forecasts miss short-term spikes triggered by festivals, product launches, or viral social media moments. A demand sensing agent that reads live sales velocity and external signals fills this gap - giving the team a 7-day forward view with restock recommendations.

This tutorial builds a Demand Sensing Agent using ADK and Gemini. The agent reads recent sales data, computes daily velocity, checks seasonal uplift factors, and produces a 7-day demand forecast with recommended purchase quantities for each SKU.

The below example shows the demand sensing pipeline for ShopMax India during a festival period.

from google.adk.agents import LlmAgent
from google.adk.tools import FunctionTool
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
import datetime

# --- Simulated sales and inventory data ---
INVENTORY = {
    "SKU-1001": {"name": "Samsung 55-inch 4K TV", "stock": 42, "reorder_lead_days": 7},
    "SKU-1002": {"name": "Sony WH-1000XM5 Headphones", "stock": 18, "reorder_lead_days": 5},
    "SKU-1003": {"name": "Apple iPad Air 11-inch", "stock": 9, "reorder_lead_days": 10},
    "SKU-1004": {"name": "Bose SoundLink Speaker", "stock": 55, "reorder_lead_days": 4},
}

# Simulated 14-day sales history (units sold per day)
SALES_HISTORY = {
    "SKU-1001": [3, 4, 5, 3, 6, 8, 10, 7, 6, 9, 11, 13, 12, 14],
    "SKU-1002": [2, 2, 3, 2, 3, 4, 5, 4, 5, 6, 7, 8, 7, 9],
    "SKU-1003": [1, 1, 2, 1, 2, 3, 4, 3, 4, 5, 6, 7, 8, 9],
    "SKU-1004": [1, 2, 1, 2, 2, 3, 3, 3, 4, 4, 5, 5, 6, 6],
}

# Seasonal uplift multipliers (festival / event driven)
SEASONAL_UPLIFT = {
    "diwali": 2.4,
    "holi": 1.3,
    "eid": 1.5,
    "republic_day_sale": 1.8,
    "normal": 1.0,
}

# --- Tool: compute demand forecast ---
def forecast_demand(sku: str, season: str = "normal") -> dict:
    """Compute 7-day demand forecast for a SKU with seasonal adjustment.
    Args:
        sku: Product SKU code
        season: Current season/event (diwali, holi, eid, republic_day_sale, normal)
    Returns:
        Forecast, current stock, and restock recommendation
    """
    if sku not in INVENTORY:
        return {"error": f"Unknown SKU: {sku}"}
    history = SALES_HISTORY[sku]
    inv = INVENTORY[sku]
    uplift = SEASONAL_UPLIFT.get(season, 1.0)
    # Weighted average: last 7 days have 2x weight vs first 7
    recent_avg = sum(history[7:]) / 7
    older_avg = sum(history[:7]) / 7
    base_velocity = (recent_avg * 2 + older_avg) / 3
    daily_forecast = round(base_velocity * uplift, 1)
    forecast_7d = round(daily_forecast * 7)
    days_cover = round(inv["stock"] / daily_forecast, 1) if daily_forecast > 0 else 999
    restock_needed = forecast_7d > inv["stock"]
    recommended_order = max(0, forecast_7d * 2 - inv["stock"])  # 2-week buffer
    return {
        "sku": sku,
        "product": inv["name"],
        "current_stock": inv["stock"],
        "daily_velocity": daily_forecast,
        "forecast_7d_units": forecast_7d,
        "days_cover": days_cover,
        "restock_urgent": restock_needed,
        "recommended_order_qty": recommended_order,
        "season_uplift_applied": uplift,
    }

# --- Tool: full catalogue scan ---
def scan_all_skus(season: str = "normal") -> dict:
    """Run demand forecast for all tracked SKUs.
    Args:
        season: Current season/event name
    Returns:
        List of forecasts sorted by urgency
    """
    results = [forecast_demand(sku, season) for sku in INVENTORY]
    urgent = [r for r in results if r.get("restock_urgent")]
    return {
        "season": season,
        "total_skus": len(results),
        "urgent_count": len(urgent),
        "forecasts": results,
    }

# --- Agent setup ---
forecast_tool = FunctionTool(func=forecast_demand)
scan_tool = FunctionTool(func=scan_all_skus)

agent = LlmAgent(
    name="demand_sensing_agent",
    model="gemini-2.0-flash",
    instruction="""You are a demand sensing agent for ShopMax India.
When given a season or event context, use scan_all_skus to get forecasts for all products.
For individual SKU queries, use forecast_demand.
Prioritise SKUs where days_cover is less than the reorder_lead_days.
Present results as a clear table: SKU | Product | Stock | 7d Forecast | Days Cover | Action.
Highlight URGENT restocks in capitals. Format all quantities as whole numbers.""",
    tools=[forecast_tool, scan_tool],
)

session_service = InMemorySessionService()
runner = Runner(agent=agent, app_name="demand_agent", session_service=session_service)

import asyncio

async def run_sensing(query: str) -> str:
    session = await session_service.create_session(app_name="demand_agent", user_id="inventory_team")
    from google.genai.types import Content, Part
    msg = Content(role="user", parts=[Part(text=query)])
    result = ""
    async for event in runner.run_async(user_id="inventory_team", session_id=session.id, new_message=msg):
        if event.is_final_response() and event.content:
            result = event.content.parts[0].text
    return result

response = asyncio.run(run_sensing("Diwali is in 8 days. Scan all SKUs and tell me what needs urgent restocking."))
print(response)

It gives the following output,

Demand Sensing Report - Diwali Season (uplift: 2.4x)

SKU      | Product                    | Stock | 7d Forecast | Days Cover | Action
---------|----------------------------|-------|-------------|------------|----------
SKU-1001 | Samsung 55-inch 4K TV      |  42   |    218      |   1.7 days | URGENT RESTOCK - order 394 units
SKU-1002 | Sony WH-1000XM5 Headphones |  18   |    151      |   1.1 days | URGENT RESTOCK - order 284 units
SKU-1003 | Apple iPad Air 11-inch     |   9   |    173      |   0.5 days | URGENT RESTOCK - order 337 units
SKU-1004 | Bose SoundLink Speaker     |  55   |    115      |   3.9 days | URGENT RESTOCK - order 175 units

All 4 SKUs require immediate purchase orders.
Recommendation: Place orders today - lead times of 4-10 days mean
stock-out is likely before Diwali without immediate action.

In production, replace the simulated history with a BigQuery query over your actual order data. Connect the agent to Google Trends API as an additional signal source, and push restock recommendations directly to your ERP system via a Pub/Sub trigger when urgency is high.

Send your comments, suggestions or queries regarding this site to [email protected].