AgentCart — Your intent. Our intelligence. Your approval.
Inspiration
Online shopping gives you endless choice and almost no help. To buy one laptop you open a dozen tabs, compare spec sheets that are formatted differently on every site, work out whether the RAM you need fits the budget you have, and then re-check the whole thing before you pay. The expensive part is not the clicking — it is the deciding.
We started from a simple question: what if shopping worked like having a personal assistant who actually does the work?
That question became AgentCart, an AI purchasing agent that takes a natural-language request, searches a catalogue, compares real specifications, checks the budget, builds the cart, and then stops and hands the decision back to you before any money moves.
We wanted to go past the shopping chatbot that recommends three links and wishes you luck. The agent should do the repetitive work — search, filter, compare, total — while the human keeps the only thing that matters: approval.
Our philosophy: your intent, our intelligence, your approval.
What it does
AgentCart turns a sentence into a completed purchase workflow.
- Natural-language shopping — "I need a laptop for robotics with 16 GB RAM and a dedicated GPU under $1,000." No filters, no dropdowns, no category tree.
- Tool-driven product discovery — the model calls a real
search_productstool against a 39-product catalogue with structured specs, not a text index it can hallucinate over. - Genuine comparison —
compare_productsandcheck_product_compatibilityline up price, CPU, GPU, RAM, storage and ports side by side, and flag what a product misses as well as what it meets. - Budget enforcement —
check_budgetandcalculate_cartcompute subtotal, shipping and tax on the server, and refuse to build a cart that exceeds the stated limit. - Cart building and editing —
add_to_cart,remove_from_cartandget_cartlet you say "drop the second one" or "choose 1" and have it mean the product you just saw, not a fresh search. - A visible plan, then a hard stop —
prepare_checkoutproduces an approval sheet with every line item, the exact total and a plain-language summary. Nothing is charged at this point. - PayPal checkout — only after you approve does the server create a real PayPal Sandbox order, open PayPal's own approval UI, and capture the payment. The receipt records PayPal's order ID, capture ID and the captured amount.
- Transparency throughout — every tool call, its arguments and its result stream to the UI, so you can see exactly what the agent did and why.
How we built it
AgentCart is an npm-workspaces monorepo with a React client and an Express API, and the agent loop lives entirely on the server.
Architecture
Client (React + Vite)
│ POST /api/agent/turn + SSE transcript
▼
Express API ── Agent engine ── provider chain: Gemini → Groq → OpenAI → local planner
│ │
│ └── 10 tools (search, compare, budget, cart, prepare_checkout)
▼
Policy engine ── approval sheet ── PayPal Orders API v2 ── capture ── receipt
│
└── SQLite (or PostgreSQL via DATABASE_URL): 12 tables
- Frontend — React, TypeScript and Vite, with Tailwind CSS, Framer Motion, React Router, TanStack Query and Lucide icons. Eleven screens cover landing, catalogue, compare, agent run, approval, checkout and receipts.
- Backend — Node.js and Express with Zod validation on every route. Prices, totals and stock are always recomputed server-side; the model's arithmetic is never trusted.
- AI integration — a tool-calling loop over a provider chain. Gemini 3.x Flash is primary; Groq (
openai/gpt-oss-120b, OpenAI-compatible) is the fallback that currently serves live turns; an OpenAI-compatible provider and a deterministic local planner sit behind it. The chain degrades automatically and the UI labels which provider produced a turn. - Data — one
schema.sqlwith 12 tables (users, sessions, products, carts, cart items, orders, order items, approvals, receipts, agent runs, agent events, webhook events), running on Node's built-in SQLite by default and PostgreSQL whenDATABASE_URLis set. - Payments — PayPal Orders API v2 for create and capture,
paypal.Buttonsfrom the JS SDK for approval, and signature-verified webhooks for reconciliation when a buyer abandons the tab mid-flow. - Security — scrypt password hashing, httpOnly session cookies, session-bound carts and orders, and same-origin checks on mutations.
- Deployment — a Render blueprint (
render.yaml) defines the API and static site, but the hackathon demo runs locally against the PayPal sandbox; no hosted instance is claimed.
The workflow
Request → AI understanding → tool calls → comparison → budget validation
→ cart → human approval → PayPal order → capture → receipt
Challenges we ran into
Keeping the agent on the original request. Multi-step shopping means many tool calls in one turn, and models drift — they forget the budget by the third product. We solved this by keeping the requirement, the cart and the last search results in server-owned state that is re-rendered into the prompt every step, instead of hoping the model remembers.
Making "choose 2" mean what the user just saw. Early on, a follow-up like "choose 1" triggered a fresh search and could add a different product. The engine now caches the numbered search results and the prompt maps an ordinal back to a concrete product ID, so the agent refers to the same list the user is reading.
Stopping the model from inventing product facts. Prices, stock and specifications come from the catalogue and are re-read server-side at checkout. If a model produces a total that disagrees with the cart, the server's number wins and the discrepancy is visible in the transcript.
Never letting an AI spend money on its own. The agent can prepare a checkout but cannot execute one. capture-order is a separate, human-triggered request that requires an approved order, and the app only records a purchase as paid when PayPal returns COMPLETED.
Provider churn. The Gemini model we started with was retired mid-build, and free-tier quota ran out during testing. We added a fallback chain and a per-model working-model cache, so a retired or rate-limited model degrades instead of breaking the demo.
Making it feel like a shop, not a chat window. The agent's work is shown as structured cards — product tiles, a comparison table, a policy checklist, an approval sheet — rather than walls of generated prose, with the raw tool calls available in a transcript panel for anyone who wants to audit them.
Accomplishments that we're proud of
- An agent that completes a real purchase workflow rather than recommending links: search, compare, budget, cart, approve, pay, receipt.
- A genuine PayPal Sandbox integration — Orders v2 create and capture, JS SDK approval, signed webhooks — with no simulated payment success anywhere in the code.
- Ten purpose-built tools with typed schemas, executed server-side, so the model plans but never touches money or invents data.
- A policy engine that turns "under $1,000" into an enforced rule and produces a readable checklist of what passed and what failed.
- Full auditability: every agent run, tool call and event is persisted, and the UI streams it live.
- A provider chain that survives model retirement, rate limits and a missing API key, with a clearly labelled non-AI fallback instead of a silent failure.
- A design that reads as a commerce product, with code-drawn SVG product artwork and no stock photography.
- Above all: a purchasing agent that is useful because it cannot act alone.
What we learned
Building AgentCart taught us that a working agent is mostly engineering around the model, not prompting.
- State beats context. Reliable multi-step behaviour came from server-owned state injected into each step, not from a longer prompt.
- Tools are the contract. Narrow, typed tools with honest errors produced far better behaviour than one broad "do shopping" capability.
- Trust boundaries are a design decision. The model proposes; the server validates; the human approves. Writing that down as three separate layers removed a whole class of bugs.
- Failure is a feature. Rate limits, retired models and empty API keys are normal. A visible fallback chain turned a demo-ending problem into a footnote.
- Autonomy and control are not opposites. The agent is most useful when it does the tedious 90% and stops precisely at the decision that belongs to the customer.
What's next for AgentCart
- Live retailer integrations — real catalogues with live pricing and stock, behind the same tool interface.
- Price monitoring — watch a cart and tell the customer when it drops below their target.
- Recurring and replenishment purchases — consumables reordered on a schedule the customer sets.
- Learning preferences with consent — brand, spec and budget defaults the agent proposes and the customer can inspect and revoke.
- Richer compatibility rules — sockets, wattage, clearance and connector checks beyond today's spec matching.
- Multi-agent planning — specialised researchers, comparers and budget keepers coordinated by an orchestrator.
- Spending policies — per-category limits, auto-approval ceilings and merchant allowlists, enforced by the same policy engine that runs today.
Our goal is simple: make online shopping feel less like admin and more like delegation — with the receipt, and the decision, still yours.
AgentCart — your intent, our intelligence, your approval.
Built With
- express.js
- framer-motion
- gemini
- groq
- lucide
- node.js
- openai
- paypal
- paypal-js-sdk
- paypal-orders-api
- postgresql
- react
- react-router
- sqlite
- tailwindcss
- tanstack-query
- typescript
- vite
- vitest
- zod