Skip to content
AX Framework

Getting Started

Quick Start

Make an existing web product measurably more agent-ready in an afternoon.

This guide takes an existing web product from Level 0 or 1 to a basic Level 2 on the maturity model for one task. It assumes a Next.js App Router project, but each step translates to any stack.

1. Write down the task

Describe the task as a person would ask an agent to do it, then list the steps the agent needs:

md
Task: "Reorder the coffee beans I bought last month."

1. Find the person's previous orders.
2. Identify the coffee beans line item.
3. Check it is still available, and at what price.
4. Add it to the cart.
5. Place the order (needs the person's approval above 40 EUR).
6. Confirm the order and expected delivery.

Each step will become a capability, a resource, or an approval point.

2. Make the content legible

Before adding anything new, make sure the facts an agent needs are machine-readable. For a product page, embed schema.org JSON-LD generated from the same data as the visible page:

tsx
// app/products/[slug]/page.tsx
export default async function ProductPage({ params }: PageProps<"/products/[slug]">) {
  const { slug } = await params;
  const product = await getProduct(slug);

  const jsonLd = {
    "@context": "https://schema.org",
    "@type": "Product",
    sku: product.sku,
    name: product.name,
    offers: {
      "@type": "Offer",
      price: product.price.amount.toFixed(2),
      priceCurrency: product.price.currency,
      availability: product.inStock ? "https://schema.org/InStock" : "https://schema.org/OutOfStock",
    },
  };

  return (
    <>
      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }} />
      <ProductView product={product} />
    </>
  );
}

Check your HTML too: labelled form controls, real buttons, and headings that describe their sections help agents and assistive technology alike.

3. Define the actions

Turn the steps that change something into typed action contracts. Keep the definitions in one place so your UI and your agent interfaces share them:

ts
// lib/actions/reorder.ts
import { z } from "zod";

export const addToCart = {
  name: "add_to_cart",
  description: "Add a product variant to the active cart.",
  risk: "low",
  idempotent: true,
  input: z.object({
    sku: z.string(),
    quantity: z.number().int().min(1).max(10),
  }),
} as const;

export const placeOrder = {
  name: "place_order",
  description: "Place an order for the current cart using a saved payment method.",
  risk: "high",
  requiresApproval: true,
  input: z.object({ cartId: z.string(), approvalId: z.string().optional() }),
} as const;

See Action Contracts for the full shape, including preconditions and results.

4. Publish a capability manifest

Serve a manifest that lists the actions and how to call them. In Next.js, a route handler works well:

ts
// app/ax.json/route.ts
import { addToCart, placeOrder, listOrders } from "@/lib/actions";
import { toManifestEntry } from "@/lib/ax";

export function GET() {
  return Response.json({
    ax: "0.1",
    name: "Example Coffee Co.",
    description: "Specialty coffee roaster shipping within the EU.",
    version: "2026-10-01",
    capabilities: [listOrders, addToCart, placeOrder].map(toManifestEntry),
  });
}

Then point to it from every page:

tsx
// app/layout.tsx
export const metadata: Metadata = {
  alternates: { types: { "application/json": "/ax.json" } },
};

5. Return structured results and errors

Every action should return an explicit status, and every failure a stable code:

json
{
  "error": {
    "code": "variant_unavailable",
    "message": "Ethiopia Guji 250g is out of stock.",
    "retryable": false,
    "suggestions": [{ "action": "notify_when_available", "input": { "sku": "ETH-GUJI-250" } }]
  }
}

See Error Handling.

6. Test it with an agent

Give an agent the task from step 1 and watch what it does. Record whether it succeeded, how many steps it took, how many times it guessed, and whether it could verify the outcome. The Testing Methodology page explains what to measure.

What you have now

  • Legible content with structured data.
  • One task available as explicit actions.
  • A manifest agents can discover.
  • Structured, recoverable errors.

That is a meaningful step. Next, add permissions and approvals so agents can act within limits a person sets.

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