multi-agent-ecommerce-system: a Supervisor orchestrator for recommendation, copy and stock

A Supervisor drives the flow instead of agents handing off

The orchestration choice is stated up front. The project uses a Supervisor pattern, where one coordinating component calls each agent and then aggregates the results, rather than a handoff chain in which agent A passes work to agent B and B to C. The README argues the choice explicitly: a Supervisor gives centralised control, a clear flow, parallel execution and unified error handling, while handoffs are decentralised and flexible but make state management hard. For a recommendation request the Supervisor is the single entry point, and the request itself is simple, a user_id and a num_items value. The decomposition is into phases: two agents run in parallel, then two more run in parallel, then the aggregation and copy steps run serially. That structure is the real content of this repository, more than any individual agent, since it is the orchestration pattern that the project is teaching.

Phase one pairs live behaviour features with multi-route recall

The first parallel phase pairs two agents. The user profile agent turns historical behaviour such as clicks, purchases and favourites into a structured profile. It reads real-time behaviour features from a Redis feature store and asks an LLM to produce a JSON profile containing segments and an RFM score, where RFM is recency times frequency times monetary value. The underlying storage is a Redis sorted set written with ZADD on a per-user key, which supports sliding window queries, and the segment taxonomy has five classes including new customers, VIP, price sensitive, active and churn risk. The recommendation agent works from the other direction, retrieving a wide candidate set through several recall routes: collaborative filtering, vector search over Milvus for semantically similar items, a popularity strategy covering the last seven days, and a new-arrival strategy for items listed within thirty days. Those candidates are deduplicated and merged before any ranking happens.

Phase two reranks with an LLM and filters on real stock

The second phase runs an LLM rerank agent and an inventory agent at the same time. The rerank agent calls the recommendation model again, this time with the user profile crossed with product attributes, and asks for a TopN ordering, such as sorting ten items for a price sensitive user who prefers phone accessories. The inventory agent queries MySQL for live stock, removes anything out of stock, and emits a purchase limit policy alongside the filter result. Running the two in parallel is the interesting decision: the rerank agent does not need to know about stock to produce a ranking, and the stock filter does not need to know the ranking to remove unavailable items. The cost is that out-of-stock items are removed after the LLM has already paid for ranking them, so an aggressive limit strategy such as ten candidates means real tokens spent on products that never reach the user.

The aggregator and copy agent run strictly in order

Phase three is serial, and the ordering matters. A result aggregator applies the inventory filter, merges and sorts the surviving items, and cuts them to TopN. Only then does the marketing copy agent run, because the copy is written about the specific products that survived. That agent picks one of five prompt styles based on the user's segment, calls the LLM to generate the text, and then runs a compliance check against advertising law rules. The prompt set is keyed by segment, with distinct copy for new users, VIP customers and the rest, and each prompt interpolates product and discount or price fields. Compliance validation on generated marketing text is a check the README lists explicitly, and it is the one part of the pipeline that treats the LLM output as untrusted. The response then returns the product list, the personalised copy and the experiment group the user was placed in.

The A/B engine buckets by user id and tunes with Thompson Sampling

Ranking is separated from experimentation by a dedicated engine at the end of the flow. Users are assigned to buckets by hashing their user id, which makes assignment deterministic and stable across requests without a separate lookup table, and the engine applies Thompson Sampling for dynamic tuning. The point of that design is that the served copy and the served ranking can be measured continuously rather than through a fixed, manually tuned split. The README lists Thompson Sampling and A/B testing among the technologies this project is meant to demonstrate, alongside Redis as the feature store and RAG and ReAct as agent patterns. That framing matters for judging the code: this is a portfolio of patterns, and the experimentation layer exists to show a complete pipeline rather than to solve a measurement problem that a real store would define differently.

docker compose brings up the API, Redis, Milvus and MySQL

The compose file at the root defines four services and a shared set of volumes. The api service builds from the ./python directory and publishes port 8000, and it takes the LLM key, base URL and model name from environment variables alongside the storage settings:

    environment:
      - ECOM_REDIS_URL=redis://redis:6379/0
      - ECOM_MILVUS_HOST=milvus
      - ECOM_DATABASE_URL=sqlite:///./ecommerce.db

The remaining services are the pieces the agents read from. Redis is the feature store, run from the redis:7-alpine image with appendonly enabled and a named volume. Milvus is the vector database in standalone mode, with ETCD_USE_EMBED set and local storage. MySQL holds the business data. Each of those services publishes its standard port, 6379, 19530 and 3306 respectively, and each has restart: unless-stopped. The one inconsistency to notice is the database setting: the api service points ECOM_DATABASE_URL at a local SQLite file even though a MySQL service is defined and running alongside it, so you must change that line before you expect inventory data to come from MySQL.

A teaching project in three languages, last pushed in April

The repository carries python/, java/ and go/ directories for the same design, and the badges state Python 3.11+, Java 17+ and Go 1.22+. It also carries plan.md, a docs/ directory, and interview notes: the README is written in Chinese and presents the project as an enterprise style agent build meant to teach multi-agent architecture from zero, with a curated question bank, resume phrasing and STAR phrasing for interviews. That framing tells you how to read the code, because the emphasis is on explaining each step rather than on production hardening. No licence identifier is listed for the repository, even though the README badge says MIT, and there are no GitHub releases. The last push was on 2026-04-05 and the project is not archived, so it is not abandoned, but nothing in the history suggests a scheduled release train either.

Editorial conclusion

Use this repository if you want a readable, end to end view of Supervisor style multi-agent orchestration with a real recall, rerank, inventory and experimentation pipeline, or if you are preparing interviews around LangGraph patterns. Do not adopt it as production commerce infrastructure: there is no release history, the last push was on 2026-04-05, no licence identifier is listed for the repository even though the README shows an MIT badge, and the compose file still defaults ECOM_DATABASE_URL to a local SQLite file while shipping a MySQL service. Verify first that the LLM provider, Redis, Milvus and MySQL instances you point ECOM_LLM_BASE_URL, ECOM_REDIS_URL, ECOM_MILVUS_HOST and ECOM_DATABASE_URL at are reachable, then read the docker-compose.yml services block to decide which of the two database defaults you actually want.

Frequently asked questions

Official sources

1. bcefghj/multi-agent-ecommerce-system on GitHub
2. Issues
3. README