Agent Web Protocol — Specification v0.2

Status: Draft RFC
Published: 2026-04-16
Authors: Agent Web Protocol contributors
License: MIT

1. Overview

Agent Web Protocol (AWP) is an open standard for declaring any digital surface — website, API, document, or authentication flow — as agent-ready.

The core artifact is agent.json: a machine-readable file published at the root of any web domain, telling AI agents exactly what they can do, what inputs they need, and how to recover from errors.

2. Design Goals

• Discoverable — agents find it without prior configuration
• Minimal — the core is small enough to implement in an afternoon
• Recoverable — every failure state has a machine-readable recovery path
• Extensible — unknown fields are ignored, not fatal
• Stable — core fields do not change between minor versions

3. Discovery

A conforming agent.json file MUST be published at:

https://{domain}/agent.json

This follows the same convention as robots.txt and sitemap.xml.
Agents SHOULD attempt GET /agent.json as the first step when interacting with any new domain. The server MUST return Content-Type: application/json.

4. Versioning

The awp_version field declares the spec version the file conforms to.

MAJOR.MINOR

• Minor versions add optional fields. Backward compatible.
• Major versions may introduce breaking changes.
• Agents encountering an unknown major version SHOULD degrade gracefully rather than fail entirely.

Current version: 0.2

5. Top-Level Fields

5.5 Protocols

AWP is the discovery layer — the manifest. Many surfaces also speak one or more transport, tool-invocation, or payment protocols. The protocols field declares them so an agent reading agent.json knows, in a single fetch, every standard the surface supports and where to reach it.

"protocols": {
  "a2a": {
    "version": "0.3",
    "endpoint": "https://agent.example.com/agent/message",
    "agent_card": "https://agent.example.com/.well-known/agent-card.json"
  },
  "mcp": {
    "version": "2025-06-18",
    "endpoint": "https://mcp.example.com",
    "transport": "http"
  },
  "x402": {
    "version": "1.0",
    "wallet": "0x..."
  },
  "payment": {
    "type": "stripe_link",
    "agent_op": "checkout.create"
  }
}

Field structure

Each entry is keyed by a protocol identifier (lowercase, hyphenated). The value is an object with at least:

Additional protocol-specific fields are allowed (e.g. agent_card for A2A, transport for MCP, wallet for x402). Agents MUST ignore unknown protocol-specific fields rather than fail.

Registered protocol identifiers

The following identifiers SHOULD be used when a surface speaks a known standard. This list is informative; surfaces MAY declare additional custom protocols.

Linking actions to protocols

Actions MAY include an optional via field naming a protocol declared in protocols. Agents use this to route the action through the correct protocol client.

"actions": [
  { "id": "list_products", "via": "a2a", "operation": "product.search" },
  { "id": "checkout",      "via": "a2a", "operation": "checkout.create" }
]

When an action has via, the named protocol MUST appear in protocols. When an action omits via, agents SHOULD assume direct HTTP at the declared endpoint/method (the v0.1 default behavior).

Why this exists

Other agent protocols define how to talk. AWP defines who to talk to. By declaring sibling protocols inside agent.json, a surface gives every agent a single bootstrap URL — /agent.json — from which all other standards become reachable. Agents no longer guess the transport.

6. Capabilities

Optional feature flags agents can check before planning actions.

"capabilities": {
  "streaming": false,
  "batch_actions": true,
  "webhooks": true,
  "pagination": "cursor",
  "idempotency": true
}

7. Auth

Declares the authentication contract for the surface.

"auth": {
  "required_for": ["book", "manage_trip"],
  "optional_for": ["search"],
  "type": "oauth2",
  "token_expiry": "24h",
  "refresh_endpoint": "/api/auth/refresh"
}

8. Entities

Named, typed data models that actions reference in inputs and outputs.

"entities": {
  "flight": {
    "fields": {
      "flight_number": "string",
      "origin": "airport_code",
      "destination": "airport_code",
      "departure_time": "ISO8601",
      "price_usd": "float",
      "cabin_class": "enum[economy, business, first]"
    }
  }
}

Entities are referenced in action inputs/outputs as object[entity_name] or array[entity_name].

Supported primitive types

9. Actions

The core of agent.json. Each action represents something an agent can do.

"actions": [
  {
    "id": "search_flights",
    "description": "Search available flights between two airports",
    "auth_required": false,
    "inputs": {
      "origin": { "type": "airport_code", "required": true },
      "destination": { "type": "airport_code", "required": true },
      "date": { "type": "ISO8601", "required": true },
      "cabin_class": {
        "type": "enum",
        "options": ["economy", "business", "first"],
        "default": "economy"
      }
    },
    "outputs": {
      "flights": "array[flight]",
      "search_token": "string"
    },
    "endpoint": "/api/flights/search",
    "method": "POST",
    "rate_limit": "30/minute",
    "idempotency": {
      "supported": true,
      "key_field": "idempotency_key",
      "window": "24h"
    },
    "execution_model": "sync"
  }
]

Action fields

Input parameter fields

Sensitivity levels

Actions SHOULD declare sensitivity when they have consequences:

• standard — default, no special handling required
• destructive — modifies or deletes data, agent SHOULD confirm
• irreversible — cannot be undone, agent MUST confirm with user

10. Errors

Maps error codes to machine-readable recovery instructions.

"errors": {
  "AUTH_EXPIRED": {
    "recovery": "call /api/auth/refresh then retry original action"
  },
  "RATE_LIMITED": {
    "recovery": "wait 60 seconds then retry"
  },
  "SEAT_UNAVAILABLE": {
    "recovery": "retry search_flights with different parameters"
  },
  "INVALID_AIRPORT_CODE": {
    "recovery": "query /api/airports?search={input} to find valid codes"
  }
}

Recovery instructions MUST be actionable by a machine. They SHOULD reference specific endpoints or actions where applicable.

11. Dependencies

Declares prerequisite relationships between actions.

"dependencies": {
  "book_flight": ["search_flights"],
  "check_in": ["book_flight"],
  "select_seat": ["book_flight"]
}

Agents MUST execute prerequisite actions and obtain required outputs before attempting a dependent action.

12. Agent Hints

Semantic guidance to improve agent planning. Free-form key-value pairs.

"agent_hints": {
  "optimal_search_window": "search at least 24h before departure",
  "price_volatility": "high — cache search results max 5 minutes",
  "auth_note": "search does not require auth — only call auth when booking"
}

Agents SHOULD incorporate hints into planning but MUST NOT treat them as hard constraints.

13. Agent Status

Optional liveness signal. Allows agents to check operational state before planning actions.

"agent_status": {
  "operational": true,
  "degraded_actions": ["book_flight"],
  "status_endpoint": "/api/status"
}

14. Synthetic agent.json

When a domain has not published a native agent.json, agents MAY use a synthetic file generated by a trusted intermediary. Middleware tools can generate a synthetic agent.json for any URL on demand.

Synthetic files MUST declare their origin:

"source": "synthetic",
"generated_by": "synthetic-agent-json-generator",
"confidence": 0.87,
"last_verified": "2026-03-15T10:00:00Z"

Agents SHOULD treat synthetic files as lower-confidence than native files and SHOULD prefer native files when available.

15. Conformance

A conforming agent.json file MUST:

• Be valid JSON
• Include awp_version, domain, intent, and actions
• Publish at https://{domain}/agent.json
• Return Content-Type: application/json

A conforming agent.json file SHOULD:

• Declare error recovery for all expected failure states
• Include description on every action
• Declare sensitivity on destructive or irreversible actions

A conforming agent.json file MAY:

• Include any additional fields not defined in this spec
• Unknown fields MUST be ignored by agents

16. Changelog

v0.2 (2026-04-16)

• Added protocols top-level field (§5.5) — declares sibling agent protocols a surface speaks (A2A, MCP, ACP, AP2, x402, etc.) so agents can route via known transports
• Added optional via and operation fields on actions, linking actions to a declared protocol
• Reference implementation: laclawclaw.com/.well-known/agent.json
• Backward compatible — v0.1 files validate as v0.2

v0.1 (2026-03-16)

• Initial draft
• Core fields: actions, auth, entities, errors, dependencies, agent_hints
• Synthetic agent.json declaration
• Sensitivity and human confirmation fields
• Agent status liveness signal

Contributing

Propose changes via GitHub issues and pull requests. Contact: spec@agentwebprotocol.org