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

Field	Type	Required	Description
`awp_version`	string	yes	Spec version (e.g. `"0.2"`)
`domain`	string	yes	Canonical domain this file applies to
`intent`	string	yes	Plain language description of the surface
`protocols`	object	no	Other agent protocols this surface speaks (see §5.5)
`capabilities`	object	no	Feature flags (see §6)
`auth`	object	no	Authentication contract (see §7)
`entities`	object	no	Typed data models (see §8)
`actions`	array	yes	Declared actions (see §9)
`errors`	object	no	Error recovery contracts (see §10)
`dependencies`	object	no	Action prerequisite graph (see §11)
`agent_hints`	object	no	Semantic planning guidance (see §12)
`agent_status`	object	no	Liveness signal (see §13)

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:

Field	Type	Required	Description
`version`	string	yes	Protocol version this surface conforms to
`endpoint`	string (url)	conditional	Where to reach the protocol. Required for transport/tool protocols; optional for payment-only declarations

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.

Identifier	Standard	Layer
`a2a`	Agent-to-Agent (Google)	Transport / messaging
`mcp`	Model Context Protocol (Anthropic)	Tool invocation
`acp`	Agent Communication Protocol (IBM)	Messaging
`ap2`	Agent Payments Protocol (Google)	Payment
`x402`	HTTP 402 + crypto wallet (Coinbase)	Payment
`skyfire`	Skyfire agent payments	Payment / identity
`openapi`	OpenAPI / Swagger	API description
`graphql`	GraphQL	API description
`payment`	Generic payment hand-off (e.g. hosted checkout link)	Payment

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
}

Field	Type	Description
`streaming`	boolean	Whether endpoints support streaming responses
`batch_actions`	boolean	Whether multiple actions can be submitted together
`webhooks`	boolean	Whether async results can be delivered via webhook
`pagination`	string	Pagination style: `cursor`, `offset`, `page`, or `none`
`idempotency`	boolean	Whether idempotency keys are supported

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"
}

Field	Type	Description
`required_for`	array[string]	Action IDs that require authentication
`optional_for`	array[string]	Action IDs where auth is optional
`type`	string	Auth type: `oauth2`, `api_key`, `bearer`, `none`
`token_expiry`	string	Token lifetime (e.g. `"24h"`, `"7d"`)
`refresh_endpoint`	string	Endpoint to refresh expired tokens

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

Type	Description
`string`	UTF-8 string
`integer`	Whole number
`float`	Decimal number
`boolean`	true / false
`ISO8601`	Date or datetime string
`url`	Fully qualified URL
`enum[a, b, c]`	One of a defined set of values
`array[type]`	List of typed items
`object[entity]`	Reference to a named entity

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

Field	Type	Required	Description
`id`	string	yes	Unique identifier for this action
`description`	string	yes	Plain language description for agent planning
`auth_required`	boolean	yes	Whether authentication is required
`inputs`	object	yes	Typed input parameters
`outputs`	object	yes	Typed output fields
`endpoint`	string	conditional	API endpoint path. Required unless `via` references a protocol that supplies the endpoint
`method`	string	conditional	HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`. Required unless `via` is set
`via`	string	no	Identifier of a protocol declared in `protocols` (see §5.5). When set, the action is invoked through that protocol
`operation`	string	no	Protocol-specific operation name when `via` is set (e.g. an A2A method, an MCP tool name)
`rate_limit`	string	no	Rate limit (e.g. `"30/minute"`)
`idempotency`	object	no	Idempotency contract (see below)
`execution_model`	string	no	`sync` (default) or `async`
`poll_endpoint`	string	no	For async: endpoint to check job status
`sensitivity`	string	no	`standard`, `destructive`, or `irreversible`
`requires_human_confirmation`	boolean	no	Agent SHOULD prompt user before executing
`reversible`	boolean	no	Whether the action can be undone

Input parameter fields

Field	Type	Required	Description
`type`	string	yes	Data type
`required`	boolean	no	Defaults to false
`default`	any	no	Default value if not provided
`options`	array	no	Valid values for enum types
`description`	string	no	Additional context for the agent

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"
}

Field	Type	Description
`operational`	boolean	Whether the surface is currently available
`degraded_actions`	array[string]	Action IDs currently impaired
`status_endpoint`	string	Endpoint for real-time 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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Agent Web Protocol — Specification v0.2

1. Overview

2. Design Goals

3. Discovery

4. Versioning

5. Top-Level Fields

5.5 Protocols

Field structure

Registered protocol identifiers

Linking actions to protocols

Why this exists

6. Capabilities

7. Auth

8. Entities

Supported primitive types

9. Actions

Action fields

Input parameter fields

Sensitivity levels

10. Errors

11. Dependencies

12. Agent Hints

13. Agent Status

14. Synthetic agent.json

15. Conformance

16. Changelog

v0.2 (2026-04-16)

v0.1 (2026-03-16)

Contributing

FilesExpand file tree

SPEC.md

Latest commit

History

SPEC.md

File metadata and controls

Agent Web Protocol — Specification v0.2

1. Overview

2. Design Goals

3. Discovery

4. Versioning

5. Top-Level Fields

5.5 Protocols

Field structure

Registered protocol identifiers

Linking actions to protocols

Why this exists

6. Capabilities

7. Auth

8. Entities

Supported primitive types

9. Actions

Action fields

Input parameter fields

Sensitivity levels

10. Errors

11. Dependencies

12. Agent Hints

13. Agent Status

14. Synthetic agent.json

15. Conformance

16. Changelog

v0.2 (2026-04-16)

v0.1 (2026-03-16)

Contributing