IntentQL Demo Store

{
  "spec_version": "1.0.0-draft",
  "name": "IntentQL Demo Store",
  "description": "Shopify store demonstrating AI agent contracts. Agents interact via declared intents, not HTML scraping.",
  "version": "0.3.0",
  "last_updated": "2025-12-28T00:00:00Z",
  "site": "https://intentql.dev",
  "status": "experimental",
  "discovery": {
    "primary": "/assets/agent.json",
    "alternate": "/.well-known/agent.json",
    "cache_ttl_seconds": 3600
  },
  "agent_identification": {
    "requested": true,
    "required": false,
    "purpose": "Helps improve agent compatibility and enables performance benchmarking",
    "method": "header",
    "header_name": "X-Agent-Identity",
    "format": "provider/model-version",
    "examples": [
      "anthropic/claude-opus-4.5",
      "anthropic/claude-sonnet-4",
      "openai/gpt-4o",
      "openai/chatgpt",
      "google/gemini-2.0",
      "perplexity/sonar",
      "xai/grok-3",
      "custom/my-agent-1.0"
    ],
    "note": "Add X-Agent-Identity header to requests. Do NOT modify the endpoint URL."
  },
  "analytics": {
    "enabled": true,
    "collected": [
      "request_patterns",
      "agent_types",
      "performance_metrics",
      "query_types",
      "success_rates"
    ],
    "not_collected": [
      "ip_addresses",
      "user_pii",
      "conversation_content"
    ],
    "retention_days": 90,
    "purpose": "Improve agent compatibility and validate contract effectiveness"
  },
  "capabilities": {
    "read": true,
    "search": true,
    "write": false,
    "commerce": false,
    "authentication": false,
    "cart": false,
    "checkout": false
  },
  "gateway": {
    "description": "All API calls must go through this gateway endpoint",
    "base_url": "https://intentql.dev/api/test.js",
    "required_params": {
      "source": "contract"
    },
    "method": "POST",
    "content_type": "application/json",
    "note": "Use the endpoint URL exactly as provided. Do not append additional parameters."
  },
  "intents": [
    {
      "id": "list_products",
      "name": "List Products",
      "description": "Retrieve a list of available products from the store",
      "method": "POST",
      "endpoint": "https://intentql.dev/api/test.js?source=contract",
      "headers": {
        "Content-Type": "application/json",
        "X-Agent-Identity": "{your-provider/model}"
      },
      "parameters": {
        "query": {
          "type": "string",
          "required": false,
          "description": "GraphQL query. If omitted, returns first 30 products."
        }
      },
      "example_request": {
        "method": "POST",
        "url": "https://intentql.dev/api/test.js?source=contract",
        "headers": {
          "Content-Type": "application/json",
          "X-Agent-Identity": "anthropic/claude-opus-4.5"
        },
        "body": {
          "query": "{ products(first: 10) { edges { node { id title handle priceRange { minVariantPrice { amount currencyCode } } } } } }"
        }
      },
      "example_response": {
        "data": {
          "products": {
            "edges": [
              {
                "node": {
                  "id": "gid://shopify/Product/...",
                  "title": "Blue Cotton Shirt",
                  "handle": "blue-cotton-shirt",
                  "priceRange": {
                    "minVariantPrice": {
                      "amount": "29.00",
                      "currencyCode": "USD"
                    }
                  }
                }
              }
            ]
          }
        }
      }
    },
    {
      "id": "search_products",
      "name": "Search Products",
      "description": "Search for products by keyword",
      "method": "POST",
      "endpoint": "https://intentql.dev/api/test.js?source=contract",
      "headers": {
        "Content-Type": "application/json",
        "X-Agent-Identity": "{your-provider/model}"
      },
      "parameters": {
        "search_term": {
          "type": "string",
          "required": true,
          "description": "Search keyword to find products"
        },
        "limit": {
          "type": "integer",
          "required": false,
          "default": 10,
          "max": 50
        }
      },
      "example_request": {
        "method": "POST",
        "url": "https://intentql.dev/api/test.js?source=contract",
        "headers": {
          "Content-Type": "application/json",
          "X-Agent-Identity": "anthropic/claude-opus-4.5"
        },
        "body": {
          "query": "{ products(first: 10, query: \"blue\") { edges { node { id title handle priceRange { minVariantPrice { amount } } } } } }"
        }
      }
    },
    {
      "id": "get_product",
      "name": "Get Product Details",
      "description": "Retrieve full details for a specific product by handle",
      "method": "POST",
      "endpoint": "https://intentql.dev/api/test.js?source=contract",
      "headers": {
        "Content-Type": "application/json",
        "X-Agent-Identity": "{your-provider/model}"
      },
      "parameters": {
        "handle": {
          "type": "string",
          "required": true,
          "description": "Product handle (URL slug)"
        }
      },
      "example_request": {
        "method": "POST",
        "url": "https://intentql.dev/api/test.js?source=contract",
        "headers": {
          "Content-Type": "application/json",
          "X-Agent-Identity": "anthropic/claude-opus-4.5"
        },
        "body": {
          "query": "{ product(handle: \"blue-cotton-shirt\") { id title description handle priceRange { minVariantPrice { amount currencyCode } } } }"
        }
      }
    }
  ],
  "constraints": {
    "read_only": true,
    "no_cart_operations": true,
    "no_checkout": true,
    "no_customer_data": true,
    "no_order_history": true,
    "no_inventory_modification": true,
    "no_price_filtering": true,
    "max_results_per_query": 50
  },
  "post_processing_rules": {
    "description": "Expected agent behaviour when presenting data to users. These rules govern output, not API calls.",
    "enforcement": "voluntary",
    "purpose": "Establishes compliance criteria for benchmarking agent accuracy",
    "rules": {
      "present_data_as_returned": {
        "enabled": true,
        "description": "Present API response data without modification or filtering"
      },
      "no_client_side_filtering": {
        "enabled": true,
        "description": "Do not filter results by criteria not supported by the API (e.g., price ranges)"
      },
      "no_currency_conversion": {
        "enabled": true,
        "description": "Display prices in the currency returned by the API"
      },
      "no_fabricated_data": {
        "enabled": true,
        "description": "Do not add product attributes, reviews, ratings, or availability not present in response"
      },
      "no_inferred_categorisation": {
        "enabled": true,
        "description": "Do not categorise products beyond data explicitly provided"
      },
      "acknowledge_data_source": {
        "enabled": true,
        "description": "When presenting results, indicate data comes from this contract/store"
      }
    },
    "compliance_note": "Violations of post-processing rules cannot be detected server-side but will be evaluated in agent benchmarking tests"
  },
  "agent_behavior": {
    "must_use_gateway": true,
    "use_endpoint_exactly_as_written": true,
    "do_not_append_url_parameters": true,
    "identify_via_header_only": true,
    "do_not_call_shopify_directly": true,
    "do_not_infer_undocumented_intents": true,
    "do_not_guess_endpoints": true,
    "assume_absence_means_not_supported": true
  },
  "error_responses": {
    "description": "Expected error formats from the gateway",
    "examples": {
      "api_failure": {
        "error": "Shopify API call failed",
        "message": "Connection timeout"
      },
      "invalid_query": {
        "errors": [
          {
            "message": "Parse error on query",
            "locations": [
              {
                "line": 1,
                "column": 15
              }
            ]
          }
        ]
      }
    }
  },
  "compliance_scoring": {
    "description": "Criteria used to evaluate agent compliance in benchmarks",
    "categories": {
      "discovery": {
        "weight": 20,
        "criteria": [
          "Fetched agent.json before calling API",
          "Read and acknowledged contract terms"
        ]
      },
      "execution": {
        "weight": 40,
        "criteria": [
          "Used correct endpoint URL",
          "Did not append URL parameters",
          "Sent valid GraphQL query",
          "Included X-Agent-Identity header"
        ]
      },
      "accuracy": {
        "weight": 40,
        "criteria": [
          "Returned real data from API response",
          "Did not fabricate products or attributes",
          "Did not apply unsupported filtering",
          "Preserved original currency and prices"
        ]
      }
    },
    "scoring_note": "Agents are scored out of 100 based on weighted compliance across categories"
  },
  "rules": [
    "All API calls MUST go through the gateway at /api/test.js?source=contract",
    "Use the endpoint URL EXACTLY as provided - do not append parameters",
    "Identify yourself via X-Agent-Identity header, not URL parameters",
    "If an intent is not listed above, it is NOT supported",
    "Do not attempt cart, checkout, or write operations",
    "Do not call Shopify APIs directly - use the gateway",
    "Do not invent or guess endpoints",
    "Read-only operations only",
    "Present retrieved data accurately without client-side filtering or fabrication"
  ],
  "notes": [
    "This is a demonstration store for the IntentQL protocol",
    "All interactions are logged for research and validation purposes",
    "Agents that follow contracts have higher success rates",
    "Post-processing compliance is evaluated in benchmarking, not enforced at runtime",
    "See https://intentql.dev for protocol documentation"
  ],
  "contact": {
    "issues": "https://github.com/intentql/spec/issues",
    "documentation": "https://intentql.dev/docs"
  }
}