Agent Commerce Engine

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

Security Scan

The skill's code, docs, and runtime instructions align with its stated purpose (an agent-facing e‑commerce client); it requests no unrelated credentials, uses only python/requests, and stores per-domain tokens locally with reasonable constraints.

Purpose & Capability

Name/description (commerce engine for headless stores) matches the included CLI and client library. Required binary is python3 and the single Python dependency (requests) is proportionate. Optional env vars and the documented credential path align with multi-store operation.

Instruction Scope

SKILL.md instructs the agent to call the provided Python CLI, target a store via --store (or legacy env vars), and perform commerce actions (search, cart, auth, order creation). Instructions only reference the declared local credential path and the expected API endpoints; there are no hidden files, unexplained system paths, or external endpoints unrelated to commerce backends.

Install Mechanism

This is instruction-plus-source (no remote install scripts). The metadata suggests installing 'requests' via pip — a single, common dependency appropriate for an HTTP client. There are no downloads from arbitrary URLs or archive extracts.

Credentials

No required environment variables or credentials are declared. Optional COMMERCE_URL / COMMERCE_BRAND_ID are relevant for a multi-store CLI. The code does persist tokens locally (creds.json) but only under the declared ~/.openclaw/credentials/agent-commerce-engine/<domain>/ path.

Persistence & Privilege

The skill writes per-domain credential files (creds.json and visitor.json) under ~/.openclaw/credentials/agent-commerce-engine/ and sets file mode 0600. It does not request system-wide privileges or modify other skills. Keep in mind the skill can be invoked autonomously (platform default) and will use stored tokens to call store APIs, including actions that create or modify carts and orders.

Assessment

This skill appears coherent and does what it says, but consider these practical points before installing: - Tokens are persisted as JSON under ~/.openclaw/credentials/agent-commerce-engine/<domain>/ with file mode 0600. They are not encrypted; anyone with local account access can read them. Revoke tokens on the merchant side if you suspect compromise. - The client will make HTTP requests to whatever --store URL you supply. Only point it at stores you trust. The client enforces HTTPS for non-localhost endpoints, but localhost/127.0.0.1 are allowed for dev. - Because the agent can run this skill autonomously, a misconfigured or compromised agent could perform cart modifications, create orders, or call account endpoints using saved tokens. The skill itself does not perform unexpected network exfiltration, but stored tokens give authorization to the merchant API. - Passwords are exchanged once for tokens (not persisted), which is good practice. Still avoid reusing high-value credentials and prefer revocable API tokens when available. - If you need higher assurance, review the code files yourself (provided) or run the CLI in a sandboxed environment and inspect the network requests it makes when interacting with a test store. Overall this skill is internally consistent with its description; the main risks are normal operational concerns around stored tokens and which store endpoints you allow the agent to contact.

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 <url> 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 <slug> --variant <V> --quantity <Q>
  • Update: python3 scripts/commerce.py update-cart <slug> --variant <V> --quantity <Q>
  • Remove: python3 scripts/commerce.py remove-cart <slug> --variant <V>
  • Clear: python3 scripts/commerce.py clear-cart
  • Checkout / Create Order (Handoff): python3 scripts/commerce.py create-order --name <NAME> --phone <PHONE> --province <PROVINCE> --city <CITY> --address <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 <N> and --limit <N> 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 <slug> --variant <variant_id>

# 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/<domain>/.

---

🤖 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.