



Network Working Group                                           V. Singh
Internet-Draft                                                  Ajna.inc
Intended status: Standards Track                                D. McKay
Expires: 5 May 2026                                             Verid.id
                                                         1 November 2025


The Agent Workflow Protocol (AWP) Well-Known Resource and Link Relation
                   draft-vinaysingh-awp-wellknown-00

Abstract

   This document registers a Well-Known URI, /.well-known/awp.json, and
   a companion Link Relation Type, awp.  The resource exposes a small,
   machine-readable description of common website workflows (states,
   actions, and resulting events) so automated agents can act
   predictably without scraping.  The format is JSON and intentionally
   minimal.

About This Document

   This note is to be removed before publishing as an RFC.

   Status information for this document may be found at
   https://datatracker.ietf.org/doc/draft-vinaysingh-awp-wellknown/.


   Source for this draft and an issue tracker can be found at
   https://github.com/vinaysingh8866/awp-wellknown-draft.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on 5 May 2026.





Singh & McKay              Expires 5 May 2026                   [Page 1]

Internet-Draft               AWP Well-Known                November 2025


Copyright Notice

   Copyright (c) 2025 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  The AWP Resource  . . . . . . . . . . . . . . . . . . . . . .   2
   3.  Discovery via Link Relation . . . . . . . . . . . . . . . . .   4
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   5
     5.1.  Well-Known URI Registration . . . . . . . . . . . . . . .   5
     5.2.  Link Relation Type Registration . . . . . . . . . . . . .   5
   Appendix A.  References . . . . . . . . . . . . . . . . . . . . .   6
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   6

1.  Introduction

   Automation on the Web often relies on brittle scraping.  Many sites
   already publish machine metadata (e.g., OpenAPI descriptions,
   sitemaps).  This document defines a single optional entry point — a
   Well-Known resource — that advertises a compact, typed map of site
   workflows.  Agents can use it to perform tasks deterministically
   (e.g., sign in, search, checkout).

   This document registers:

   *  the Well-Known URI: /.well-known/awp.json, and

   *  the Link Relation Type: awp.

   The resource is read-only and does not alter authorization; normal
   Web security controls continue to apply.

2.  The AWP Resource

   An origin *MAY* expose a JSON resource at:




Singh & McKay              Expires 5 May 2026                   [Page 2]

Internet-Draft               AWP Well-Known                November 2025


   GET /.well-known/awp.json Content-Type: application/awp+json

   The document contains:

   *  version — semantic version (required),

   *  initial — the starting state (required),

   *  states — a map of state → allowed action names (required),

   *  transitions — event-driven edges (from, event, to) (required),

   *  actions — named HTTP operations with form bindings (required),

   *  schemas — JSON Schema 2020-12 objects referenced by expects/
      produces (required),

   *  site — site metadata with name and baseUrl (required),

   *  template_id — unique identifier (optional),

   *  title — human-readable name (optional),

   *  description — template description (optional),

   *  openapi — link to OpenAPI spec (optional),

   *  policies — rate limiting and other policies (optional).

   A minimal example follows:





















Singh & McKay              Expires 5 May 2026                   [Page 3]

Internet-Draft               AWP Well-Known                November 2025


   {
     "version": "1.0.0",
     "initial": "Anon",
     "states": {
       "Anon":          { "available": ["login"] },
       "Authenticated": { "available": ["search","checkout"] }
     },
     "transitions": [
       { "from": "Anon", "event": "login_ok", "to": "Authenticated" }
     ],
     "actions": {
       "login": {
         "form": { "method": "POST", "target": "/api/login", "contentType": "application/json" },
         "expects":  { "$ref": "#/schemas/LoginInput" },
         "emits": { "onSuccess": "login_ok", "onError": "login_failed" }
       }
     },
     "schemas": {
       "LoginInput": {
         "$schema": "https://json-schema.org/draft/2020-12/schema",
         "type": "object",
         "required": ["email","password"],
         "properties": {
           "email": { "type": "string", "format": "email" },
           "password": { "type": "string", "minLength": 8 }
         }
       }
     },
     "site": {
       "name": "Example Shop",
       "baseUrl": "https://shop.example.com"
     }
   }

   Servers *MAY* use RFC 6570 URI Templates in form.target (e.g., /api/
   search{?q,limit,offset}).  API errors *SHOULD* use RFC 9457 Problem
   Details to allow deterministic branching by clients.

3.  Discovery via Link Relation

   Origins *SHOULD* advertise the resource with:

   Link: </.well-known/awp.json>; rel="awp"

   The awp relation identifies the AWP manifest for the current origin.






Singh & McKay              Expires 5 May 2026                   [Page 4]

Internet-Draft               AWP Well-Known                November 2025


4.  Security Considerations

   *  The manifest is advisory; authentication and authorization remain
      unchanged.

   *  Do not place secrets or user-specific data in the manifest.

   *  Consider cache lifetimes so changes propagate appropriately.

   *  Implement normal rate-limiting/abuse controls on operational
      endpoints referenced by the manifest.

   *  Cross-origin access is governed by existing Web mechanisms (e.g.,
      CORS).

5.  IANA Considerations

5.1.  Well-Known URI Registration

   IANA is requested to register the following in the “Well-Known URIs”
   registry:

   *  *URI Suffix:* awp.json

   *  *Change Controller:* IETF

   *  *Specification Document:* This document, Section 2

   *  *Status:* permanent

   *  *Related Information:* JSON manifest describing site workflows for
      automated agents.

5.2.  Link Relation Type Registration

   IANA is requested to register the following in the “Link Relation
   Types” registry:

   *  *Relation Name:* awp

   *  *Description:* Identifies the Agent Workflow Protocol (AWP)
      manifest for this origin.

   *  *Reference:* This document, Section 3







Singh & McKay              Expires 5 May 2026                   [Page 5]

Internet-Draft               AWP Well-Known                November 2025


Appendix A.  References

   *  RFC 8615 — Well-Known URIs

   *  RFC 8288 — Web Linking

   *  RFC 6570 — URI Templates

   *  RFC 9457 — Problem Details for HTTP APIs

   *  JSON Schema 2020-12 — Core & Validation

Authors' Addresses

   Vinay Singh
   Ajna.inc
   Email: vinay@ajna.inc


   Dave McKay
   Verid.id
   Email: dave@verid.id





























Singh & McKay              Expires 5 May 2026                   [Page 6]
