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: ; 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]