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

Field	Required	Description
`schema_version`	Yes	Specification version number
`name`	Yes	Brand / company name
`description`	Yes	One-line description
`url`	Yes	Website URL
`capabilities`	Yes	Supported AI interaction capabilities
`capabilities.product_discovery`	Recommended	Product discovery (UCP, etc.)
`capabilities.checkout`	Optional	Checkout capability (ACP, etc.)
`capabilities.customer_service`	Optional	Customer service (MCP, etc.)
`trust`	Recommended	Trust verification information
`structured_data`	Recommended	Structured data declarations
`policies`	Recommended	Policy 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

Create the .well-known directory if it does not exist
Create agent.json inside that directory
Ensure the HTTP response Content-Type is application/json
Ensure robots.txt is not blocking the /.well-known/ path

Platform-specific instructions:

Platform	Method
Nginx	Create `.well-known/agent.json` under the `root` directory
Apache	Same as above; ensure the `.well-known` directory is accessible
Vercel / Netlify	Place at `public/.well-known/agent.json`
Shopify	Via App Proxy or custom routing
WordPress	Create `.well-known/agent.json` in the web root

7.6 Verification

After deployment, check:

Visit https://yourdomain.com/.well-known/agent.json
Confirm valid JSON is returned (use JSONLint to validate format)
Confirm the Content-Type is application/json
Confirm all URL links are accessible

Next chapter: Sitemap Optimization — Helping AI crawlers efficiently discover all of your pages

llms.txt writing guide for AI discoverability Sitemap optimization for AI crawlers

Start

Learning Paths

Getting Started with AI Commerce

OTR Open Trust Registry

UCP Universal Commerce Protocol

ACP Agentic Commerce Protocol

MCP Model Context Protocol

SEO for the AI Era

ORBEXA Integrated Solution

Templates & Prompts

Glossary

agent.json service declaration guide

agent.json Service Declaration

7.1 What Is agent.json

7.2 Why You Need agent.json

7.3 agent.json Field Specification

Field Reference

7.4 Configuration Examples by Merchant Size

Small Merchant (Product Display Only)

Mid-Size Merchant (Product Discovery + Customer Service)

7.5 Deployment

7.6 Verification

​agent.json Service Declaration

​7.1 What Is agent.json

​7.2 Why You Need agent.json

​7.3 agent.json Field Specification

​Field Reference

​7.4 Configuration Examples by Merchant Size

​Small Merchant (Product Display Only)

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

​7.5 Deployment

​7.6 Verification

agent.json Service Declaration

7.1 What Is agent.json

7.2 Why You Need agent.json

7.3 agent.json Field Specification

Field Reference

7.4 Configuration Examples by Merchant Size

Small Merchant (Product Display Only)

Mid-Size Merchant (Product Discovery + Customer Service)

7.5 Deployment

7.6 Verification