> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# agent.json service declaration guide

> How to tell AI agents what interaction capabilities you support — agent.json specification, field reference, and deployment guide.

# 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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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**:

| 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:

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

***

**Next chapter**: [Sitemap Optimization](/en/book-6/ch8-sitemap) — Helping AI crawlers efficiently discover all of your pages