v0.2: Simplify spec + add MCP gateway integration
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>
This commit is contained in:
165
examples/ecommerce.md
Normal file
165
examples/ecommerce.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# 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
|
||||
```
|
||||
106
examples/weather-api.md
Normal file
106
examples/weather-api.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# Example: Weather Service
|
||||
|
||||
A simple weather API demonstrating minimal and practical agent.md usage.
|
||||
|
||||
## agent.md
|
||||
|
||||
```yaml
|
||||
---
|
||||
protocol_version: "0.1"
|
||||
name: "Weather Service"
|
||||
description: "Current weather and forecasts for any location"
|
||||
|
||||
tools:
|
||||
- name: get_current
|
||||
description: "Get current weather conditions for a location"
|
||||
endpoint: "GET /api/weather/current"
|
||||
parameters:
|
||||
type: object
|
||||
properties:
|
||||
location:
|
||||
type: string
|
||||
description: "City name, address, or coordinates (lat,lon)"
|
||||
units:
|
||||
type: string
|
||||
enum: ["metric", "imperial"]
|
||||
default: "metric"
|
||||
required:
|
||||
- location
|
||||
response:
|
||||
type: json
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
temperature:
|
||||
type: number
|
||||
feels_like:
|
||||
type: number
|
||||
humidity:
|
||||
type: integer
|
||||
conditions:
|
||||
type: string
|
||||
wind_speed:
|
||||
type: number
|
||||
auth: none
|
||||
rate_limit: "60/minute"
|
||||
|
||||
- name: get_forecast
|
||||
description: "Get weather forecast for upcoming days"
|
||||
endpoint: "GET /api/weather/forecast"
|
||||
parameters:
|
||||
type: object
|
||||
properties:
|
||||
location:
|
||||
type: string
|
||||
days:
|
||||
type: integer
|
||||
minimum: 1
|
||||
maximum: 14
|
||||
default: 7
|
||||
units:
|
||||
type: string
|
||||
enum: ["metric", "imperial"]
|
||||
default: "metric"
|
||||
required:
|
||||
- location
|
||||
auth: api_key
|
||||
rate_limit: "30/minute"
|
||||
|
||||
- name: get_alerts
|
||||
description: "Get active weather alerts for a location"
|
||||
endpoint: "GET /api/weather/alerts"
|
||||
parameters:
|
||||
type: object
|
||||
properties:
|
||||
location:
|
||||
type: string
|
||||
required:
|
||||
- location
|
||||
auth: none
|
||||
|
||||
auth:
|
||||
api_key:
|
||||
header: "X-Weather-Key"
|
||||
obtain: "https://weather.example/api-keys"
|
||||
description: "Free tier: 1000 requests/day"
|
||||
|
||||
rate_limits:
|
||||
global: "1000/day"
|
||||
|
||||
contact:
|
||||
url: "https://weather.example/api/docs"
|
||||
---
|
||||
|
||||
# Weather API for Agents
|
||||
|
||||
Simple, reliable weather data.
|
||||
|
||||
## Free Tools
|
||||
- Current conditions (no key needed)
|
||||
- Weather alerts (no key needed)
|
||||
|
||||
## API Key Required
|
||||
- Extended forecasts (up to 14 days)
|
||||
|
||||
Get your free API key at weather.example/api-keys
|
||||
```
|
||||
Reference in New Issue
Block a user