Bruno Sarlo
f2b3a14685
Major revision based on first principles thinking: - Simplified format: plain Markdown, human readable - Focus on capabilities (Can/Cannot) not API schemas - MCP gateway pointer for structured tool access - Clear positioning vs robots.txt and llms.txt The agents.md file is the handshake. The MCP gateway is where real work happens. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
166 lines
3.7 KiB
Markdown
166 lines
3.7 KiB
Markdown
# 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
|
|
```
|