> ## 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服务声明配置指南

> agent.json服务声明文件的完整配置指南，详解schema_version、capabilities和authentication等全部核心字段规范，覆盖UCP商品发现、ACP结账和MCP客服等AI交互协议的声明方法，提供JSON Schema验证工具使用方法与生产环境部署最佳实践

# agent.json 服务声明

## 7.1 什么是agent.json

`agent.json` 是放在网站 `.well-known` 目录下的JSON文件，告诉AI代理你的网站支持哪些AI交互能力。

**文件路径**: `https://你的域名/.well-known/agent.json`

**类比**: llms.txt是"我是谁"，agent.json是"我能做什么"。就像餐厅门口的菜单牌，AI代理看一眼就知道这家店支持哪些服务。

## 7.2 为什么需要agent.json

AI代理商务正在形成多个协议标准（UCP、ACP、MCP等）。每个商家支持的协议和能力不同。agent.json让AI代理快速判断：

* 你支持哪些商务协议？
* 你的API端点在哪里？
* 你接受AI代理下单吗？
* 你的商品数据格式是什么？

没有agent.json，AI代理只能靠猜测和试探，效率很低。

## 7.3 agent.json字段规范

```json theme={null}
{
  "schema_version": "1.0",
  "name": "你的品牌名",
  "description": "一句话描述你的业务",
  "url": "https://你的域名",
  "logo": "https://你的域名/logo.png",
  "capabilities": {
    "product_discovery": {
      "enabled": true,
      "protocols": ["ucp"],
      "endpoint": "https://你的域名/.well-known/ucp/products",
      "formats": ["json-ld", "json"]
    },
    "checkout": {
      "enabled": false,
      "protocols": [],
      "notes": "计划2026年Q3接入ACP"
    },
    "customer_service": {
      "enabled": true,
      "protocols": ["mcp"],
      "endpoint": "https://你的域名/api/mcp",
      "tools": ["order_status", "return_request", "product_inquiry"]
    }
  },
  "trust": {
    "otr_id": "OTR-xxxx",
    "verification_url": "https://orbexa.io/zh/verify/你的域名"
  },
  "structured_data": {
    "schema_org": true,
    "llms_txt": true,
    "sitemap": "https://你的域名/sitemap.xml"
  },
  "contact": {
    "email": "support@你的域名",
    "support_url": "https://你的域名/support"
  },
  "policies": {
    "privacy": "https://你的域名/privacy",
    "returns": "https://你的域名/returns",
    "terms": "https://你的域名/terms"
  }
}
```

### 字段说明

| 字段                               | 必填 | 说明           |
| -------------------------------- | -- | ------------ |
| `schema_version`                 | 是  | 规范版本号        |
| `name`                           | 是  | 品牌/公司名       |
| `description`                    | 是  | 一句话描述        |
| `url`                            | 是  | 网站URL        |
| `capabilities`                   | 是  | 支持的AI交互能力    |
| `capabilities.product_discovery` | 推荐 | 商品发现能力（UCP等） |
| `capabilities.checkout`          | 可选 | 下单能力（ACP等）   |
| `capabilities.customer_service`  | 可选 | 客服能力（MCP等）   |
| `trust`                          | 推荐 | 信任验证信息       |
| `structured_data`                | 推荐 | 结构化数据声明      |
| `policies`                       | 推荐 | 政策页面链接       |

## 7.4 不同规模商家的配置示例

### 小型商家（仅商品展示）

```json theme={null}
{
  "schema_version": "1.0",
  "name": "小明手工皮具",
  "description": "手工真皮钱包和皮带，江浙沪包邮",
  "url": "https://xiaoming-leather.com",
  "capabilities": {
    "product_discovery": {
      "enabled": true,
      "protocols": [],
      "formats": ["json-ld"]
    }
  },
  "structured_data": {
    "schema_org": true,
    "llms_txt": true,
    "sitemap": "https://xiaoming-leather.com/sitemap.xml"
  },
  "contact": {
    "email": "xiaoming@example.com"
  }
}
```

### 中型商家（商品发现 + 客服）

```json theme={null}
{
  "schema_version": "1.0",
  "name": "户外探索家",
  "description": "专业户外运动装备，8000+ SKU",
  "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 部署方法

1. 创建 `.well-known` 目录（如果不存在）
2. 在该目录下创建 `agent.json` 文件
3. 确保HTTP响应的Content-Type是 `application/json`
4. 确保robots.txt没有屏蔽 `/.well-known/` 路径

**各平台操作**:

| 平台                 | 方法                                      |
| ------------------ | --------------------------------------- |
| **Nginx**          | 在 `root` 目录下创建 `.well-known/agent.json` |
| **Apache**         | 同上，确保 `.well-known` 目录可访问               |
| **Vercel/Netlify** | 放在 `public/.well-known/agent.json`      |
| **Shopify**        | 通过App代理或自定义路由                           |
| **WordPress**      | 在根目录创建 `.well-known/agent.json`         |

## 7.6 验证

部署后检查：

1. 访问 `https://你的域名/.well-known/agent.json`
2. 确认返回正确的JSON（用 [JSONLint](https://jsonlint.com/) 验证格式）
3. 确认Content-Type是 `application/json`
4. 确认所有URL链接可访问

***

**下一章**: [Sitemap优化](/zh/book-6/ch8-sitemap) — 让AI爬虫高效发现你的所有页面