Four vertical demos, each running both agents over one catalog: retail/ (ACME),
travel/ (ACME Travel), telecom/ (ACME Mobile), and entertainment/ (ACME Tickets).
python scripts/run_demo.py <vertical> starts one; each vertical's README lists its ports,
prompts to try on both surfaces, and what it adds to the libraries.
| Path | Contents |
|---|---|
demo_common/ |
Host code the four APIs share: app and middleware (host.py), session store (sessions.py), storefront routes (storefront.py), merchant router (merchant.py), memory routes and fixture seeder (memory.py), mock-backend helpers (*_fixtures.py) |
web-shared/ |
The npm package the eight web apps import: the API client, the session and turn hooks, the event types (protocol.ts mirrors commerce_common/streaming.py), the transcript and inspector components, shared primitives and icons, and the two app frames (storefront/, portal/) |
package.json |
The npm workspace: web-shared plus every */storefront-web and */merchant-web (npm ci installs all of them) |
<vertical>/api/ |
One FastAPI process: the two mock backends, the two agent configs (agent_config.py), the vertical's own routes and presentation extensions, and the merchant router mounted under /api/merchant |
<vertical>/data/ |
The fixtures both backends load, listed in the vertical's README |
<vertical>/storefront-web/, <vertical>/merchant-web/ |
The Next.js apps: this vertical's cards, views, and tokens over web-shared |
Sessions, carts, and staged changes live in one process's memory in demo_common, so the
examples run one worker.
web-shared holds the session, streaming, and rendering plumbing once. Each app holds its
own components: components/generative/ has one entry per presentation tool, typed by the
app's lib/types.ts, so the four frontends are four builds of the same payload schemas
(shopping_agent/tools/presentation.py, merchant_agent/tools/presentation.py); a
deployment's frontend is a fifth.
Every web app serves /showcase, which renders each of its components from
lib/showcase-fixtures.ts; it needs neither the API nor a key, and run_demo.py prints
the storefront's showcase URL when the demo is up. Open it when changing a component.
A storefront session starts by naming a profile from data/users.json (POST /api/session);
a merchant session binds to the one merchant the process serves. Every later request carries
only the session id, in X-Session-Id, and the routes read the principal from it.
| Variable | Effect | Read in | Default |
|---|---|---|---|
ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN |
Chat credentials; the environment wins over <vertical>/.env, which wins over the repo-root .env |
demo_common/host.py |
unset (client credential chain) |
COMMERCE_DEMO_AUTH |
sdk skips the .env files and clears the key variables so the client's credential chain is used; run_demo.py --federated sets it |
demo_common/host.py |
unset |
DEMO_ALLOWED_HOSTS |
Comma-separated Host values the API answers to besides localhost and 127.0.0.1 |
demo_common/host.py |
unset |
DEMO_LOG_LEVEL |
INFO writes one line per model call; DEBUG adds each request and response |
demo_common/host.py |
INFO |
MERCHANT_REQUIRE_HOST_APPROVAL |
0 lets an approval typed in chat apply a change; 1 requires the preview card's button |
demo_common/host.py |
1 |
MERCHANT_ANALYSIS_CODE_EXECUTION |
1 mounts the hosted code execution tool in the retail analysis delegate |
retail/api/agent_config.py |
0 |
MERCHANT_ANALYSIS_MODEL |
The retail analysis delegate's model | retail/api/agent_config.py |
unset (main model) |
NEXT_PUBLIC_API_URL |
Where a web app sends its requests; run_demo.py sets it to the port the API came up on |
<app>/lib/api.ts |
http://localhost:<API_PORT> |
The API reads its variables at startup; a web app takes the NEXT_PUBLIC_ values when it
is built or its dev server starts.