Agent Affordance Layer

Today, AI browser agents read a page one of two ways: a screenshot — universal, but expensive and fragile — or a scraped accessibility tree, built for screen readers rather than for an agent deciding what to do next. Neither format says what an action costs, whether it can be undone, or whether a human needs to sign off first.

There's no standard way for a site to declare its affordances — the actions an agent can take, what they risk, and what's safe to run without asking. ARIA describes structure. llms.txt describes content. MCP replaces the GUI outright. AAL fills the gap between them: a page keeps its ordinary interface, and tells an agent, in a few hundred bytes, exactly what it's allowed to do with it.

• WAI-ARIADescribes UI structure for assistive tech. AAL describes action semantics, cost, reversibility, and flow state — not structure.
• llms.txtContent discovery for LLMs. AAL is action discovery: not what a page says, what it lets you do.
• ai-agent.jsonSite-wide agent permissions. AAL is per-page and per-action — finer grained, and it names a cost and a trust class for each one.
• MCPReplaces the GUI with a server-side API. AAL annotates the GUI itself, so an agent can use the page the way a person does — no per-site server required.

Modeled, not measured. These rows are the spec's own motivating estimate (anchored on Sonnet-class pricing at $3/M input tokens and ~0.0003 Wh per inference token) — not bench output. A Playwright + Claude empirical bench (30 task fixtures, three perception modes) is built to replace this table with a real number, but it hasn't been run. Read this as an upper-bound estimate of the gap, not a proven multiplier.

A site serves a manifest at /.well-known/agent-affordances.json, pointing to per-route fragments. Each affordance in a fragment carries a stable id, an action type, a human-readable label, and — the part that matters — a trust classification.

{
  "aal": "0.1",
  "page": "/checkout",
  "flow": { "id": "checkout", "step": 2, "of": 4 },
  "affordances": [
    {
      "id": "submit-order",
      "selector": "[data-aal=submit-order]",
      "action": "purchase",
      "label": "Place Order",
      "destructive": true,
      "reversible": false,
      "trust": "financial",
      "cost": { "currency": "USD", "amount": 49.00 },
      "preconditions": ["cart.non_empty", "payment.attached"],
      "success_schema": { "order_id": "string", "confirmation_url": "string" }
    }
  ]
}

Every affordance is checked against a JSON Schema before an agent acts on it — field-length caps, a closed set of action types, and a label pattern that blocks control characters and zero-width Unicode (v0.1.1's answer to cloaking attacks).

A conforming consumer must not autonomously execute an affordance when it's destructive and irreversible, when its trust class is financial or admin, or when it carries a non-zero cost — unless a human has explicitly granted authority for that class of action. Free-text fields (id, label) are treated as data, never as instructions to the agent's model, and must be shown to the human verbatim before anything happens. A publisher marking a purchase as "non-destructive" doesn't relax the gate — v0.1.1 overrides purchase, delete, and known-financial submit actions regardless of what's declared.

1. Add stable identifiers.

   Put a data-aal attribute on the interactive elements you want an agent to use.

2. Publish a manifest.

   Serve /.well-known/agent-affordances.json, pointing to per-route fragments.

3. Validate against the schema.

   The JSON Schema (schema/aal-0.1.json in the repo) enforces the v0.1.1 size caps and field constraints before anything ships.

4. Test against a reference consumer.

   NEXUS, Trinity's agent coordination platform, ships fetch_affordances and execute_affordance MCP tools that already consume this spec.

v0.x may break across minor versions; from v1.0 on, minors stay backward-compatible and only a major bump breaks anything. Field-level or wire-format changes go through an open RFC — a GitHub issue, a seven-day discussion window, then a PR against the spec, the schema, and at least one example. Wording fixes and new examples don't need one. The aim is to graduate AAL to a vendor-neutral working group once adoption justifies it — it isn't there yet.