Skip to content

Architecture

The agent suite is four layers. The bottom two already exist.

┌─────────────────────────────────────────────────────────┐
│  4. Surface         Discord brief  +  live dashboard URL  │
├─────────────────────────────────────────────────────────┤
│  3. Agents          Coordinator, Demand, PPC, Pricing     │
│                     (read -> recommend -> [approve] -> act)│
├─────────────────────────────────────────────────────────┤
│  2. Agent runtime   memory, guardrails, tool access,      │
│                     reasoning log, cost tracker           │
├─────────────────────────────────────────────────────────┤
│  1. Data + actions  StickyMetrics warehouse (read)        │
│                     SP-API / Ads API (read + write)       │
└─────────────────────────────────────────────────────────┘

Layer 1: Data and actions (exists)

  • Warehouse: Supabase Postgres (stickymetrics project). Schemas raw, agg, forecasts. See Data Warehouse and Inventory Data Warehouse.
  • Read tables the agents lean on: agg.sales_daily_unified, agg.profit_daily, agg.ad_spend_unified_daily, raw.fba_restock, raw.awd_inventory, raw.inventory_ledger_summary, forecasts.predictions, forecasts.po_recommendations, forecasts.scores, raw.search_query_performance, raw.product_skus, raw.products.
  • Write paths (for action mode): SP-API and Amazon Ads API via the helpers in scripts/lib_sticky.py (sp_api_request, ads_api_request, get_sp_api_creds, get_ads_api_creds). Credentials come from Vaultwarden via vault_read.
  • Nightly refresh: scripts/nightly_refresh.sh already pulls orders, sales, restock, inventory, ad spend, runs the forecast, computes PO recs, and scores. The agents read what it produces; they do not re-pull.

Layer 2: Agent runtime

This is the new infrastructure to build. Reuse the W5 patterns, instantiated fresh and isolated for eComHD.

  • Identity + memory: each agent has a markdown spec (these files) plus persistent memory. Keep memory in the stickymetrics Postgres (a new agents schema) or a file store, isolated from W5 memory.
  • Tool access: read tools = SQL against the warehouse (read-only role). Action tools = scoped SP-API / Ads API calls, each behind the guardrail layer.
  • Reasoning log: every recommendation and action writes a row (input data snapshot, reasoning, confidence, expected dollar impact, outcome). This is both the audit trail and the training signal for calibration. Mirror forecasts.scores / forecasts.calibration_log, which already do this for the demand model.
  • Cost tracker: per-agent LLM spend, surfaced in the brief.

Layer 3: Agents

Each agent: pull its slice of the warehouse, produce recommendations with dollar impact, and (once trusted) execute through guarded action tools. The coordinator runs them and assembles the brief. Cross-agent coordination is the point: when Demand flags a stockout, PPC pauses that ASIN's ads. Specs per agent in the sidebar.

Layer 4: Surface

  • Discord for the daily brief and approval prompts (Discord is the standing channel; Slack is deprecated here).
  • Live dashboard published to Cloudflare Pages (same pattern as this docs site) showing current recommendations, the reasoning log, and per-agent status, at a URL Ace can open.

Build order

  1. v1 Overnight Brief: read-only, assembles recommendations from existing data. No writes, no risk.
  2. Add the runtime pieces (reasoning log table, cost tracker, memory) as the brief needs them.
  3. Add action mode one domain at a time (PPC first, then pricing), each gated by Guardrails.