agentstore

A multi-agent e-commerce assistant built on LangGraph and Claude.

agentstore turns natural-language questions about a retail business — revenue, inventory, customer reviews, top spenders — into accurate, tool-grounded answers. A supervisor agent routes each question to one of four specialist agents, each with its own focused toolset against the store's data.

---

Why this exists

Most LangGraph tutorials show a single ReAct agent or a toy two-node graph. Real systems usually want specialist agents with narrow toolsets routed by a supervisor — better grounding, simpler prompts, easier debugging. agentstore is a clean, production-shaped reference implementation of that pattern over a concrete domain (e-commerce analytics) so you can fork it and swap in your own data and tools.

Architecture

flowchart LR
U([User]) --> S[Supervisor<br/>structured-output router]
S -- sales --> A1[Sales Analyst<br/>revenue, profit, trends]
S -- inventory --> A2[Inventory Analyst<br/>stock, low-stock alerts]
S -- reviews --> A3[Review Analyst<br/>ratings, return reasons]
S -- customer --> A4[Customer Analyst<br/>VIPs, history, geo]
S -- FINISH --> E([Answer])
A1 --> S
A2 --> S
A3 --> S
A4 --> S
A1 -.uses.-> T1[(sales_tools)]
A2 -.uses.-> T2[(inventory_tools)]
A3 -.uses.-> T3[(review_tools)]
A4 -.uses.-> T4[(customer_tools)]

Loading

Key design choices

Choice	Why
Supervisor uses with_structured_output	Routing is enum-constrained Pydantic — the LLM physically cannot return a free-form string, so the graph never wedges on an unknown destination.
Each specialist owns its toolset	Smaller prompts, fewer tool-selection mistakes, cleaner ownership. Add a tool to tools/sales_tools.py and only the sales agent sees it.
RECURSION_LIMIT = 8	Hard cap on supervisor↔worker hops per request — bounds cost and latency even if the LLM keeps trying to re-route.
@lru_cache on data loaders	The JSON dataset loads once per process; tests can call data.reset_cache() to mutate fixtures cleanly.
No DB in the demo	Easier to fork and adapt. Real deployments should swap agentstore/data.py for a database client; nothing else changes.

Quickstart

git clone https://github.com/devthedevil/agentstore.git
cd agentstore
python -m venv .venv &&source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
# Edit .env and set ANTHROPIC_API_KEY=sk-ant-...# CLI smoke test
python -m agentstore.cli "What were our total sales and profit?"# Or run the server + UI
uvicorn agentstore.server:app --reload --port 8000
# open http://localhost:8000

Docker

docker build -t agentstore .
docker run --rm -p 8000:8000 \
-e ANTHROPIC_API_KEY=sk-ant-... \
agentstore

Try these queries

Question	Routes to
What was our total revenue and profit margin?	sales
Which products are running low on stock?	inventory
What are the top 3 reasons customers return items?	reviews
Who are our top 5 customers by spend?	customer
Which category sold the most in the last 12 months?	sales
Tell me about customer #1's order history	customer

Project layout

agentstore/
├── agentstore/
│ ├── config.py # Env-loaded Settings, lazy singleton
│ ├── llm.py # ChatAnthropic factory (cached)
│ ├── data.py # Demo dataset loaders + lookup helpers
│ ├── state.py # TypedDict graph state schema
│ ├── supervisor.py # Routing node + conditional-edge function
│ ├── graph.py # StateGraph wiring + compile
│ ├── server.py # FastAPI app: /api/chat, /api/health, /
│ ├── cli.py # `python -m agentstore.cli "..."`
│ ├── agents/ # 4 specialist worker agents
│ │ ├── _factory.py # Shared ReAct → graph-node builder
│ │ ├── sales.py
│ │ ├── inventory.py
│ │ ├── reviews.py
│ │ └── customer.py
│ └── tools/ # Tools grouped by specialist
│ ├── sales_tools.py
│ ├── inventory_tools.py
│ ├── review_tools.py
│ └── customer_tools.py
├── data/ # Demo e-commerce dataset (JSON)
├── frontend/index.html # Single-page chat UI (no build step)
├── tests/ # Unit + topology + HTTP tests
├── Dockerfile
├── pyproject.toml
└── requirements.txt

Extending agentstore

Add a new specialist agent

1. Create agentstore/tools/<domain>_tools.py — a list of @tool-decorated functions and export XYZ_TOOLS.
2. Create agentstore/agents/<domain>.py — call build_worker(name, system_prompt, XYZ_TOOLS).
3. Add the name to AgentName in agentstore/state.py.
4. Register the node in agentstore/graph.py and add it to the conditional-edge map.
5. Mention the new specialist in supervisor.py's SUPERVISOR_PROMPT.

Swap the dataset for a database

Replace the loader functions in agentstore/data.py (e.g. products(), orders()) with calls to your DB client. Tools call only those accessors, so nothing else has to change.

Swap Claude for another LLM

Edit agentstore/llm.py to return a different LangChain BaseChatModel. Every agent and the supervisor go through that single factory, so the swap is a one-file change. Worth noting: the supervisor relies on with_structured_output(Route), so the chosen model must support structured output (most current LLMs do via LangChain).

Development

pip install -e ".[dev]"
ruff check agentstore tests # lint
pytest # run tests
pytest --cov=agentstore # with coverage

The CI workflow (.github/workflows/ci.yml) runs lint + tests against Python 3.11 and 3.12 on every push and PR.

License

MIT — see LICENSE.

Acknowledgements

• LangGraph for the graph runtime.
• Anthropic Claude for the underlying LLM.
• Demo dataset adapted from a sibling project (AskMyStore).