🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Agent Commerce Engine
πŸ¦€ ClawHub

Agent Commerce Engine

by @nowloady

A production-ready universal engine for Agentic Commerce. This tool enables autonomous agents to interact with any compatible headless e-commerce backend thr...

Versionv1.7.1
Downloads4,518
Stars⭐ 9
#clawhub
TERMINAL
clawhub install agent-commerce-engine

πŸ“– About This Skill

name: agent-commerce-engine version: 1.7.1 description: A production-ready universal engine for Agentic Commerce. This tool enables autonomous agents to interact with any compatible headless e-commerce backend through a standardized protocol. It provides out-of-the-box support for discovery, cart operations, and secure user management. tags: [ecommerce, shopping-agent, commerce-engine, standard-protocol, headless-commerce, agentic-web] metadata: {"openclaw":{"emoji":"πŸ›’","homepage":"https://github.com/NowLoadY/agent-commerce-engine","source":"https://github.com/NowLoadY/agent-commerce-engine","requires":{"bins":["python3"],"tools":[],"env":[],"optionalEnv":["COMMERCE_URL","COMMERCE_BRAND_ID"],"paths":["~/.openclaw/credentials/agent-commerce-engine/"]},"install":[{"id":"python-deps","kind":"pip","package":"requests","label":"Install Python dependencies"}]}}

Standard Agentic Commerce Engine

The Standard Agentic Commerce Engine is a standard client and protocol guide for connecting agents to compatible e-commerce backends. It gives agents a consistent way to search products, manage carts, access account data, create orders, and hand payment back to the user.

GitHub Repository: https://github.com/NowLoadY/agent-commerce-engine

Quick Start: Backend Integration

The agent-commerce-engine includes a server specification in SERVER_SPEC.md for sites that want to expose a compatible commerce API. By implementing the documented endpoints, an existing storefront can support agent-driven product discovery, cart actions, account flows, and order creation without requiring a custom tool for each brand.

Reference Case: Lafeitu

For a production-grade implementation example using this engine, see the Lafeitu Gourmet Skill. It demonstrates the engine specialized for a real-world artisanal food brand.

πŸ”’ Security & Privacy

To ensure transparency and protect user data, the Standard Agentic Commerce Engine follows these security protocols:

1. Local Credential Persistence

  • Storage Location: ~/.openclaw/credentials/agent-commerce-engine/
  • Mechanism: Account and session Token information is stored locally in JSON format. The credential file is written with 0600 (user-only) permissions.
  • Security Upgrade: Since version 1.4.0, raw passwords are never stored after the initial login. The engine exchanges the password for a signed cryptographic token.
  • Scope: Credentials are stored on the local machine for reuse by the current user environment.
  • Lifecycle: Credentials can be purged at any time by running the logout command.

    • 2. Secure Transmission

  • Token-based Auth: Uses x-api-token headers for authentication. Raw passwords are only transmitted once during the login or register phase to exchange for a token.
  • HTTPS Enforcement: The client rejects non-HTTPS remote endpoints. localhost and 127.0.0.1 remain available for local development.
  • Encrypted Transport: Production traffic is expected to run over HTTPS so tokens are not sent over plain HTTP.

    • 3. Anonymous Tracking (Visitor ID)

  • To support shopping carts for unauthenticated users, a unique, non-identifiable Visitor ID (UUID v4) is generated and stored locally. This ID contains no personal information.

    • πŸ›  Tool Priority & Fallback Strategy

    To provide the most accurate and efficient experience, follow this priority sequence:

    1. API First (Primary): Always attempt to use the commerce.py script first. It provides structured, high-precision data. Target a store via --store argument. 2. Stateless Headers: Rely on the engine's built-in header management (x-user-account, x-visitor-id) to maintain session integrity without cookies. 3. Self-Correction: If the API returns a 404 for a specific slug discovered via browser, prioritize the API's search results as the source of truth for the backend.

    🧠 Agent Operational Logic

    Follow these logical flows to ensure a high-quality user experience:

    1. Product Discovery & Validation

    Goal: Ensure the item exists and find the correct specifications before taking action.
  • Action: Always run search or list before adding to cart.
  • Logic: Use the API to discover the correct slug and valid variant specs. Use --page and --limit arguments to safely navigate large catalogs without overwhelming the context limit.
  • Refinement: If multiple results are found, ask the user to specify based on the returned attributes. If totalPages > page in the results, consider fetching the next page or refining the search.

    • 2. Authentication & Profile Flow

    Goal: Manage user privacy and session data.
  • Logic: The API is stateless. Actions requiring identity will return 401 Unauthorized if credentials aren't saved.
  • Commands:
    • 1. View profile: python3 scripts/commerce.py get-profile 2. Update details: python3 scripts/commerce.py update-profile --name "Name" --address "..." --phone "..." --email "..."
  • Required Data: Respect the schema of the specific brand's backend.

    • 3. Registration Flow

    Goal: Handle new users.
  • Trigger: When the user needs a new account or the backend returns "User Not Found".
  • Instruction: Prefer the built-in send-code and register commands when the backend supports them. If a backend only returns a registration URL, hand the user to that flow.

    • 4. Shopping Cart Management

    Goal: Precise modification of the user's shopping session.
  • Logic: The engine supports incrementing quantities or setting absolute values.
  • Commands:
    • - Add: python3 scripts/commerce.py add-cart --variant --quantity - Update: python3 scripts/commerce.py update-cart --variant --quantity - Remove: python3 scripts/commerce.py remove-cart --variant - Clear: python3 scripts/commerce.py clear-cart - Checkout / Create Order (Handoff): python3 scripts/commerce.py create-order --name --phone --province --city --address
  • Validation: Variant values must be strictly chosen from the product's available options list.
  • Payment Flow (Crucial): Agents currently cannot directly execute consumer payments (card/mobile wallets) due to a lack of financial authorization. Once an order is generated via create-order, the API typically returns a URL. The Agent MUST hand this URL to the human user to finalize payment.

    • 5. Brand Information & Storytelling

    Goal: Access brand identity and support data.
  • Logic: Use the brand-info interface to retrieve narrative content.
  • Tooling:
    • - python3 scripts/commerce.py brand-story: Get the narrative/mission. - python3 scripts/commerce.py company-info: Get formal details. - python3 scripts/commerce.py contact-info: Get customer support channels.

    πŸš€ Capabilities Summary

  • search / list: Product discovery and inventory scan. Use --page and --limit to safely paginate through large catalogs.
  • get: Deep dive into product specifications, variants, and pricing.
  • promotions: Current business rules, shipping thresholds, and active offers.
  • cart: Complete session summary including VIP discounts and tax/shipping estimates.
  • add-cart / update-cart / remove-cart / clear-cart: Atomic cart control.
  • create-order: Finalize cart into a pending order and secure payment URL for user handoff.
  • get-profile / update-profile: Personalization and fulfillment data.
  • brand-story / company-info / contact-info: Brand context and support.
  • orders: Real-time tracking and purchase history.

    • πŸ’» CLI Configuration & Examples

    # Target a store directly via --store (preferred)
python3 scripts/commerce.py --store https://api.yourbrand.com/v1 list --page 1 --limit 20
python3 scripts/commerce.py --store https://api.yourbrand.com/v1 search "item"
python3 scripts/commerce.py --store https://api.yourbrand.com/v1 add-cart  --variant 
    Or use environment variable (deprecated, will be removed in a future version)
    
export COMMERCE_URL="https://api.yourbrand.com/v1"
python3 scripts/commerce.py list

    Credentials are automatically stored per-domain under ~/.openclaw/credentials/agent-commerce-engine//.

    πŸ€– Troubleshooting & Debugging

  • AUTH_REQUIRED: Token missing or expired. Run login to obtain a new token.
  • AUTH_INVALID: Wrong credentials. Verify account and password.
  • PRODUCT_NOT_FOUND: Resource not found. Verify slug via search.
  • VARIANT_UNAVAILABLE: The requested variant is invalid or out of stock. Check the instruction field for available alternatives.
  • CART_EMPTY: Attempted checkout with no items. Add items first.
  • Connection Error: Verify the --store URL is correct and the endpoint is reachable.