Retail Agentic Commerce

NVIDIA AI Blueprint: Retail Agentic Commerce

[](LICENSE) [](https://www.python.org/downloads/) [](https://nodejs.org/)

A reference implementation of the Agentic Commerce Protocol (ACP) and Universal Commerce Protocol (UCP), built for merchant-controlled checkout, payments, and agent orchestration.

Architecture

What You Get

• Merchant API (ACP + UCP discovery/A2A)
• PSP service for delegated payment flows
• Apps SDK MCP server + widget
• NAT agents for promotion, recommendations, search, and post-purchase messaging
• Demo UI with protocol and agent activity panels

Architecture (Default Deployment)

flowchart TB
    subgraph Client["Client Layer"]
        CA[🤖 Client Agent]
        subgraph Webhooks["UI Webhook Receivers"]
            WH_ACP["/api/webhooks/acp"]
            WH_UCP["/api/webhooks/ucp"]
            BRIDGE["Webhook → Agent Activity Bridge"]
        end
    end

    subgraph Integration["Integration Options"]
        direction LR
        subgraph SDK["Apps SDK Layer"]
            MCP["📦 Apps SDK MCP Server(Port 2091)"]
            subgraph tools["Entry Point"]
                T1["search-products(returns widget)"]
            end
            WIDGET["🛒 Autonomous Widget(cart, checkout, recs)"]
        end

        subgraph Native["Native Protocol Layer"]
            ACP["🔗 ACP REST Transport"]
            UCP["🔗 UCP A2A Transport"]
            subgraph endpoints["Protocol Endpoints"]
                E1["ACP: /checkout_sessions/*"]
                E2["UCP: /.well-known/ucp"]
                E3["UCP: /.well-known/agent-card.json"]
                E4["UCP: /a2a (message/send)"]
            end
        end
    end

    subgraph Backend["Backend Services"]
        MERCHANT["🏪 Merchant API(Port 8000)"]
        PSP["💳 PSP Service(Port 8001)"]
        
        subgraph merchant_features["Merchant Features"]
            M1[Products & Sessions]
            M2[Checkout & Promotions]
            M3[Orders & Recommendations]
        end
        
        subgraph psp_features["PSP Features"]
            P1[Payment Delegation]
            P2[Vault Tokens]
            P3[Idempotency]
        end
    end

    subgraph Agents["NAT Agents"]
        PROMO["🎯 Promotion Agent(Port 8002)"]
        POST["📨 Post-Purchase Agent(Port 8003)"]
        RECS["🔍 Recommendation Agent(Port 8004)"]
        SEARCH["🔎 Search Agent(Port 8005)"]
    end

    subgraph NIMs["NVIDIA NIMs"]
        LLM["🧠 Nemotron Nano LLM(Port 8010)"]
        EMBED["📐 NV-EmbedQA-E5(Port 8011)"]
    end

    subgraph Data["Data Stores"]
        SQLITE[("🗄️ SQLiteApplication DB")]
        MILVUS[("🧠 MilvusVector DB")]
    end

    CA -->|MCP| MCP
    CA -->|REST| ACP
    CA -->|A2A JSON-RPC| UCP
    MCP -.->|loads| WIDGET
    WIDGET -->|MCP tools| MCP
    MCP --> MERCHANT
    ACP --> E1
    UCP --> E2
    UCP --> E3
    UCP --> E4
    E1 --> MERCHANT
    E4 --> MERCHANT
    MERCHANT --> PSP
    MERCHANT --> PROMO
    MERCHANT --> POST
    MERCHANT --> RECS
    MERCHANT --> SEARCH
    MERCHANT --> SQLITE
    MERCHANT -->|ACP post-purchase webhook| WH_ACP
    MERCHANT -->|UCP order webhook| WH_UCP
    WH_ACP --> BRIDGE
    WH_UCP --> BRIDGE
    BRIDGE --> CA
    PROMO --> LLM
    POST --> LLM
    RECS --> LLM
    RECS --> EMBED
    SEARCH --> LLM
    SEARCH --> EMBED
    EMBED --> MILVUS
    RECS --> MILVUS
    SEARCH --> MILVUS

Quick Start (Codex, Claude Code)

This is the recommended path. It does not require local NIM containers.

Prerequisites

• Python 3.12+
• uv package manager
• Node.js 18+ and pnpm
• Docker 24+ and Docker Compose v2
• NVIDIA API key (create one)

1. Clone and Configure

git clone https://github.com/NVIDIA/Retail-Agentic-Commerce.git
cd Retail-Agentic-Commerce
cp env.example .env

Update .env:

NVIDIA_API_KEY=nvapi-xxx

In Codex or Claude Code, simply run: /setup

Manual Deployment Options

| Mode | Description | Guide | |------|-------------|-------| | Docker (recommended) | Full stack in containers via Docker Compose | [Docker Deployment](deploy/docker-deployment.md) | | Local Development | Services on host, automated via install.sh | [Local Development](deploy/local-development.md) |

Quick local start:

./install.sh   # install deps + start all 8 services
./stop.sh      # stop everything

Hardware Requirements (Local NIM Deployment)

Local NIM deployment requires NVIDIA GPUs to host the inference models. The following table summarizes the models and their GPU requirements:

| Model | Purpose | Minimum GPU | Recommended GPU | |-------|---------|-------------|-----------------| | Nemotron-Nano-30B-A3B | LLM — prompt planning, recommendations, search, promotions | 1× A100 (80 GB) | 1× H100 (80 GB) | | NV-EmbedQA-E5-v5 | Embedding — semantic search and product retrieval | 1× A100 (80 GB) | 1× H100 (80 GB) |

Total: 2× A100 (80 GB) minimum, 2× H100 (80 GB) recommended for best performance.

> Note: These requirements apply only to self-hosted local NIM deployment. The default deployment uses public NVIDIA API endpoints and does not require any GPU hardware.

Optional: Local NIM Deployment (GPU)

Only needed for self-hosted local inference. The default deployment already works with public endpoints.

For step-by-step instructions (prerequisites, GPU setup, NIM containers, validation), see the [Local NIM Deployment Notebook](deploy/1DeployAgentic_Commerce.ipynb).

Project Structure

src/
├── merchant/      # Merchant API (FastAPI)
├── payment/       # PSP service (FastAPI)
├── apps_sdk/      # MCP server + widget
├── agents/        # NAT agents and configs
└── ui/            # Next.js demo UI

deploy/
├── docker-deployment.md
├── local-development.md
└── 1_Deploy_Agentic_Commerce.ipynb

docs/
├── architecture.md
├── features/
└── specs/

Documentation

• [Docker Deployment](deploy/docker-deployment.md)
• [Local Development](deploy/local-development.md)
• [Architecture](docs/architecture.md)
• [Feature Breakdown](docs/features/index.md)
• [ACP Spec](docs/specs/acp-spec.md)
• [UCP Spec](docs/specs/ucp-spec.md)
• [Apps SDK Spec](docs/specs/apps-sdk-spec.md)
• [Agent Integration](src/agents/README.md)

License

GOVERNING TERMS: The Blueprint scripts are governed by Apache License, Version 2.0, and enables use of separate open source and proprietary software governed by their respective licenses: Nemotron-Nano-V3, (ii) MIT license for NV-EmbedQA-E5-v5. The sample data is governed by the [NVIDIA Data License for Retail Agentic Commerce](/LICENSE-assets.txt).

This project will download and install additional third-party open source software projects. Review the license terms of these open source projects before use, found in [License-3rd-party.txt](/LICENSE-3rd-party.txt).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NVIDIA-AI-Blueprints
• Source: NVIDIA-AI-Blueprints/Retail-Agentic-Commerce
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.