Skip to main content

Mental Model: How AXAG Works

Before writing your first annotation, understand the mental model that makes AXAG work.

The Two Audiences​

Every interface element serves two audiences simultaneously:

  1. Human users — who perceive the element visually and interact manually
  2. AI agents — who need to discover, understand, and invoke the element programmatically

Traditional interfaces serve only the first audience. AXAG adds a semantic layer that serves the second.

The Five-Layer Architecture​

Layer 1: Human Interface​

The existing UI. No changes required to visual design, layout, or user interaction patterns.

Layer 2: AXAG Semantic Contract​

Annotations added to UI elements. These annotations declare intent, entity, action type, parameters, constraints, preconditions, risk level, and safety requirements.

Layer 3: Semantic Manifest​

A JSON document generated from annotations. It catalogs every operation available on a page, section, or application with full parameter schemas and safety metadata.

Layer 4: MCP Tool Registry​

Tool definitions generated from the manifest following the Model Context Protocol specification. Each operation becomes a callable tool with typed inputs and safety constraints.

Layer 5: Agent Runtime​

The agent reads the tool registry, plans which tools to invoke, validates parameters against constraints, and executes operations.

An agent running in the browser skips the fetch: @web-axag/webmcp registers each action with document.modelContext while its element is on screen, so the agent's tool list is layer 4, live. The manifest is how agents outside the page — crawlers, server-side agents, registries — see the same operations.

There is a sixth thing, and it isn't a layer: the server. Everything above declares what the rules are; only your API can refuse a call that breaks them.

The Key Insight​

📋 Normative — MUST

Agents MUST interact with systems through semantic operations declared in the AXAG contract — not through scraping, prompt interpretation, or visual inference.

This means:

  • The agent does not parse the DOM to find buttons
  • The agent does not read button text to guess intent
  • The agent does not inspect CSS classes to identify elements
  • The agent reads the Semantic Manifest to discover operations
  • The agent reads tool definitions to understand invocation contracts
  • The agent validates parameters against declared constraints before execution

From UI Element to Agent Action​

Here is the complete transformation path for a single UI element:

Step 1: The UI Element (Human-Facing)​

Before — plain HTML button
<button onclick="handleCheckout()">Proceed to Checkout</button>

Step 2: Add AXAG Annotations​

After — AXAG-annotated checkout button
<button
  axag-intent="checkout.begin"
  axag-entity="order"
  axag-action-type="write"
  axag-required-parameters='["cart_id","payment_method_id","shipping_address_id"]'
  axag-preconditions='["cart_validated","inventory_reserved"]'
  axag-postconditions='["checkout_session_created"]'
  axag-risk-level="high"
  axag-confirmation-required="true"
  axag-scope="user"
  onclick="handleCheckout()"
>
  Proceed to Checkout
</button>

Step 3: Generate Semantic Manifest Entry​

axag-manifest.json — checkout entry
{
  "intent": "checkout.begin",
  "entity": "order",
  "action_type": "write",
  "operation_id": "checkout_begin",
  "description": "Start checkout for a validated cart and create a checkout session.",
  "required_parameters": [
    { "name": "cart_id", "type": "string" },
    { "name": "payment_method_id", "type": "string" },
    { "name": "shipping_address_id", "type": "string" }
  ],
  "optional_parameters": [],
  "risk_level": "high",
  "confirmation_required": true,
  "scope": "user",
  "preconditions": ["cart_validated", "inventory_reserved"],
  "postconditions": ["checkout_session_created"]
}

Step 4: Generate MCP Tool Definition​

MCP tool definition — checkout_begin
{
  "name": "checkout_begin",
  "description": "Start checkout for a validated cart and create a checkout session.",
  "input_schema": {
    "type": "object",
    "properties": {
      "cart_id": { "type": "string" },
      "payment_method_id": { "type": "string" },
      "shipping_address_id": { "type": "string" }
    },
    "required": ["cart_id", "payment_method_id", "shipping_address_id"]
  },
  "metadata": {
    "action_type": "write",
    "risk_level": "high",
    "idempotent": false,
    "confirmation_required": true,
    "approval_required": false,
    "source_intent": "checkout.begin",
    "source_entity": "order"
  }
}

Step 5: Agent Invokes the Tool​

The agent runtime:

  1. Discovers checkout_begin — in the tool registry, or registered live in the page
  2. Validates that cart_id, payment_method_id, and shipping_address_id are provided
  3. Reasons about the cart_validated and inventory_reserved preconditions, and calls what satisfies them first
  4. Notes that this is a high-risk mutating operation requiring confirmation
  5. Asks the person to confirm, and carries the confirmation token into the call
  6. Executes the operation — which your server accepts only because the token, roles and tenant check out
  7. Checks the result against the checkout_session_created postcondition

Next Steps​