Skip to main content
Target Audience:All Audiences

What is AXAG?

AXAG (Agent Experience Accessibility Guidelines) is an annotation standard that makes interface semantics explicit and machine-readable for AI agents. It defines a semantic interaction contract — a formal declaration of what each interface element means, what it does, what it requires, and what it produces.

AX defines the discipline. AXAG defines the executable semantic contract.

AXAG Is Not Just Metadata​

AXAG is frequently misunderstood as a metadata format — a way to add descriptive labels to UI elements. This undersells its purpose.

AXAG is a semantic interaction contract. It declares:

DimensionWhat It Answers
IntentWhat is this interaction trying to accomplish?
EntityWhat domain object does this interaction operate on?
Action TypeIs this a read, write, delete, or navigate operation?
ParametersWhat inputs does this interaction require?
ConstraintsWhat rules govern valid inputs?
PreconditionsWhat state must be true before execution?
PostconditionsWhat state will be true after execution?
ScopeWhat boundary (tenant, user, org) does this operate within?
Risk LevelHow dangerous is this operation?
ConfirmationDoes this require explicit confirmation?
ApprovalDoes this require multi-party approval?
IdempotencyIs it safe to repeat this operation?
Side EffectsWhat observable changes does this produce?

This contract becomes the source of truth for two downstream artifacts:

  1. Semantic Manifest — A structured document that exposes all available operations
  2. MCP Tool Registry — Generated tool definitions that agent runtimes consume

The Architecture​

Layer 1: Human Interface​

The visual, interactive surface designed for human users. Buttons, forms, tables, navigation — everything a human sees and interacts with.

Layer 2: AXAG Semantic Contract​

The machine-readable contract that declares the meaning, intent, constraints, and execution semantics of interface interactions. This contract exists as annotations on UI elements.

Layer 3: Semantic Manifest​

A derived artifact generated from AXAG annotations. It exposes discoverable, structured operations with parameter schemas, constraint declarations, and safety metadata.

Layer 4: MCP Tool Registry​

A generated tool surface following the Model Context Protocol (MCP) specification. Agent runtimes consume this registry to discover and invoke operations deterministically.

Layer 5: Agent Runtime​

The planning and execution layer. It reads the tool registry, selects appropriate tools, validates constraints, and performs operations — all without scraping or visual inference.

In a browser, tools reach the agent through WebMCP, registered for as long as their UI is on screen. The server behind them enforces what the contract declared, so an agent can't skip a confirmation or cross a tenant boundary by calling the API directly. See The SDK.

A Concrete Example​

Consider a search button on an e-commerce product page.

Without AXAG​

<button class="btn btn-primary search-btn" onclick="doSearch()">
  Search
</button>

An agent looking at this button knows:

  • There is a button
  • It says "Search"
  • It has a CSS class search-btn

The agent does not know:

  • What entity is being searched
  • What parameters the search requires
  • What scope the search operates within
  • Whether the operation has side effects
  • What the expected response structure is

With AXAG​

🔬 Proposed Implementation Pattern

The following annotation syntax is a Proposed Implementation Pattern. The semantic dimensions are normative; the exact attribute syntax may evolve.

<button
  axag-intent="product.search"
  axag-entity="product"
  axag-action-type="read"
  axag-required-parameters='["query"]'
  axag-optional-parameters='["category", "price_min", "price_max", "sort_by"]'
  axag-scope="public"
  axag-risk-level="none"
  axag-idempotent="true"
>
  Search
</button>

Now the agent knows:

  • ✅ This is a product search operation
  • ✅ It operates on the product entity
  • ✅ It is a read (non-mutating) operation
  • ✅ It requires a query parameter
  • ✅ It optionally accepts category, price_min, price_max, sort_by
  • ✅ It is public — no sign-in needed
  • ✅ It has no risk
  • ✅ It is idempotent — safe to retry

The same contract fits in one attribute with the macro shorthand, and the parameters can come from the search form itself rather than being listed by hand — see Schema Harvesting:

<form axag="read:product.search!none?idempotent&scope=public">
  <label for="q">Search products</label>
  <input id="q" name="query" required>
  <button type="submit">Search</button>
</form>

What AXAG Is Not​

AXAG IsAXAG Is Not
A semantic contract standardA UI component library
An annotation format for existing interfacesA replacement for existing interfaces
A source of truth for agent interactionA visual rendering system
Compatible with any frontend frameworkTied to React, Vue, or Angular
A specification for what interactions meanA specification for how interactions look
Framework-agnostic metadataAn API definition language like OpenAPI

Relationship to Existing Standards​

StandardPurposeAXAG Relationship
ARIA / WCAGAccessibility for humans with disabilitiesComplementary — AXAG serves agents, not screen readers
OpenAPIAPI contract definitionAXAG annotates UI semantics; OpenAPI defines API endpoints
JSON-LD / Schema.orgStructured data for search enginesAXAG describes interaction semantics, not content metadata
MCPAgent tool protocolAXAG generates MCP-compatible tool definitions

Who Should Use AXAG?​

  • Frontend engineers — Annotate UI elements with semantic contracts
  • Platform teams — Generate manifests and tools on every build with @web-axag/compiler, and enforce safety with @web-axag/server
  • Agent runtime builders — Consume tools through WebMCP, or through the MCP bridge from outside the browser
  • Product architects — Design agent-ready interface semantics
  • Standards committees — Govern annotation vocabulary and conformance levels

Next Steps​