drupal-mods/commerce-agent-detector

Detects AI procurement/shopping agents and switches the commerce experience to machine-optimized mode.

1.0.0-beta4 2026-04-02 10:00 UTC

Requires

• php: >=8.2
• drupal/commerce: ^2.38 || ^3.0
• drupal/core: ^10.3 || ^11

Requires (Dev)

• drupal/coder: ^8.3
• mglaman/phpstan-drupal: ^2.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.0
• phpstan/phpstan-deprecation-rules: ^2.0
• phpunit/phpunit: ^10 || ^11

Suggests

• drupal/commerce_api: Provides REST/JSON:API endpoints for Commerce
• drupal/jsonapi_extras: Enhanced JSON:API customization for agent responses
• drupal/search_api: Enables full-text search via the agent search endpoint

GPL-2.0-or-later

• drupal
• headless
• acp
• commerce
• Agent
• openapi
• ai
• ucp
• llm

README

A Drupal module that automatically detects AI procurement/shopping agents and serves machine-optimized JSON commerce endpoints — while keeping the human experience 100% unchanged.

Features

Core

• Automatic agent detection — identifies ChatGPT, Claude, Gemini, Perplexity, Copilot, and custom agents via tokens, headers, user-agent strings, and optional heuristics
• JSON commerce API — search, product detail, cart, and checkout endpoints with Schema.org structured data
• Token management — SHA-256 hashed, customer-bound API tokens with scopes, expiration, and usage tracking
• Customer self-service — "Connected Agents" tab on user profiles for generating and revoking personal tokens
• Order ownership — orders placed via managed tokens are automatically assigned to the customer's account
• Rate limiting — configurable per-window limits via Drupal flood control
• Audit logging — every agent interaction logged with dashboard analytics
• Extensible — event-driven architecture for custom agent personas
• Zero impact on humans — normal site routing is completely unaffected

API Features

• Order tracking — order history and detail endpoints for agents to check status, items, and totals on behalf of customers
• Webhook subscriptions — agents can subscribe to store events (order placed, shipped, refunded, etc.) with HMAC-signed payloads and secret rotation
• Bulk cart operations — add, update, remove, or replace multiple cart items in a single request
• Shipping estimates — get shipping rates and available methods for a given address and order before checkout
• MCP server — Model Context Protocol endpoint for LLM tool-use integration (browsing, search, cart, checkout as MCP tools)
• Product comparison — compare multiple products side-by-side with attribute diffs, price comparison, and recommendations
• Budget-aware search — search products within a budget constraint with price-range facets and smart allocation
• Reorder — one-call reorder from a previous order, automatically recreating the cart with the same items
• Natural language query — POST natural language questions ("find me a red laptop under $1000") and get structured product results
• Inventory checks — real-time stock availability for single items or bulk variation lookups
• Agent sessions — persistent session context (preferences, conversation history) across multiple agent requests
• Returns & refunds — check return eligibility, create RMA requests, and track return status via API
• .well-known/agent-commerce.json — standardized discovery endpoint for agents to auto-detect store capabilities, endpoints, and protocols

Discovery & Interoperability

• Agent discovery — OpenAPI 3.1 spec, JSON product sitemap, and enhanced llms.txt for automatic API and catalog discovery
• ACP/UCP protocol support — compatible with OpenAI/Stripe Agentic Commerce Protocol and Google Universal Commerce Protocol
• A2A protocol — Google Agent-to-Agent protocol support with /.well-known/agent.json agent card and JSON-RPC handler

Architecture

Incoming Request
      │
      ▼
AgentDetectionSubscriber (priority 200)
      │
      ├─ 1. Managed tokens (cad_..., SHA-256, customer-bound)
      ├─ 2. Legacy tokens (config whitelist)
      ├─ 3. Agent headers (X-Agent-ID, X-ACP-Version, etc.)
      ├─ 4. User-Agent patterns (ChatGPT, ClaudeBot, etc.)
      └─ 5. Heuristics (opt-in behavioral scoring)
      │
      ├── Agent detected → AgentDetectedEvent → Agent API endpoints
      └── Not an agent  → Normal Drupal routing (unchanged)

Requirements

Dependency	Version
Drupal	10.3+ or 11
PHP	8.2+
Drupal Commerce	2.38+ or 3.x
JSON:API module	core (auto-enabled)
REST module	core (auto-enabled)

Optional: Search API, Commerce API, JSON:API Extras

Installation

Via Composer (Packagist)

composer require drupal-mods/commerce-agent-detector
drush en commerce_agent_detector -y
drush cr

From GitLab (alternative)

composer config repositories.commerce_agent_detector vcs https://gitlab.com/drupal-mods/commerce-agent-detector
composer require drupal-mods/commerce-agent-detector:dev-main
drush en commerce_agent_detector -y
drush cr

The commerce_agent_log and commerce_agent_token database tables are created automatically. Drupal Commerce and its dependencies (Address, Entity, Profile, etc.) will be pulled in by Composer if not already installed.

Quick Start

1. Enable the module (detection is on by default)
2. Go to Commerce → Configuration → Agent Detector to review settings
3. Create managed tokens at Agent Detector → Tokens for enterprise agents
4. Grant customers the manage own agent tokens permission for self-service
5. Agents access your store via /api/commerce/agent/* endpoints

Documentation

Guide	Description
Token Management	Managed tokens, customer binding, admin/customer UI, migration from legacy tokens
API Reference	All endpoints, parameters, request/response examples, error codes
Detection	How detection works, priority order, AgentResult, AgentDetectedEvent
Configuration	All settings explained, permissions, admin tabs
Security	Rate limiting, token auth, audit logging, input validation, fallbacks
Extending	Custom agent personas, programmatic API, adding agent-only routes
Testing	PHPUnit test suite, simulation script, cURL examples

API Endpoints

Search & Products

Method	Path	Description
GET	/api/commerce/agent/search	Search products
GET	/api/commerce/agent/product/{id}	View product detail
GET,POST	/api/commerce/agent/products/compare	Compare multiple products
POST	/api/commerce/agent/budget/search	Budget-constrained search
GET	/api/commerce/agent/budget/price-ranges	Get price range facets
POST	/api/commerce/agent/query	Natural language product query

Cart & Checkout

Method	Path	Description
GET	/api/commerce/agent/cart	View cart
POST	/api/commerce/agent/cart/add	Add item to cart
POST	/api/commerce/agent/cart/bulk-add	Add multiple items
PATCH	/api/commerce/agent/cart/bulk-update	Update multiple items
POST	/api/commerce/agent/cart/bulk-remove	Remove multiple items
POST	/api/commerce/agent/cart/replace	Replace entire cart
POST	/api/commerce/agent/checkout	Complete checkout
POST	/api/commerce/agent/reorder	Reorder from previous order

Orders & Returns

Method	Path	Description
GET	/api/commerce/agent/orders	Order history
GET	/api/commerce/agent/order/{id}	Order detail
GET	/api/commerce/agent/return/eligibility/{order_id}	Check return eligibility
POST	/api/commerce/agent/return	Create return/RMA
GET	/api/commerce/agent/return/{return_id}	Get return status

Shipping & Inventory

Method	Path	Description
GET,POST	/api/commerce/agent/shipping/estimate	Get shipping rates
GET	/api/commerce/agent/shipping/methods	List shipping methods
GET	/api/commerce/agent/inventory/{variation_id}	Check stock
POST	/api/commerce/agent/inventory/bulk	Bulk stock check

Webhooks

Method	Path	Description
GET	/api/commerce/agent/webhooks	List subscriptions
POST	/api/commerce/agent/webhooks	Subscribe to events
PATCH	/api/commerce/agent/webhooks/{id}	Update subscription
DELETE	/api/commerce/agent/webhooks/{id}	Unsubscribe
POST	/api/commerce/agent/webhooks/{id}/rotate-secret	Rotate webhook secret
GET	/api/commerce/agent/webhooks/events	List available event types

Sessions

Method	Path	Description
POST	/api/commerce/agent/session	Create session
GET	/api/commerce/agent/session/{id}	Get session
PATCH	/api/commerce/agent/session/{id}	Update session
DELETE	/api/commerce/agent/session/{id}	Delete session
GET	/api/commerce/agent/sessions	List sessions

Discovery & Protocols

Method	Path	Description
GET	/api/commerce/agent/openapi.json	OpenAPI 3.1 specification
GET	/api/commerce/agent/sitemap.json	JSON product sitemap
GET	/llms.txt	Machine-readable store description
GET	/.well-known/agent-commerce.json	Agent commerce discovery
GET	/.well-known/agent.json	A2A agent card
POST	/api/commerce/agent/a2a	A2A JSON-RPC handler
POST	/api/commerce/agent/mcp	MCP tool-use endpoint

See API Reference for full details.

Agent Dashboard

View traffic analytics at Commerce → Agent Dashboard: requests, unique agents, orders, revenue, conversion rate, and per-agent breakdown. Requires the view commerce agent dashboard permission.

How It Works (for Site Owners)

This module watches every request to your Drupal Commerce site. When it detects an AI agent, it serves clean JSON data instead of HTML pages. Human visitors see no change whatsoever — your themes, checkout flow, CAPTCHA, and every other module work exactly as before.

Agents get structured product data, direct cart/checkout APIs, and machine-readable error responses. Orders placed by agents with managed tokens are automatically assigned to the customer's account and appear in their normal order history.

Rate limiting, audit logging, and token authentication ensure your store stays secure. If anything fails, agents get a structured error with a fallback URL to the human version.

License

GPL-2.0-or-later