StateSet iCommerce Quickstart

Getting started guide for AI agents using the StateSet iCommerce engine

StateSet iCommerce Quickstart

This guide helps AI agents get up and running with the StateSet iCommerce engine in minutes.

Overview

StateSet iCommerce provides:

• Embedded Commerce Engine - Local SQLite database with 70+ tables
• Autonomous Agent Runtime - Scheduled jobs, workflows, policies
• Multi-Agent Coordination - Verifiable Event Sync (VES) via sequencer
• 90+ MCP Tools - Full commerce operations accessible to agents

Prerequisites

• Node.js 18+
• npm or yarn
• Anthropic API key (for Claude-powered agents)

Step 1: Install the CLI

npm install -g @stateset/cli

Verify installation:

stateset --version

Step 2: Register Your Agent

Register with the sequencer to get an API key for multi-agent coordination:

curl -X POST https://api.sequencer.stateset.com/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-commerce-agent",
    "description": "Autonomous commerce agent"
  }'

Response:

{
  "success": true,
  "agentId": "550e8400-e29b-41d4-a716-446655440000",
  "tenantId": "660e8400-e29b-41d4-a716-446655440001",
  "apiKey": "ss_660e8400aBcDeFgHiJkLmNoPqRsTuVwXyZ",
  "permissions": "read_write",
  "message": "Agent registered successfully. Store your API key securely."
}

Save your API key - it’s only shown once.

Step 3: Initialize Commerce Database

# Create database with demo data
stateset init --demo

# Or create empty database
stateset init

This creates ~/.stateset/commerce.db with:

• 70+ commerce tables (orders, customers, products, inventory, etc.)
• Demo data (if --demo flag used)
• Sync outbox for VES events

Step 4: Configure Sync

Create ~/.stateset/sync-config.json:

{
  "tenantId": "<your-tenant-id>",
  "storeId": "00000000-0000-0000-0000-000000000001",
  "agentId": "<your-agent-id>",
  "sequencerEndpoint": "https://api.sequencer.stateset.com",
  "apiKey": "<your-api-key>",
  "transport": "rest",
  "conflictStrategy": "remote-wins"
}

Verify connection:

stateset-sync status

Step 5: Run Your First Agent Command

Read-Only Query

stateset "List all customers"

Write Operation

stateset --apply "Create a customer named Alice Smith with email [e-mail]"

With Sync (Multi-Agent)

stateset --apply --sync "Create an order for customer [e-mail]"

Step 6: Start Autonomous Engine

Run the full autonomous engine with scheduled jobs and workflows:

stateset-autonomous start --init-defaults --verbose

Output:

📦 Initializing commerce engine...
🚀 Starting autonomous engine...

📊 Engine Status:
   Scheduler: ✅ Running (7 jobs)
   Workflows: ✅ Ready (4 definitions)
   Policies:  ✅ Loaded (15 policy sets)
   Webhooks:  ✅ Listening on port 3000
   Approvals: ✅ Ready

✨ Autonomous engine is running!

---

Agent Commands Reference

Customer Operations

stateset "List customers"
stateset --apply "Create customer John Doe with email [e-mail]"
stateset "Get customer by email [e-mail]"

Order Operations

stateset "List pending orders"
stateset --apply "Create order for customer [e-mail] with SKU-001 quantity 2"
stateset --apply "Ship order ORD-123 with tracking 1Z999AA10123456784"

Inventory Operations

stateset "Check stock for SKU-001"
stateset --apply "Adjust inventory for SKU-001 add 100 units"
stateset --apply "Reserve 5 units of SKU-001 for order ORD-123"

Returns Operations

stateset "List pending returns"
stateset --apply "Create return for order ORD-123 reason defective"
stateset --apply "Approve return RET-456"

Sync Operations

stateset-sync status          # Check sync health
stateset-sync push            # Push local events to sequencer
stateset-sync pull            # Pull remote events
stateset-sync history         # View sync history

---

Programmatic Usage (Node.js)

import { Commerce } from '@stateset/embedded';
import { runAgentLoop } from '@stateset/cli/src/claude-harness.js';

// Initialize commerce engine
const commerce = new Commerce('~/.stateset/commerce.db');

// Run agent task
const result = await runAgentLoop({
  commerce,
  request: "Create an order for [e-mail]",
  allowApply: true,      // Enable write operations
  enableSync: true,      // Capture events for sync
  autoSyncPush: true,    // Auto-push to sequencer
  maxTurns: 10
});

console.log(result.response);

---

Multi-Agent Coordination

How Agents Coordinate

Agent A (Orders)              Sequencer                 Agent B (Inventory)
      │                           │                           │
      │ 1. Create Order           │                           │
      │──────────────────────────>│                           │
      │                           │                           │
      │ 2. Sign & Commit          │                           │
      │──────────────────────────>│                           │
      │                           │ 3. Broadcast Event        │
      │                           │──────────────────────────>│
      │                           │                           │
      │                           │ 4. Reserve Inventory      │
      │                           │<──────────────────────────│
      │                           │                           │
      │ 5. Receive Confirmation   │                           │
      │<──────────────────────────│                           │

Running Multiple Agents

Terminal 1 - Order Agent:

export STATESET_AGENT_NAME="order-agent"
stateset-autonomous start --db ./order-agent.db --port 3001

Terminal 2 - Inventory Agent:

export STATESET_AGENT_NAME="inventory-agent"
stateset-autonomous start --db ./inventory-agent.db --port 3002

Both agents sync through the sequencer and coordinate automatically.

---

Autonomous Engine Features

Scheduled Jobs

# List jobs
stateset-autonomous jobs

# Run job manually
stateset-autonomous jobs --run process-orders

# Enable/disable job
stateset-autonomous jobs --enable low-stock-alerts

Default Jobs

Job	Schedule	Description
process-orders	Every 5 min	Process pending orders
check-inventory	Hourly	Check low stock levels
sync-events	Every 10 min	Sync with sequencer
cleanup-carts	Daily	Abandon old carts

Workflows

Pre-configured workflows for:

• Order fulfillment lifecycle
• Return processing
• Subscription billing
• Inventory replenishment

Policies

15 policy sets covering:

• Order value limits
• Inventory thresholds
• Return windows
• Discount rules

---

Environment Variables

# Required
export ANTHROPIC_API_KEY=sk-ant-...

# Optional
export STATESET_DB_PATH=~/.stateset/commerce.db
export STATESET_SYNC_ENDPOINT=https://api.sequencer.stateset.com
export STATESET_API_KEY=ss_...
export STATESET_LOG_LEVEL=info

---

Troubleshooting

Database not found

stateset init --demo

Sync not connecting

# Check config
cat ~/.stateset/sync-config.json

# Test connection
stateset-sync status

Agent not responding

# Check API key
echo $ANTHROPIC_API_KEY

# Run with verbose
stateset "test" --verbose

---

Next Steps

1. Explore the CLI - Run stateset --help for all commands
2. Customize Agents - Edit .claude/agents/*.md for agent personalities
3. Add Workflows - Create custom workflows in .stateset/autonomous/
4. Enable Webhooks - Configure external integrations
5. Scale Up - Run multiple agents with different specializations

---

Quick Reference

Command	Description
stateset init	Initialize commerce database
stateset "query"	Run agent query (read-only)
stateset --apply "task"	Run agent task (write enabled)
stateset --apply --sync "task"	Run with multi-agent sync
stateset-autonomous start	Start autonomous engine
stateset-sync status	Check sync health
stateset-sync push	Push events to sequencer
stateset-sync pull	Pull events from sequencer

---

API Endpoints

Endpoint	Purpose
POST /api/v1/agents/register	Register new agent
POST /api/v1/ves/events/ingest	Ingest VES events
GET /api/v1/events	List events
POST /api/v1/ves/commitments	Create commitment
GET /health	Health check

Base URL: https://api.sequencer.stateset.com

---

StateSet iCommerce Engine v1.22.0 July 2026