Sales Agent Harness

Sales Agent Harness is an open-source, framework-agnostic agentic commerce stack that acts as the merchant-owned control layer between an AI seller agent and the merchant's commerce systems. It lets the agent support product discovery, product details, cart preparation, cart summaries, and checkout handoff, without directly exposing raw commerce backends or letting the model decide prices, discounts, availability, checkout terms, or commercial commitments on its own. It ships with an integrated agent runtime built on LangGraph Deep Agents.

What It Does

• Searches products from trusted commerce data.
• Retrieves product details, prices, availability, and delivery information when the adapter returns it.
• Creates and updates cart drafts or carts through the configured commerce adapter.
• Summarizes cart totals, line items, and shipping costs.
• Prepares checkout handoff URLs using opaque harness tokens or adapter-owned UCP checkout sessions.
• Completes checkout only in the explicit UCP research path, when the capability and merchant policy are both enabled and buyer confirmation data is present.
• Relays a buyer-supplied AP2 checkout mandate to the shop on completion, opaquely and only when the inbound A2A message carries one — the harness never generates or inspects it.
• Exposes the same controlled flow through a customer chat UI, direct HTTP commerce routes, and an A2A-compatible HTTP+JSON surface.

What It Does Not Do

• Uncontrolled autonomous selling.
• Payment execution outside an explicitly supported, merchant-approved checkout completion flow.
• Legal-term acceptance on behalf of the buyer.
• Binding quotes, custom discount negotiation, or customer account mutation.
• Direct model access to Shopware, Store API, UCP, MCP, PSPs, or other commerce systems.

Quick Start

Use this path for a local smoke test against a real Shopware Store API.

1. Copy the example environment file:

   cp .env.example .env

2. Fill in the required values:

   OPENAI_API_KEY=sk-...
   SHOPWARE_BASE_URL=https://your-shop.example
   SHOPWARE_STORE_API_ACCESS_KEY=store-api-access-key
   SHOPWARE_DEFAULT_SALES_CHANNEL_ID=sales-channel-id
   AGENT_RUNTIME_MODEL=gpt-5-mini
   STORAGE_PROVIDER=sqlite
   SQLITE_DB_PATH=data/sales-agent-harness.sqlite
   HOST=127.0.0.1
   PORT=3000

   To run the model through OpenRouter (or any OpenAI-compatible endpoint) instead of OpenAI directly, set OPENAI_BASE_URL — see Configuration.

3. Start with Docker:

   docker compose up --build

   Or start with Bun:

   bun install
   set -a
   source .env
   set +a
   bun run start

4. Check health:

   curl http://127.0.0.1:3000/health

5. Open the example UI:

   http://127.0.0.1:3000/examples/customer-ui
   

6. Create a session and send a chat message:

   curl -X POST http://127.0.0.1:3000/sessions \
     -H 'content-type: application/json' \
     -d '{"channel":"customer_ui","customerContext":{"region":"DE"}}'
   
   curl -X POST http://127.0.0.1:3000/chat \
     -H 'content-type: application/json' \
     -d '{"agentSessionId":"session-id-from-create-session","message":"Find waterproof jackets"}'

For the full local runbook, real-agent test flow, endpoint list, and troubleshooting, see Running The Harness.

Documentation

• Running The Harness: environment variables, Docker/Bun startup, smoke tests, real-agent testing, A2A requests, and troubleshooting.
• Configuration: agent profile, capability flags, policy config, commerce adapter choice, UCP profile signing, and runtime/storage settings.
• Architecture: request flow, module boundaries, runtime boundary, commerce adapter boundary, and persistence structure.
• Checkout And UCP: checkout handoff, automated UCP checkout, idempotency, and non-production full-checkout testing.
• Observability: audit events, SQLite persistence, LangGraph checkpoints, and exported store classes.
• Demo Journey: a narrated merchant, customer, and A2A buyer-agent demo.
• Extending The Harness: how to add adapters, capabilities, policy rules, runtimes, routes, storage, and observability sinks without bypassing the harness.
• A2A Buyer Agent Demo: standalone buyer-agent UI for local agent-to-agent experiments.

Development

Install dependencies:

bun install

Run focused tests:

bun test

Run the standard checks:

bun run format:check
bun run lint
bun run typecheck

Run architecture and quality checks:

bun run quality:fallow
bun run quality:health
bun run quality

CI remains the final authority.

Research Preview Limits

Current known limits are tracked in Running The Harness. The short version: A2A support is intentionally narrow, checkout completion is UCP-only and opt-in, SQLite is for durable local demos, and this repository does not include production authentication, tenant isolation, payment authorization, fraud controls, or an admin audit UI.