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.

Over 12 articles, we build ECommerce Agents, a fully functional e-commerce platform powered by six AI agents that collaborate across product search, order management, pricing, reviews, inventory, and customer support. This is not a toy demo. It runs on real data with real production concerns wired in.

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

Clone it. Run docker compose up. You have six agents, a database, Redis, a telemetry dashboard, and a chat frontend running locally in under five minutes.

The short version

#

• Six specialist agents behind one orchestrator, communicating over the A2A protocol.
• Real data to work against: 50 products, 200 orders, and 20 users across four roles.
• Production concerns built in: JWT auth, RBAC, OpenTelemetry tracing, a Next.js chat frontend, and Docker Compose for one-command deployment.
• Every article maps to specific files and functions in the open-source repo, so you read the explanation and then open the code.

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: all 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 15: 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 deployment of all 11 services
• A2A Protocol: standardized agent-to-agent communication
• JWT + RBAC: authentication with four roles (customer, power_user, seller, admin)

Why This Series Is Different

#

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 all those pieces fit together in a single, runnable codebase with production concerns addressed.

This series walks through every layer of that codebase, from the conceptual foundation of what agents are, through building tools and prompts, to deployment and advanced topics like streaming, memory, evaluation, MCP integration, and graph-based workflows. Each article references specific files and functions in the repository. You can read the article, then open the code and see exactly how it works.

The progression is deliberate:

• Parts 1-3 build the foundation: what agents are and your first implementation, writing prompts that prevent hallucination, and building production-quality tools.
• Part 4 scales to multiple agents: the orchestrator pattern and the A2A protocol for inter-agent communication, covered together because you cannot understand orchestration without understanding the protocol those calls use.
• Parts 5-7 address production concerns: observability with OpenTelemetry, a rich frontend with streaming, and authentication, security, and deployment.
• Parts 8-11 cover advanced topics: agent memory, evaluation frameworks, MCP integration, and graph-based workflows.

The Series

#

Here is the complete series with a summary of what each article covers:

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 environment file and add your OpenAI API key
cp .env.example .env
# Edit .env and set OPENAI_API_KEY=sk-...

# Start everything
docker compose up

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 series assumes you are comfortable with Python 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.

The bottom line

#

• If you take away one thing: the hard part of a multi-agent system isn’t any single agent, it’s the wiring between them (routing, auth, tracing, deployment), and that wiring is most of this series.
• Read it in order to build along, or jump to Part 4 for orchestration and Part 7 for deployment if you’re evaluating the architecture first.

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/
    orchestrator/       # The routing agent (Part 4)
    product_discovery/  # Product search agent (Parts 1, 3)
    order_management/   # Order lifecycle agent (Part 3)
    pricing_promotions/ # Pricing and coupons (Part 3)
    review_sentiment/   # Review analysis (Part 3)
    inventory_fulfillment/ # Stock and shipping (Part 3)
    shared/             # Shared utilities
      agent_host.py     # HTTP host + tool-calling loop (Part 4)
      auth.py           # JWT + shared secret auth (Part 7)
      context.py        # ContextVars for user scoping (Part 3)
      telemetry.py      # OpenTelemetry setup (Part 5)
      prompt_loader.py  # YAML prompt composition (Part 2)
      tools/            # Shared tools across agents (Part 3)
    config/
      prompts/          # YAML prompt configuration (Part 2)
  web/                  # Next.js frontend (Part 6)
  docker-compose.yml    # Full platform deployment (Part 7)
  scripts/
    dev.sh              # One-command setup (Part 7)
    seed.py             # Database seeder (Part 7)

Start with Part 1: AI Agents: Concepts and Your First Implementation and work through the series in order. Each article builds on the previous one, but they are also readable standalone if you want to jump to a specific topic.

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