Skip to content
AX Framework

Architecture

Agent Experience Layer

Where AX sits in your stack and how it relates to your UI, API, and business logic.

The Agent Experience layer is the set of surfaces through which agents interact with your product. It is an architectural idea, not a separate service: in most products it is a small amount of new code over existing business logic.

Person

User interface

Pages, controls, visual feedback

Agent acting for a person

Agent Experience layer

  • Capability manifest
  • Resource descriptions
  • Action contracts
  • Grants & approvals
  • Receipts & status

Delivered through HTML + JSON-LD, an HTTP API, and/or an MCP server

Shared business logic, data, authorization, and audit
The AX layer is a sibling of the UI, not a wrapper around it. Both call the same logic.

A sibling, not a wrapper

A common first instinct is to build agent support by wrapping the UI: describe each screen, or let an agent drive a headless browser through it. That keeps agents dependent on the presentation layer, which changes often and encodes meaning visually.

The AX layer instead sits alongside the UI and calls the same business logic. When your checkout rules change, both the checkout page and the place_order action change with them, because both call the same function.

ts
// lib/orders.ts — business logic shared by UI and agents
export async function placeOrder(input: PlaceOrderInput, ctx: Context): Promise<PlaceOrderResult> {
  await assertCan(ctx.actor, "orders:create");
  const cart = await carts.get(input.cartId, ctx);
  // …pricing, inventory, payment
}

// app/checkout/actions.ts — UI (Server Action)
"use server";
export async function submitCheckout(formData: FormData) {
  return placeOrder(parseCheckoutForm(formData), await contextFromSession());
}

// app/api/ax/place_order/route.ts — agents (HTTP)
export async function POST(req: Request) {
  return Response.json(await placeOrder(await req.json(), await contextFromGrant(req)));
}

What the layer contains

ElementPurposePillar
Capability manifestDeclares what is possibleDiscoverability
Resource descriptionsTyped facts with units and constraintsComprehension
Action contractsTyped, validated, idempotent operationsActionability
Status and receiptsVerifiable outcomesFeedback & Observability
Grants and approvalsScoped authority, human checkpointsTrust & Control
Error vocabularyRecoverable failureRecovery & Resilience

Delivery channels

The same layer can be delivered through more than one channel:

  • HTML with structured data. For agents that browse. Semantic markup, JSON-LD, and link elements that point to machine-readable alternates.
  • HTTP API. For agents and integrations that call endpoints directly. Often described with OpenAPI.
  • MCP server. For agents running inside AI applications that support the Model Context Protocol. See MCP Integration.

What it is not

  • It is not a chatbot. The AX layer does not converse; it exposes capabilities to agents that do.
  • It is not a second product. It should not have features the UI lacks for the same principal, unless they are explicitly agent-only (for example, a resume endpoint).
  • It is not an access control system. Authorization lives in your business logic, where it already applies to every caller.

Last updated 2026-10-06. AX Framework documentation describes proposals unless a section is marked as an established standard.