{"id":50885085,"url":"https://github.com/nitin27may/e-commerce-agents","last_synced_at":"2026-06-15T16:30:45.188Z","repository":{"id":349393079,"uuid":"1201731193","full_name":"nitin27may/e-commerce-agents","owner":"nitin27may","description":"6 specialized AI agents collaborating via A2A protocol to power e-commerce — product discovery, orders, pricing, reviews, inventory \u0026 support. Built with Microsoft Agent Framework, FastAPI, Next.js, and PostgreSQL + pgvector.","archived":false,"fork":false,"pushed_at":"2026-05-29T17:03:47.000Z","size":4529,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T17:07:41.964Z","etag":null,"topics":["a2a-protocol","ai-agents","aspire-dashboard","azure-openai","e-commerce","fastapi","microsoft-agent-framework","multi-agent","nextjs","openai","opentelemetry","pgvector","postgresql","redis","semantic-search","shadcn-ui"],"latest_commit_sha":null,"homepage":"https://nitinksingh.com/posts/building-a-multi-agent-e-commerce-platform-the-complete-guide/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nitin27may.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-05T04:35:21.000Z","updated_at":"2026-05-29T15:30:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nitin27may/e-commerce-agents","commit_stats":null,"previous_names":["nitin27may/e-commerce-agents"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nitin27may/e-commerce-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitin27may%2Fe-commerce-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitin27may%2Fe-commerce-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitin27may%2Fe-commerce-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitin27may%2Fe-commerce-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nitin27may","download_url":"https://codeload.github.com/nitin27may/e-commerce-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nitin27may%2Fe-commerce-agents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34372091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a-protocol","ai-agents","aspire-dashboard","azure-openai","e-commerce","fastapi","microsoft-agent-framework","multi-agent","nextjs","openai","opentelemetry","pgvector","postgresql","redis","semantic-search","shadcn-ui"],"created_at":"2026-06-15T16:30:44.506Z","updated_at":"2026-06-15T16:30:45.181Z","avatar_url":"https://github.com/nitin27may.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# E-Commerce Agents\n\n[![Tests](https://github.com/nitin27may/e-commerce-agents/actions/workflows/tests.yml/badge.svg)](https://github.com/nitin27may/e-commerce-agents/actions/workflows/tests.yml)\n[![Build Images](https://github.com/nitin27may/e-commerce-agents/actions/workflows/build-images.yml/badge.svg)](https://github.com/nitin27may/e-commerce-agents/actions/workflows/build-images.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.12+](https://img.shields.io/badge/Python-3.12+-3776AB.svg)](https://python.org)\n[![Next.js 16](https://img.shields.io/badge/Next.js-16-000000.svg)](https://nextjs.org)\n[![MAF v1](https://img.shields.io/badge/Microsoft%20Agent%20Framework-v1-5E5DF0.svg)](https://github.com/microsoft/agent-framework)\n[![PostgreSQL + pgvector](https://img.shields.io/badge/PostgreSQL-pgvector-336791.svg)](https://github.com/pgvector/pgvector)\n[![Docker](https://img.shields.io/badge/Docker-Compose-2496ED.svg)](https://docs.docker.com/compose/)\n\nA **multi-agent e-commerce platform** built with [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) (MAF) Python SDK. Six specialized AI agents collaborate via **A2A protocol** to handle product discovery, orders, pricing, reviews, inventory, and customer support.\n\nCompanion demo repo for the AI article series on [nitinksingh.com](https://nitinksingh.com).\n\n![AI shopping assistant with product cards](docs/images/shop-ai-assistant.png)\n\n---\n\n## Where to start\n\n| I want to... | Go here |\n|---|---|\n| Run the demo locally | [Quick Start](#quick-start) below |\n| Understand how the agents work / add a new one | [Architecture](docs/architecture.md) · [Adding an Agent](docs/adding-an-agent.md) |\n| Use the MCP server | [MCP Integration](docs/mcp-integration.md) |\n| Follow the step-by-step tutorial series | [tutorials/README.md](./tutorials/README.md) |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- [Docker](https://docs.docker.com/get-docker/) and Docker Compose\n- An [OpenAI API key](https://platform.openai.com/api-keys) (or Azure OpenAI credentials)\n\n### Setup\n\n```bash\n# 1. Clone the repo\ngit clone https://github.com/nitin27may/e-commerce-agents.git\ncd e-commerce-agents\n\n# 2. Configure environment\ncp .env.example .env\n# Edit .env — add your OPENAI_API_KEY (or Azure OpenAI credentials)\n\n# 3. Start everything (builds, seeds, and starts all services)\n./scripts/dev.sh\n```\n\nOpen in your browser:\n- **Frontend**: http://localhost:3000\n- **Aspire Dashboard** (telemetry): http://localhost:18888\n\n### Other Commands\n\n```bash\n./scripts/dev.sh --clean       # Nuke volumes, rebuild from scratch\n./scripts/dev.sh --seed-only   # Re-run database seeder only\n./scripts/dev.sh --infra-only  # Start db + redis + aspire only\n```\n\n---\n\n## Table of Contents\n\n- [Project Status](#project-status)\n- [Learning Path](#learning-path--maf-v1-python-and-net)\n- [Architecture](#architecture)\n- [Screens](#screens)\n- [Test Users](#test-users)\n- [Agent Catalog](#agent-catalog)\n- [Demo Scenarios](#demo-scenarios)\n- [Tech Stack](#tech-stack)\n- [Project Structure](#project-structure)\n- [Configuration](#configuration)\n- [Documentation](#documentation)\n- [Port Map](#port-map)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Project Status\n\n**This is v1 — the Python version is live today.** It runs end-to-end: six specialist agents, orchestrator, auth, telemetry, and a full Next.js frontend.\n\nThe frontend is a **public, agentic e-commerce storefront**: anyone can browse the catalog, search, and use the AI shopping assistant (`/shop`) without an account — product discovery is served anonymously — while account flows (cart checkout, orders, tracking, returns) require sign-in. A built-in **agent-activity timeline** surfaces the multi-agent routing (orchestrator → specialist → tool) live in chat, backed by OpenTelemetry → .NET Aspire. Light/dark theming throughout.\n\nThe **.NET / C# port** for teams building in the Microsoft ecosystem lives at [`agents/dotnet/`](./agents/dotnet/) alongside the Python backend at [`agents/python/`](./agents/python/). Enhancement plans and the phased roadmap are tracked in [`.claude/plans/enhancements/`](./.claude/plans/enhancements/).\n\n---\n\n## Learning Path — *MAF v1: Python and .NET*\n\nA new step-by-step tutorial series walks through **every Microsoft Agent Framework concept** — agents, tools, memory, middleware, workflow primitives, all five orchestration patterns, HITL, checkpoints, declarative workflows, visualization — with runnable examples in **both Python and .NET**. This repository is the capstone.\n\n**Start here:** [`tutorials/README.md`](./tutorials/README.md)\n\n| Tier | Chapters | Topics |\n|------|----------|--------|\n| 1 · Core Agent | [01–04](./tutorials/) | First agent · tools · streaming · sessions |\n| 2 · Agent Internals | 05–08 | Context providers · middleware · OpenTelemetry · MCP |\n| 3 · Workflow Foundations | 09–11 | Executors · edges · events · builder · agents in workflows |\n| 4 · Orchestrations | 12–16 | Sequential · Concurrent · Handoff · Group Chat · Magentic |\n| 5 · Advanced | 17–20 | HITL · checkpoints · declarative YAML · visualization |\n| Capstone | 21 | Guided tour of this repo |\n\nEach chapter has `python/`, `dotnet/`, `tests/`, a Hugo-ready article draft (`README.md`), and a per-chapter plan (`PLAN.md`). Chapters cross-post to [nitinksingh.com](https://nitinksingh.com) under the *MAF v1: Python and .NET* series, complementing the [original Python-only series](https://nitinksingh.com/posts/building-a-multi-agent-e-commerce-platform-the-complete-guide/).\n\n---\n\n## Architecture\n\n![System Architecture](docs/architecture.png)\n\n\u003cdetails\u003e\n\u003csummary\u003eView as Mermaid diagram\u003c/summary\u003e\n\n```mermaid\ngraph TB\n    subgraph Client[\"Browser / Client\"]\n        FE[\"Next.js 16\u003cbr/\u003eReact 19 + Tailwind CSS\"]\n    end\n\n    subgraph Orchestrator[\"Orchestrator Agent :8080\"]\n        FA[\"FastAPI + MAF\"]\n        AUTH[\"JWT Auth + RBAC\"]\n        ROUTER[\"Intent Router\"]\n        CONV[\"Conversation Mgmt\"]\n        MKT[\"Marketplace API\"]\n    end\n\n    subgraph Specialists[\"Specialist Agents · A2A Protocol\"]\n        PD[\"Product Discovery\u003cbr/\u003e:8081\"]\n        OM[\"Order Management\u003cbr/\u003e:8082\"]\n        PP[\"Pricing \u0026amp; Promotions\u003cbr/\u003e:8083\"]\n        RS[\"Review \u0026amp; Sentiment\u003cbr/\u003e:8084\"]\n        IF[\"Inventory \u0026amp; Fulfillment\u003cbr/\u003e:8085\"]\n    end\n\n    subgraph Infrastructure[\"Shared Infrastructure\"]\n        PG[(\"PostgreSQL 16\u003cbr/\u003e+ pgvector\")]\n        RD[(\"Redis 7\")]\n        ASP[\"Aspire Dashboard\u003cbr/\u003e:18888\"]\n    end\n\n    subgraph LLM[\"LLM Provider\"]\n        OAI[\"OpenAI API\u003cbr/\u003egpt-4.1\"]\n        AZ[\"Azure OpenAI\u003cbr/\u003e(configurable)\"]\n    end\n\n    FE --\u003e|\"HTTP/JSON\"| FA\n    FA --\u003e AUTH\n    AUTH --\u003e ROUTER\n    ROUTER --\u003e|\"A2A\"| PD\n    ROUTER --\u003e|\"A2A\"| OM\n    ROUTER --\u003e|\"A2A\"| PP\n    ROUTER --\u003e|\"A2A\"| RS\n    ROUTER --\u003e|\"A2A\"| IF\n\n    PD --\u003e PG\n    OM --\u003e PG\n    PP --\u003e PG\n    RS --\u003e PG\n    IF --\u003e PG\n\n    PD --\u003e|\"Embeddings\"| OAI\n    PD -.-\u003e|\"or\"| AZ\n    Orchestrator --\u003e RD\n    Specialists --\u003e|\"OTLP\"| ASP\n\n    Orchestrator --\u003e|\"OTLP\"| ASP\n    Specialists --\u003e OAI\n    Specialists -.-\u003e AZ\n\n    style Client fill:#6366f1,stroke:#4f46e5,stroke-width:2px,color:#fff\n    style FE fill:#818cf8,stroke:#6366f1,color:#fff\n\n    style Orchestrator fill:#0891b2,stroke:#0e7490,stroke-width:2px,color:#fff\n    style FA fill:#22d3ee,stroke:#06b6d4,color:#0c4a6e\n    style AUTH fill:#fca5a5,stroke:#f87171,color:#7f1d1d\n    style ROUTER fill:#67e8f9,stroke:#22d3ee,color:#0c4a6e\n    style CONV fill:#67e8f9,stroke:#22d3ee,color:#0c4a6e\n    style MKT fill:#67e8f9,stroke:#22d3ee,color:#0c4a6e\n\n    style Specialists fill:#0d9488,stroke:#0f766e,stroke-width:2px,color:#fff\n    style PD fill:#2dd4bf,stroke:#14b8a6,color:#134e4a\n    style OM fill:#2dd4bf,stroke:#14b8a6,color:#134e4a\n    style PP fill:#2dd4bf,stroke:#14b8a6,color:#134e4a\n    style RS fill:#2dd4bf,stroke:#14b8a6,color:#134e4a\n    style IF fill:#2dd4bf,stroke:#14b8a6,color:#134e4a\n\n    style Infrastructure fill:#475569,stroke:#334155,stroke-width:2px,color:#fff\n    style PG fill:#94a3b8,stroke:#64748b,color:#1e293b\n    style RD fill:#94a3b8,stroke:#64748b,color:#1e293b\n    style ASP fill:#94a3b8,stroke:#64748b,color:#1e293b\n\n    style LLM fill:#d97706,stroke:#b45309,stroke-width:2px,color:#fff\n    style OAI fill:#fbbf24,stroke:#f59e0b,color:#78350f\n    style AZ fill:#fbbf24,stroke:#f59e0b,color:#78350f\n```\n\u003c/details\u003e\n\n---\n\n## Screens\n\n\u003cdetails open\u003e\n\u003csummary\u003eScreenshots — guest browsing, the AI shopping flow, and the platform (click to collapse)\u003c/summary\u003e\n\n### Guest experience (no login required)\n\nAnyone can browse the catalog, use the AI shopping assistant, and explore product details without creating an account.\n\n\u003ctable\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cimg src=\"docs/images/flow-guest-storefront.png\" alt=\"Public storefront — browse without signing in\" width=\"820\"/\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cem\u003eProduct detail — full info, pricing, reviews, and stock status\u003c/em\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cimg src=\"docs/images/flow-guest-assistant.png\" alt=\"Public AI shopping assistant\" width=\"820\"/\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cem\u003eAI shopping assistant — product questions answered via multi-agent routing, no login needed\u003c/em\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\n### AI shopping flow (signed in)\n\nSign in as any seeded user to access cart, checkout, order tracking, and returns — all driven by natural language in the chat interface.\n\n\u003ctable\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cimg src=\"docs/images/flow-product-search.png\" alt=\"AI chat — product search with cards\" width=\"820\"/\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cem\u003eFind a product — orchestrator routes to Product Discovery; results render as interactive cards\u003c/em\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cimg src=\"docs/images/flow-add-to-cart.png\" alt=\"AI chat — add to cart\" width=\"820\"/\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cem\u003eAdd to cart — ask the assistant; it calls the cart API and confirms with a card\u003c/em\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cimg src=\"docs/images/flow-view-cart.png\" alt=\"AI chat — cart summary\" width=\"820\"/\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cem\u003eView cart — the agent renders a cart summary with totals and a checkout link\u003c/em\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cimg src=\"docs/images/flow-order-tracking.png\" alt=\"AI chat — order tracking\" width=\"820\"/\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cem\u003eTrack an order — Order Management agent returns live status and shipment detail\u003c/em\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cimg src=\"docs/images/flow-refund.png\" alt=\"AI chat — return / refund request\" width=\"820\"/\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cem\u003eReturn / refund — agent initiates the return flow and issues a return label\u003c/em\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\n### Platform\n\n\u003ctable\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cimg src=\"docs/images/agent-timeline.png\" alt=\"Live agent activity timeline\" width=\"820\"/\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cem\u003eAgent timeline — orchestrator → specialist → tool routing surfaced live in chat\u003c/em\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cimg src=\"docs/images/storefront.png\" alt=\"Product storefront\" width=\"820\"/\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cem\u003eProduct storefront — authenticated view with cart and account access\u003c/em\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cimg src=\"docs/images/marketplace.png\" alt=\"Agent marketplace\" width=\"820\"/\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cem\u003eAgent marketplace — browse, request, and manage specialist agent access\u003c/em\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cimg src=\"docs/images/admin-dashboard.png\" alt=\"Admin dashboard\" width=\"820\"/\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cem\u003eAdmin dashboard — usage analytics, approval queues, and audit log\u003c/em\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cimg src=\"docs/images/seller-dashboard.png\" alt=\"Seller dashboard\" width=\"820\"/\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003cem\u003eSeller dashboard — product catalog and order management\u003c/em\u003e\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c/details\u003e\n\n---\n\n## Test Users\n\nPre-seeded accounts for testing different roles:\n\n| Email | Password | Role | Loyalty Tier |\n|-------|----------|------|-------------|\n| `admin.demo@gmail.com` | admin123 | Admin | Gold |\n| `seller.demo@gmail.com` | seller123 | Seller | Bronze |\n| `seller2.demo@gmail.com` | seller123 | Seller | Bronze |\n| `alice.johnson@gmail.com` | customer123 | Customer | Gold |\n| `bob.smith@gmail.com` | customer123 | Customer | Silver |\n\n---\n\n## Agent Catalog\n\n| Agent | Port | Description | Key Tools |\n|-------|------|-------------|-----------|\n| **Customer Support** (Orchestrator) | 8080 | Routes requests to specialists via A2A | `call_specialist_agent` |\n| **Product Discovery** | 8081 | Search, semantic search, comparisons, trending | `search_products`, `semantic_search`, `compare_products` |\n| **Order Management** | 8082 | Order tracking, cancellation, returns, refunds | `get_user_orders`, `cancel_order`, `initiate_return` |\n| **Pricing \u0026 Promotions** | 8083 | Coupon validation, cart optimization, loyalty | `validate_coupon`, `optimize_cart`, `get_active_deals` |\n| **Review \u0026 Sentiment** | 8084 | Sentiment analysis, fake review detection | `analyze_sentiment`, `detect_fake_reviews` |\n| **Inventory \u0026 Fulfillment** | 8085 | Stock, shipping estimates, fulfillment planning | `check_stock`, `estimate_shipping` |\n\n---\n\n## Demo Scenarios\n\nTry these in the chat after logging in:\n\n1. **Product Search**: \"Find me wireless headphones under $300 with good noise cancellation\"\n2. **Comparison**: \"Compare the Sony WH-1000XM5 with AirPods Max\"\n3. **Order Tracking**: \"Where's my latest order?\"\n4. **Return Flow**: \"I want to return my last order\"\n5. **Price Check**: \"Is the Logitech MX Master 3S a good deal right now?\"\n6. **Review Analysis**: \"What do people think about the Dyson V15?\"\n7. **Stock Check**: \"Is the Dyson V15 Detect in stock?\"\n8. **Multi-Intent**: \"Return my jacket and find me a warmer one under $200\"\n\n---\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|-----------|\n| Agent Framework | [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) v1.0 (Python SDK) |\n| Agent Communication | A2A Protocol (HTTP) |\n| LLM | OpenAI / Azure OpenAI (gpt-4.1) |\n| Orchestrator | FastAPI (Python 3.12) |\n| Database | PostgreSQL 16 + pgvector (1536-dim embeddings) |\n| Cache | Redis 7 |\n| Frontend | Next.js 16, React 19, Tailwind CSS, shadcn/ui |\n| Auth | Self-contained JWT (PyJWT + bcrypt) |\n| Telemetry | OpenTelemetry → .NET Aspire Dashboard |\n| Package Managers | uv (Python), pnpm (Node) |\n| Containerization | Docker Compose |\n\n---\n\n## Project Structure\n\n```\ne-commerce-agents/\n├── docker-compose.yml               # 11 services with profiles\n├── .env.example                     # Environment template\n├── agents/                          # Both backends live here\n│   ├── python/                      # Python backend\n│   │   ├── Dockerfile               # Multi-target agent image (ARG AGENT_NAME)\n│   │   ├── Dockerfile.mcp           # Lean MCP server image (ARG MCP_PACKAGE)\n│   │   ├── pyproject.toml           # Workspace root + dependencies (MAF, OTel, FastAPI)\n│   │   ├── packages/                # Standalone publishable MCP server packages\n│   │   │   ├── mcp-product/         # ecommerce-mcp-product (:9000)\n│   │   │   └── mcp-inventory/       # ecommerce-mcp-inventory (:9001)\n│   │   ├── shared/                  # Shared library (config, auth, DB, prompts, telemetry)\n│   │   ├── config/prompts/          # YAML prompt configs (shared with .NET)\n│   │   ├── orchestrator/            # Customer Support (:8080)\n│   │   ├── product_discovery/       # Product Discovery (:8081)\n│   │   ├── order_management/        # Order Management (:8082)\n│   │   ├── pricing_promotions/      # Pricing \u0026 Promotions (:8083)\n│   │   ├── review_sentiment/        # Review \u0026 Sentiment (:8084)\n│   │   └── inventory_fulfillment/   # Inventory \u0026 Fulfillment (:8085)\n│   └── dotnet/                      # .NET backend — parity with Python\n│       ├── ECommerceAgents.sln\n│       ├── Directory.Packages.props # Central package versions\n│       └── src/\n│           ├── ECommerceAgents.Shared/\n│           ├── ECommerceAgents.Orchestrator/   # :8080\n│           ├── ECommerceAgents.ProductDiscovery/\n│           ├── ECommerceAgents.OrderManagement/\n│           ├── ECommerceAgents.PricingPromotions/\n│           ├── ECommerceAgents.ReviewSentiment/\n│           └── ECommerceAgents.InventoryFulfillment/\n├── docker/postgres/\n│   └── init.sql                    # 24-table schema + pgvector\n├── scripts/\n│   ├── dev.sh                      # One-command dev setup\n│   ├── seed.py                     # Database seeder\n│   └── generate_embeddings.py      # Product embedding generation\n├── web/                            # Next.js 16 frontend\n│   └── src/\n│       ├── app/                    # 16 routes (App Router)\n│       ├── components/             # UI components (shadcn/ui)\n│       └── lib/                    # API client, auth context\n├── tutorials/                      # 22-chapter MAF v1 tutorial series (Python + .NET)\n└── docs/                           # Full documentation — see docs/README.md\n    ├── README.md                   # Docs index and reading order\n    ├── architecture.md             # System design, agent patterns, A2A protocol\n    ├── adding-an-agent.md          # Step-by-step guide to adding a specialist\n    ├── api-reference.md            # All REST endpoints with examples\n    ├── agent-flows.md              # Multi-agent collaboration sequence diagrams\n    ├── database-schema.md          # 24 tables with ER diagram\n    ├── deployment.md               # Docker Compose, dev.sh, environment config\n    ├── frontend.md                 # Routes, theming, SSE/timeline, auth model\n    ├── telemetry.md                # OpenTelemetry setup and Aspire Dashboard\n    ├── mcp-integration.md          # MCP servers, setup, agent wiring\n    ├── maf-best-practices.md       # MAF idioms: @tool, middleware, prompt YAML\n    ├── security-guide.md           # Threat model, guardrails, hardening checklist\n    ├── agent-quality.md            # Eval methodology, datasets, CI gate\n    ├── agent-audit-matrix.md       # Per-agent security posture matrix\n    └── troubleshooting.md          # Common local-stack issues and fixes\n```\n\n---\n\n## Configuration\n\nCopy `.env.example` to `.env` and configure your LLM provider:\n\n```bash\n# OpenAI (default)\nLLM_PROVIDER=openai\nOPENAI_API_KEY=sk-...\nLLM_MODEL=gpt-4.1\n\n# Azure OpenAI (alternative)\nLLM_PROVIDER=azure\nAZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/\nAZURE_OPENAI_KEY=...\nAZURE_OPENAI_DEPLOYMENT=gpt-4.1\n```\n\nSee [Deployment Guide](docs/deployment.md) for all configuration options.\n\n---\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Architecture](docs/architecture.md) | System design, agent patterns, A2A protocol, auth flow |\n| [Adding an Agent](docs/adding-an-agent.md) | Step-by-step guide to adding a specialist agent |\n| [API Reference](docs/api-reference.md) | All REST endpoints with examples |\n| [Database Schema](docs/database-schema.md) | 24 tables with ER diagram |\n| [Telemetry](docs/telemetry.md) | OpenTelemetry setup and Aspire Dashboard |\n| [Agent Flows](docs/agent-flows.md) | Multi-agent collaboration diagrams |\n| [Deployment](docs/deployment.md) | Docker Compose, dev.sh, environment configuration |\n| [Frontend](docs/frontend.md) | Routes, theming, SSE/timeline, public-vs-auth model |\n| [Troubleshooting](docs/troubleshooting.md) | Common local-stack issues and fixes |\n| [Contributing](CONTRIBUTING.md) | Setup, conventions, testing policy, PR checklist |\n| [Security Guide](docs/security-guide.md) | Threat model, guardrails stack, auth, SQL controls |\n| [Agent Quality \u0026 Evals](docs/agent-quality.md) | Eval methodology, datasets, red-team suite, CI gate |\n| [Agent Audit Matrix](docs/agent-audit-matrix.md) | Per-agent security posture and open hardening items |\n| [MAF Best Practices](docs/maf-best-practices.md) | MAF idioms: @tool, middleware, prompt YAML, ContextVars |\n| [MCP Integration](docs/mcp-integration.md) | MCP servers (FastMCP), MCPStreamableHTTPTool wiring, enable/disable |\n\n---\n\n## Port Map\n\n| Service | Port | URL |\n|---------|------|-----|\n| Frontend | 3000 | http://localhost:3000 |\n| Orchestrator | 8080 | http://localhost:8080 |\n| Product Discovery | 8081 | |\n| Order Management | 8082 | |\n| Pricing \u0026 Promotions | 8083 | |\n| Review \u0026 Sentiment | 8084 | |\n| Inventory \u0026 Fulfillment | 8085 | |\n| Aspire Dashboard | 18888 | http://localhost:18888 |\n| PostgreSQL | 5432 | |\n| Redis | 6379 | |\n| MCP Product | 9000 | http://localhost:9000/mcp (when `--profile mcp`) |\n| MCP Inventory | 9001 | http://localhost:9001/mcp (when `--profile mcp`) |\n\n---\n\n## Roadmap\n\nThis is v1. The Python platform is live and stable. The .NET port is also available.\n\nLegend: `- [x]` shipped · `- [ ]` planned or in progress.\n\n### Shipped in v1\n\n- [x] **Agent evaluators** — scripted eval sets (precision@k, recall@k, answer faithfulness, tool-call correctness) across all six specialists, run against the seeded catalog. Nightly CI via `.github/workflows/evals.yml` (deliberately not a PR gate — LLM calls are slow and non-deterministic; nightly is the right cadence).\n- [x] **Prompt injection prevention** — `shared/guardrails/` wired into the middleware stack for all agents. Enabled by default (`GUARDRAILS_ENABLED=true`); runs in observe-first mode (`GUARDRAILS_FAIL_OPEN=true`) — flags and logs injections. Set `GUARDRAILS_BLOCK_ON_INJECTION=true` to enable hard blocking once false-positive rates are measured in your environment.\n- [x] **Session memory \u0026 context persistence** — `store_memory` / `recall_memories` tools in `shared/tools/memory_tools.py`, surfaced to the orchestrator via `shared/context_providers.py`. Per-user preferences, recent intents, and history make follow-ups feel continuous.\n- [x] **Full .NET / C# port** — same six specialist agents plus an MCP server, same A2A protocol and PostgreSQL schema, idiomatic .NET throughout. Nine test projects, ~191 tests. See [`agents/dotnet/`](./agents/dotnet/).\n- [x] **Observability dashboards** — pre-built Aspire Dashboard views for agent latency, tool error rates, and LLM token spend per specialist.\n- [x] **MCP data-access layer (2 servers)** — `mcp-product` (:9000) and `mcp-inventory` (:9001) are standalone, independently publishable Python packages (`packages/mcp-product`, `packages/mcp-inventory`) in a uv workspace. They expose product and inventory data over the MCP streamable HTTP transport (FastMCP). Flag-gated via `MCP_ENABLED`; `product-discovery` and `inventory-fulfillment` swap their direct-asyncpg `@tool` set for `MCPStreamableHTTPTool` with no behavior change. Any MCP-compatible client — Claude Desktop, Cursor, LangGraph — can use them without this codebase. See [MCP Integration](docs/mcp-integration.md).\n\n### In Progress\n\n- [ ] **Human-in-the-loop approval flows** — backend approval endpoints and admin review UI are complete (`/api/admin/hitl/requests`). The remaining piece is the in-chat agent-pause card: the agent suspends mid-task, renders an approval prompt in the UI, and resumes once an operator confirms. High-stakes actions (refunds over threshold, inventory writes, bulk price changes) are the first targets.\n- [ ] **Per-agent cost tracking** — per-specialist token counts are persisted in the database (`shared/usage_db.py`) and surfaced on the admin usage page. The remaining piece is first-class OpenTelemetry metrics (token + dollar cost per specialist as OTLP counters), so the Aspire Dashboard and any OTLP sink can alert on spend anomalies.\n- [ ] **Streaming tool calls end-to-end** — text-delta streaming is live and product/order cards render progressively as the LLM generates the response. The remaining piece is propagating raw tool-result payloads as separate SSE frames so cards can appear before the text completes.\n\n---\n\n### Planned — Search \u0026 Retrieval\n\nThe product catalog has 1536-dim pgvector embeddings but `search_products` still uses `ILIKE` matching. Planned:\n\n- [ ] **Postgres full-text search** — `tsvector` column + GIN index, `plainto_tsquery` + `ts_rank` to replace the `ILIKE` loop.\n- [ ] **Hybrid retrieval (FTS + vector)** — combine lexical and semantic scores via Reciprocal Rank Fusion in a single CTE.\n- [ ] **Smarter tool routing** — update `product-discovery.yaml` so the LLM routes vague descriptive queries to `semantic_search` and attribute-driven queries to `search_products`.\n- [ ] **Typed filter DSL** — replace the flat parameter list on `search_products` with a structured `ProductFilters` Pydantic model (category, price, brand, sort). Keeps SQL parameterized and safe.\n\nText-to-SQL was considered and rejected: `user_email`/`user_role` scoping via ContextVars means dynamic SQL would bypass that contract. The typed filter DSL gives the model flexibility at the boundary while keeping SQL generation server-side and auditable.\n\n---\n\n### MCP as the Agent Data-Access Layer\n\n| Server | Port | Domain |\n|--------|------|--------|\n| `mcp-product` | 9000 | Product search, details, comparison, trending, price history |\n| `mcp-inventory` | 9001 | Stock levels, warehouses, shipping, carriers |\n\nBoth are standalone publishable packages in a uv workspace (`packages/mcp-product`, `packages/mcp-inventory`). Start them with:\n\n```bash\ndocker compose --profile mcp --profile agents up\n\n# then set in .env\nMCP_ENABLED=true\nMCP_PRODUCT_SERVER_URL=http://localhost:9000/mcp\nMCP_INVENTORY_SERVER_URL=http://localhost:9001/mcp\n```\n\nSee [MCP Integration](docs/mcp-integration.md) for the full setup guide, tool coverage table, external client examples (Claude Desktop, LangGraph), and publishing instructions.\n\nPlanned:\n\n- [ ] **External integration surface** — publish `ecommerce-mcp-product` and `ecommerce-mcp-inventory` to PyPI so any MCP-compatible client can `pip install` and run them against any PostgreSQL database without this codebase.\n- [ ] **Eval gate** — run each eval dataset twice (native tools vs MCP path) and fail CI if the MCP run scores below the native baseline.\n\n---\n\n### Planned — Platform \u0026 Observability\n\n- [ ] **Prompt caching** — cache system prompts and tool schemas per agent to reduce per-request token cost on repeated specialist invocations.\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/your-feature`\n3. Make your changes and ensure tests pass\n4. Submit a pull request\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed setup, conventions, testing policy, and PR checklist.\n\n---\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n---\n\nBuilt with [Microsoft Agent Framework](https://github.com/microsoft/agent-framework) and [A2A Protocol](https://google.github.io/A2A/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitin27may%2Fe-commerce-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnitin27may%2Fe-commerce-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnitin27may%2Fe-commerce-agents/lists"}