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>
3.7 KiB
3.7 KiB
Example: E-commerce Site
This example shows how an e-commerce site might expose its API to AI agents.
agent.md
---
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