Skip to main content

​
agent.json Service Declaration

​
7.1 What Is agent.json

agent.json is a JSON file placed in your website’s .well-known directory that tells AI agents which AI interaction capabilities your site supports. File path: https://yourdomain.com/.well-known/agent.json Analogy: llms.txt says “who I am”; agent.json says “what I can do.” Think of it as the menu board outside a restaurant — an AI agent can glance at it and immediately know what services are available.

​
7.2 Why You Need agent.json

Agentic commerce is converging around multiple protocol standards (UCP, ACP, MCP, and others). Each merchant supports a different set of protocols and capabilities. agent.json lets AI agents quickly determine:
  • Which commerce protocols do you support?
  • Where are your API endpoints?
  • Do you accept AI agent-initiated orders?
  • What format is your product data in?
Without agent.json, AI agents must rely on guesswork and probing, which is highly inefficient.

​
7.3 agent.json Field Specification

{
  "schema_version": "1.0",
  "name": "Your Brand Name",
  "description": "A one-line description of your business",
  "url": "https://yourdomain.com",
  "logo": "https://yourdomain.com/logo.png",
  "capabilities": {
    "product_discovery": {
      "enabled": true,
      "protocols": ["ucp"],
      "endpoint": "https://yourdomain.com/.well-known/ucp/products",
      "formats": ["json-ld", "json"]
    },
    "checkout": {
      "enabled": false,
      "protocols": [],
      "notes": "Planned for 2026 Q3 via ACP"
    },
    "customer_service": {
      "enabled": true,
      "protocols": ["mcp"],
      "endpoint": "https://yourdomain.com/api/mcp",
      "tools": ["order_status", "return_request", "product_inquiry"]
    }
  },
  "trust": {
    "otr_id": "OTR-xxxx",
    "verification_url": "https://orbexa.io/verify/yourdomain.com"
  },
  "structured_data": {
    "schema_org": true,
    "llms_txt": true,
    "sitemap": "https://yourdomain.com/sitemap.xml"
  },
  "contact": {
    "email": "support@yourdomain.com",
    "support_url": "https://yourdomain.com/support"
  },
  "policies": {
    "privacy": "https://yourdomain.com/privacy",
    "returns": "https://yourdomain.com/returns",
    "terms": "https://yourdomain.com/terms"
  }
}

​
Field Reference

FieldRequiredDescription
schema_versionYesSpecification version number
nameYesBrand / company name
descriptionYesOne-line description
urlYesWebsite URL
capabilitiesYesSupported AI interaction capabilities
capabilities.product_discoveryRecommendedProduct discovery (UCP, etc.)
capabilities.checkoutOptionalCheckout capability (ACP, etc.)
capabilities.customer_serviceOptionalCustomer service (MCP, etc.)
trustRecommendedTrust verification information
structured_dataRecommendedStructured data declarations
policiesRecommendedPolicy page links

​
7.4 Configuration Examples by Merchant Size

​
Small Merchant (Product Display Only)

{
  "schema_version": "1.0",
  "name": "Artisan Leather Co.",
  "description": "Handcrafted genuine leather wallets and belts, free US shipping",
  "url": "https://artisan-leather.com",
  "capabilities": {
    "product_discovery": {
      "enabled": true,
      "protocols": [],
      "formats": ["json-ld"]
    }
  },
  "structured_data": {
    "schema_org": true,
    "llms_txt": true,
    "sitemap": "https://artisan-leather.com/sitemap.xml"
  },
  "contact": {
    "email": "hello@artisan-leather.com"
  }
}

​
Mid-Size Merchant (Product Discovery + Customer Service)

{
  "schema_version": "1.0",
  "name": "Outdoor Explorer",
  "description": "Professional outdoor sports equipment, 8,000+ SKUs",
  "url": "https://outdoor-explorer.com",
  "capabilities": {
    "product_discovery": {
      "enabled": true,
      "protocols": ["ucp"],
      "endpoint": "https://outdoor-explorer.com/api/ucp/products"
    },
    "customer_service": {
      "enabled": true,
      "protocols": ["mcp"],
      "endpoint": "https://outdoor-explorer.com/api/mcp",
      "tools": ["product_search", "order_tracking", "return_request"]
    }
  },
  "structured_data": {
    "schema_org": true,
    "llms_txt": true,
    "sitemap": "https://outdoor-explorer.com/sitemap.xml"
  }
}

​
7.5 Deployment

  1. Create the .well-known directory if it does not exist
  2. Create agent.json inside that directory
  3. Ensure the HTTP response Content-Type is application/json
  4. Ensure robots.txt is not blocking the /.well-known/ path
Platform-specific instructions:
PlatformMethod
NginxCreate .well-known/agent.json under the root directory
ApacheSame as above; ensure the .well-known directory is accessible
Vercel / NetlifyPlace at public/.well-known/agent.json
ShopifyVia App Proxy or custom routing
WordPressCreate .well-known/agent.json in the web root

​
7.6 Verification

After deployment, check:
  1. Visit https://yourdomain.com/.well-known/agent.json
  2. Confirm valid JSON is returned (use JSONLint to validate format)
  3. Confirm the Content-Type is application/json
  4. Confirm all URL links are accessible
Next chapter: Sitemap Optimization — Helping AI crawlers efficiently discover all of your pages