The Agent Workflow Protocol (AWP) Well-Known Resource and Link Relation

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.¶

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

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:¶

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:¶

{
  "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.¶

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

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