Building a Multi-Agent E-Commerce Platform: The Complete Guide

Most AI agent tutorials end at “hello world.” You build a single agent with one or two tools, it answers a few questions, and that is it. The gap between that tutorial and a production system with multiple agents, authentication, observability, and a real frontend is enormous.

This series closes that gap.

We build ECommerce Agents, a working e-commerce platform powered by six AI agents that collaborate across product search, order management, pricing, reviews, inventory, and customer support. It is not a toy demo. It runs on real data with real production concerns wired in, and it ships two complete backends, Python and .NET / C#, behind one frontend.

This page is the index to two series written against it. The 28-chapter MAF v1: Python and .NET series is the current one and covers both languages. The original 12-part series below is the Python-only walkthrough that came first, and it is still the best narrative account of why the system is shaped the way it is.

The entire codebase is open source: github.com/nitin27may/e-commerce-agents

Clone it. Run ./scripts/dev.sh --demo. You have six agents, a database, Redis, a telemetry dashboard, and a chat frontend running locally in about a minute.

What We Build

The platform has six agents, each responsible for a specific domain:

Agents communicate via the A2A (Agent-to-Agent) protocol, the open standard for agent interoperability. Each agent runs as an independent FastAPI service with its own A2A endpoint. The orchestrator is the only agent users interact with; it classifies intent, routes to the right specialist, and synthesizes coherent responses.

The Tech Stack

• Python 3.12 and .NET 10 / C#: two complete implementations of the same six agents
• Microsoft Agent Framework (MAF): agent SDK with @tool decorator, Annotated type hints, and ContextProvider
• FastAPI: HTTP layer for each agent
• PostgreSQL 16 + pgvector: products, orders, users, reviews, inventory, and vector embeddings for semantic search
• Redis 7: caching for product catalogs and session state
• Next.js 16: frontend with React 19, Tailwind CSS, shadcn/ui, and interactive chat cards
• OpenTelemetry: distributed tracing across all six agents
• .NET Aspire Dashboard: trace, metric, and log visualization
• Docker Compose: one-command start, with ten released images published to GitHub Container Registry
• A2A Protocol: standardized agent-to-agent communication
• JWT + RBAC, with an optional self-hosted OAuth2 authorization server: four roles (customer, power_user, seller, admin)

Why this exists

I built ECommerce Agents because the tutorials I found all had the same problem: they showed isolated concepts without connecting them into a working system. You could find an article about tool calling, another about prompt engineering, another about multi-agent orchestration, but nothing that showed how those pieces fit together in a single runnable codebase with production concerns addressed.

Every chapter references specific files in the repository, so you read the explanation and then open the code. And because the repository keeps moving, one rule holds throughout: the repo and its documentation site are canonical. Where a post and the code disagree, the code is right, and the post has a correction on it.

Start here

Three routes in, depending on where you are starting from.

Never built an agent. Go to Chapter 00: Setup, then work forward. The first three chapters get you from an empty folder to an agent that calls a tool, in whichever language you picked.

Comfortable with agents, want the whole system. Skip to Chapter 21: the repo guided tour. It locates every concept in the running application and names the file. Double back to any chapter it mentions that you do not recognise.

On .NET, and want to know whether MAF is real on your stack. Read Chapter 22: Python and .NET asymmetries first. It is the honest list of what maps across, what does not, and what is Python-only. Then start at Chapter 00.

The curriculum: MAF v1, in Python and C#

28 chapters. Every one that ships code ships both languages, and every one is tested in CI, so the code behind the writing cannot drift without something going red.

Fundamentals (00 to 08)

Workflow primitives (09 to 11)

The five orchestration patterns (12 to 16)

Production concerns (17 to 20c)

The capstone and the appendices (21 to 25)

The original series: the Python-only walkthrough

These twelve came first. They are Python-only, and each one now carries a pointer to its revised chapter above. They are kept because the narrative is better: this is the version that explains why the system ended up shaped the way it is, rather than how each piece works.

Foundation (Parts 1-3)

Part 1: AI Agents: Concepts and Your First Implementation The mental model and the first working agent in one sitting. It draws the line between chatbot, assistant, and agent, names the four properties that make a system “agentic,” then goes hands-on with MAF: the @tool decorator, Annotated type hints, multi-turn conversations, and the tool-calling loop traced in a sequence diagram.

Part 2: Prompt Engineering for AI Agents The prompt is where most agent hallucinations get fixed or created. This part builds the five-layer prompt (identity, capabilities, grounding, tool guidance, output format), then makes it maintainable with YAML composition and a loader so six agents don’t drift out of sync.

Part 3: Building Domain-Specific Tools Tools are where an agent actually touches your systems. It covers the three shapes that matter (query, action with validate-then-act, and validation with cascading checks), user-scoped data via ContextVars, returning error dicts instead of raising, and testing tools without spending a token on the LLM.

Multi-Agent Architecture (Part 4)

Part 4: Multi-Agent Architecture: Orchestration and the A2A Protocol Orchestration and the protocol underneath it, together, because you can’t reason about one without the other. Part A is the split decision, the orchestrator with a single call_specialist_agent tool, and LLM-as-classifier routing. Part B is the A2A protocol itself: agent cards, the /message:send endpoint, two-layer auth (shared secret plus user identity), and where A2A ends and MCP begins.

Production (Parts 5-7)

Part 5: Observability with OpenTelemetry You can’t debug what you can’t see, and a single multi-agent request hides a lot. This wires OpenTelemetry in one call, auto-instruments httpx/asyncpg/FastAPI, adds custom spans for A2A and tool calls, correlates traces across agents with W3C traceparent, and reads it all in the .NET Aspire Dashboard.

Part 6: Frontend: Rich Cards and Streaming Responses Two frontend upgrades that make the agent feel like a product. First, turning agent text into interactive components (product cards, order timelines, action buttons that feed back into the chat) with a fenced-code-block parser. Then token-by-token streaming through the whole stack: an async generator in the agent host, an SSE endpoint in FastAPI, progressive rendering in the browser, and tool calls handled mid-stream.

Part 7: Production Readiness: Auth, RBAC, and Deployment JWT authentication with access and refresh tokens, four-role RBAC (customer, power_user, seller, admin), user-scoped data via ContextVars, inter-agent shared secret auth, role-aware prompts that change agent behavior per role, and a security checklist. Then: Docker Compose with 11 services and profiles, multi-target Dockerfile (one file, six agents), the dev.sh setup script, and troubleshooting common issues.

Advanced Topics (Parts 8-11)

Part 8: Agent Memory Three types of agent memory (short-term, long-term episodic, semantic), schema design for the agent_memories table with pgvector, store_memory and recall_memories tools, ContextProvider integration for automatic memory injection, two-layer memory (passive + active), privacy considerations, and performance implications.

Part 9: Evaluating Agent Quality Why traditional testing fails for non-deterministic agents. Behavioral assertions instead of exact output matching, three scoring dimensions (groundedness, correctness, completeness), golden datasets, an automated evaluator with weighted scoring, CLI runner, cost tracking, GitHub Actions CI/CD integration, and gotchas around non-determinism.

Part 10: MCP Integration The Model Context Protocol as “USB-C for AI tools.” MCP vs A2A (vertical vs horizontal), building an MCP server with FastAPI, tool manifests and discovery, connecting MAF agents to MCP servers, a decision framework for MCP vs native tools, security considerations, and Docker Compose integration.

Part 11: Graph-Based Workflows When LLM routing is not enough. Deterministic graph-based workflows with dataclass state, a sequential return-and-replace pipeline, a parallel pre-purchase research workflow with asyncio.gather, state management patterns, error handling with early exit, comparing three orchestration approaches, and practical heuristics for when to use which.

Running the Platform Locally

# Clone the repository
git clone https://github.com/nitin27may/e-commerce-agents.git
cd e-commerce-agents

# Copy the minimal environment file and add your OpenAI API key
cp .env.minimal .env
# Edit .env and set OPENAI_API_KEY=sk-...

# Start everything
./scripts/dev.sh --demo

.env.minimal carries one variable, which is all a first run needs. .env.example is the full reference with every switch in it, and is worth reading later rather than first. --demo pulls the released images from GitHub Container Registry instead of building them locally, which is the difference between roughly one minute and roughly twelve; drop the flag to build from source.

This starts all 11 services: six agents, PostgreSQL, Redis, the seeder (which populates test data), the Aspire Dashboard, and the Next.js frontend. Once everything is healthy:

• Frontend: http://localhost:3000
• Orchestrator API: http://localhost:8080
• Aspire Dashboard: http://localhost:18888

Log in with one of the seeded users (credentials are in the README) and start chatting. Ask about products, check order status, apply coupons, read reviews, and the orchestrator routes your questions to the right specialist agent automatically.

Who This Series Is For

This assumes you are comfortable with Python or C#, and have at least a passing familiarity with LLMs and API calls. You do not need prior experience with agent frameworks, multi-agent systems, or the specific tools we use (MAF, FastAPI, pgvector). Each article introduces concepts from the ground up with working code.

If you have built a single-agent chatbot and want to understand what comes next (multiple agents, production concerns, real authentication, real observability), this is the series.

If you are evaluating whether to build a multi-agent system for your organization and want to see what a working reference architecture looks like, start with Part 1 for concepts and Part 7 for deployment, then read the parts relevant to your concerns.

Source Code

Every article references specific files and functions in the repository. The codebase is structured so you can follow along:

e-commerce-agents/
  agents/
    python/                    # The Python backend
      orchestrator/            # Routing agent, and the five orchestration modes
      product_discovery/       # Product search agent
      order_management/        # Order lifecycle agent
      pricing_promotions/      # Pricing and coupons
      review_sentiment/        # Review analysis
      inventory_fulfillment/   # Stock and shipping
      auth_server/             # Optional self-hosted OAuth2 authorization server
      shared/                  # Shared across every agent
        agent_host.py          # A2A-compatible host, MAF-native execution
        auth.py                # JWT, OAuth2 and inter-agent auth
        context.py             # ContextVars for user scoping
        telemetry.py           # OpenTelemetry setup
        prompt_loader.py       # YAML prompt composition
        tools/                 # The shared tool library
      packages/                # Standalone MCP servers (product, inventory)
      evals/                   # Golden datasets, scorers, baselines
      config/prompts/          # YAML prompt configuration
    dotnet/                    # The C# backend, same agents, same schema
  web/                         # Next.js frontend, serves either backend
  tutorials/                   # 34 self-contained chapters, gated in CI
  docs/                        # The documentation site source
  docker-compose.yml           # Python stack
  docker-compose.dotnet.yml    # .NET stack
  scripts/
    dev.sh                     # One-command start
    seed.py                    # Database seeder

Pick a route from Start here and work forward. Chapters build on each other, but each is readable standalone if you want to jump to one topic.

The full source code is at github.com/nitin27may/e-commerce-agents.