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 to handle product search, order management, pricing, reviews, inventory, and customer support. This is not a toy demo. It has 50 real products, 200 orders, 20 users with different roles, JWT authentication, role-based access control, OpenTelemetry tracing across all agents, a Next.js frontend with interactive chat cards, and Docker Compose for one-command deployment.

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.

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 From the mental model to working code in a single article. Covers the chatbot-vs-assistant-vs-agent distinction, the four properties that make systems “agentic” (autonomy, tool use, reasoning, memory), and the LLM + function calling loop — then goes hands-on with MAF: the @tool decorator, Annotated type hints for schema generation, multi-turn conversations, and the tool-calling loop with a sequence diagram.

Part 2: Prompt Engineering for AI Agents Why agent prompts need five layers (identity, capabilities, constraints, tool guidance, output format). Grounding rules that prevent hallucination, role-based instructions for customer/seller/admin, database schema context, few-shot tool examples, and YAML-based prompt configuration with a composable loader.

Part 3: Building Domain-Specific Tools Three categories of tools: query tools (search, details), action tools (initiate return with validate-then-act), and validation tools (coupon validation with cascading checks). User-scoped data with ContextVars, shared tools across agents, error handling with dicts instead of exceptions, and testing tools without an LLM.

Multi-Agent Architecture (Part 4)

#

Part 4: Multi-Agent Architecture: Orchestration and the A2A Protocol When to split from single to multi-agent (decision framework), the orchestrator pattern with a single call_specialist_agent tool, LLM-as-classifier for intent routing, the four-file specialist agent structure, and the agent host with tool-calling loop. Then: the Agent-to-Agent protocol — agent cards for capability discovery, the /message:send endpoint, two-layer authentication (shared secret + user identity), service discovery via agent registry, and A2A vs MCP comparison.

Production (Parts 5-7)

#

Part 5: Observability with OpenTelemetry Why observability is critical for non-deterministic agent systems. OpenTelemetry setup with one function call, auto-instrumentation of httpx/asyncpg/FastAPI, custom spans for A2A calls and tool execution, cross-agent trace correlation via W3C traceparent, .NET Aspire Dashboard walkthrough, and usage tracking with trace ID bridging.

Part 6: Frontend: Rich Cards and Streaming Responses Two frontend enhancements in one article. Transforming agent text into interactive UI components — product cards with price badges and ratings, order cards with timelines, action buttons that feed back into the conversation — with a fenced code block parsing pipeline. Then token-by-token streaming through the full stack: async generator in the agent host, SSE endpoint in FastAPI, progressive rendering in the browser, and handling tool calls 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 – 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.

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.