Spec

Protocol Specification

The complete AWP 1.0 specification. This document defines all schemas, endpoint contracts, token budgets, authentication patterns, and compliance requirements.

Version1.0

StatusStable

Published2026-06-25

LicenseMIT

Overview

The Agentic Web Protocol (AWP) defines how websites expose structured, token-optimized content to AI agents. It consists of:

A Discovery Manifest at a well-known URL (/.well-known/agentic-web-protocol.json)
A set of Content Endpoints under /awp/ with standardized paths
Token budgets that keep all content within LLM context window limits
Optional Function Schemas that describe callable APIs in a machine-readable way
Optional MCP integration for agent-to-server communication

Discovery Manifest Schema

The discovery manifest is the entry point for all agent interaction. It MUST be served at /.well-known/agentic-web-protocol.json.

ValidationValidate your manifest at Tools → Interactive Validator or with npx create-awp validate.

JSON Schema — Discovery Manifest
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "AWP Discovery Manifest",
  "description": "Served at /.well-known/agentic-web-protocol.json",
  "type": "object",
  "required": ["version", "name", "description", "capabilities", "endpoints"],
  "properties": {
    "version":      { "type": "string", "const": "1.0" },
    "name":         { "type": "string", "minLength": 1, "maxLength": 100 },
    "description":  { "type": "string", "minLength": 10, "maxLength": 2000 },
    "capabilities": {
      "type": "array",
      "minItems": 1,
      "uniqueItems": true,
      "items": { "type": "string", "enum": ["content", "api", "search", "mcp", "analytics"] }
    },
    "endpoints": {
      "type": "object",
      "required": ["manifest"],
      "properties": {
        "manifest": { "type": "string", "pattern": "^/" },
        "content":  { "type": "string" },
        "api":      { "type": "string" },
        "mcp":      { "type": "string" }
      }
    },
    "authentication": {
      "type": "object",
      "properties": {
        "required": { "type": "boolean" },
        "methods":  { "type": "array", "items": { "type": "string" } },
        "registration": { "type": "string" }
      }
    },
    "rate_limits": {
      "type": "object",
      "properties": {
        "requests_per_minute": { "type": "integer", "minimum": 1 },
        "requests_per_day":    { "type": "integer", "minimum": 1 }
      }
    },
    "llms_txt":       { "type": "string" },
    "a2a_agent_card": { "type": "string" },
    "updated_at":     { "type": "string", "format": "date-time" }
  }
}

Function Schema

Function schemas let agents discover and call your API endpoints without reading HTML docs. They are served at /awp/api/tools/functions.json.

functions.json example
{
  "version": "1.0",
  "functions": [
    {
      "name": "search_products",
      "description": "Search the product catalog by keyword, category, and price range",
      "method": "GET",
      "path": "/api/v1/products",
      "parameters": {
        "type": "object",
        "properties": {
          "q":        { "type": "string",  "description": "Search query" },
          "category": { "type": "string",  "enum": ["electronics", "fashion"] },
          "max_price": { "type": "number", "minimum": 0 },
          "limit":    { "type": "integer", "default": 20, "maximum": 100 }
        },
        "required": ["q"]
      },
      "returns": { "type": "object", "description": "Paginated product list" },
      "tags": ["products"],
      "auth_required": false
    }
  ]
}

Token Budgets

All AWP content files have strictly enforced token budgets. These budgets ensure content fits within LLM context windows and keeps agent costs predictable.

Token counting uses the GPT-4 tokenizer (tiktoken). Approximate: 1 token ≈ 4 characters.

Content TypeMax Tokens~Characters

Discovery manifest description200~800

Content summary (summary.md)500~2,000

Agent instructions300~1,200

Per-page content2,000~8,000

API endpoint description100~400

Function description150~600

llms.txt intro200~800

Token budget enforcement

Validators will flag content that exceeds its budget as a warning. Marketplace ranking penalizes sites that consistently exceed budgets.

Endpoint Contracts

All AWP endpoints MUST include the X-AWP-Version: 1.0 header and allow CORS from all origins.

Endpoint contracts

## Standard AWP Endpoint Contracts

GET /.well-known/agentic-web-protocol.json
  Status: 200
  Content-Type: application/json; charset=utf-8
  X-AWP-Version: 1.0
  Cache-Control: public, max-age=3600
  Access-Control-Allow-Origin: *

GET /awp/manifest.json
  Status: 200 (same headers as above)
  Body: full site manifest with capabilities and content map

GET /awp/content/summary.md
  Content-Type: text/markdown; charset=utf-8
  Body: ≤500 token markdown summary

GET /awp/content/structure.json
  Content-Type: application/json; charset=utf-8
  Body: site navigation and section list

GET /awp/instructions.md
  Content-Type: text/markdown; charset=utf-8
  Body: ≤300 token agent instructions

Versioning Policy

VERSIONING.md
## Versioning Policy

AWP follows semantic versioning (SemVer):
- **MAJOR** (e.g., 2.0): Breaking changes to required fields or endpoint contracts
- **MINOR** (e.g., 1.1): New optional fields or capabilities added
- **PATCH** (e.g., 1.0.1): Clarifications, doc fixes, no schema changes

All manifests MUST declare "version": "1.0".
Servers MUST serve X-AWP-Version: 1.0 on all AWP responses.
Agents SHOULD degrade gracefully when encountering unknown fields.

Compliance Checklist

Use this checklist to verify your implementation is fully AWP 1.0 compliant before submitting to the marketplace.

Compliance checklist
## AWP 1.0 Compliance Checklist

### Required
☑ /.well-known/agentic-web-protocol.json responds with valid JSON
☑ version field is exactly "1.0"
☑ name, description, capabilities, endpoints.manifest are present
☑ All content within token budgets
☑ X-AWP-Version: 1.0 header on all /awp/ responses
☑ CORS: Access-Control-Allow-Origin: * on all AWP endpoints

### Recommended
☐ /awp/content/summary.md present and ≤500 tokens
☐ /awp/content/structure.json present
☐ /awp/instructions.md present  
☐ /llms.txt present
☐ endpoints.content in manifest
☐ updated_at timestamp within last 30 days
☐ authentication object declared (even if required: false)
☐ rate_limits declared

Automated compliance checkRun npx create-awp analyze https://yoursite.com to get a full automated compliance report with specific line-level fixes.