# Example: E-commerce Site

This example shows how an e-commerce site might expose its API to AI agents.

## agent.md

```yaml
---
protocol_version: "0.1"
name: "Tech Store"
description: "Browse products, check prices, and manage wishlists"

robots:
  disallow:
    - /admin
    - /checkout
    - /account/orders
  crawl_delay: 2

tools:
  - name: search_products
    description: "Search for products by name, category, or features"
    endpoint: "GET /api/products/search"
    parameters:
      type: object
      properties:
        q:
          type: string
          description: "Search query"
        category:
          type: string
          enum: ["laptops", "phones", "tablets", "accessories"]
        min_price:
          type: number
          minimum: 0
        max_price:
          type: number
        in_stock:
          type: boolean
          default: true
        sort:
          type: string
          enum: ["price_asc", "price_desc", "rating", "newest"]
          default: "rating"
        limit:
          type: integer
          default: 20
          maximum: 50
      required:
        - q
    auth: none
    rate_limit: "100/minute"

  - name: get_product
    description: "Get detailed product information including specs and reviews"
    endpoint: "GET /api/products/{id}"
    parameters:
      type: object
      properties:
        id:
          type: string
        include_reviews:
          type: boolean
          default: false
      required:
        - id
    auth: none

  - name: compare_products
    description: "Compare specifications of multiple products"
    endpoint: "POST /api/products/compare"
    parameters:
      type: object
      properties:
        product_ids:
          type: array
          items:
            type: string
          minItems: 2
          maxItems: 5
      required:
        - product_ids
    auth: none

  - name: get_price_history
    description: "Get price history for a product"
    endpoint: "GET /api/products/{id}/price-history"
    parameters:
      type: object
      properties:
        id:
          type: string
        days:
          type: integer
          default: 30
          maximum: 365
      required:
        - id
    auth: api_key
    scopes:
      - price:read

  - name: add_to_wishlist
    description: "Add a product to user's wishlist"
    endpoint: "POST /api/wishlist"
    parameters:
      type: object
      properties:
        product_id:
          type: string
        notify_on_sale:
          type: boolean
          default: true
      required:
        - product_id
    auth: oauth2
    scopes:
      - wishlist:write

auth:
  api_key:
    header: "X-API-Key"
    obtain: "https://techstore.example/developers"

  oauth2:
    authorization_url: "https://techstore.example/oauth/authorize"
    token_url: "https://techstore.example/oauth/token"
    scopes:
      wishlist:read: "View your wishlist"
      wishlist:write: "Modify your wishlist"
      price:read: "Access price history data"

rate_limits:
  global: "1000/hour"
  per_tool: true

contact:
  email: "api@techstore.example"
  url: "https://techstore.example/developers/docs"
---

# Tech Store Agent API

AI agents can help users find products, compare prices, and track deals.

## Public Tools (No Auth)

- **search_products** - Find products by name or category
- **get_product** - Get detailed product info
- **compare_products** - Side-by-side comparison

## Authenticated Tools

### API Key Required
- **get_price_history** - Historical pricing data

### OAuth2 Required
- **add_to_wishlist** - Save products for later

## Best Practices

1. Cache product details (they don't change often)
2. Use price history to advise on purchase timing
3. Respect rate limits during peak hours
```