Architecture
Context and State
Exposing structured context and readable state for agents.
Agents make decisions from the information you give them. Context is the information about the world (products, policies, availability). State is the information about the task in progress (the cart, the draft, the workflow step). Both need to be explicit.
Structured context
Start by listing the facts that drive decisions in your domain. For a store, that is price, availability, delivery, and return policy. For a travel product, fare rules, baggage, and change fees. Give each a typed field.
type Price = { amount: number; currency: string; includesTax: boolean };
type DeliveryWindow = { earliest: string; latest: string; timeZone: string };
type ProductVariant = {
sku: string;
attributes: Record<string, string>; // { size: "EU 42", color: "Black" }
price: Price;
compareAtPrice?: Price;
availability: { status: "in_stock" | "low_stock" | "out_of_stock" | "preorder"; quantity?: number };
delivery: DeliveryWindow;
};Rules for context
- Units always. Currency with every amount, time zone with every time, unit with every measurement.
- Enumerations over prose.
"status": "low_stock"instead of "Only a few left!". - Constraints as data. "Ships to EU only" becomes
"shipsTo": ["EU"]. - One vocabulary. If the UI says "Reserved", the data should not say "held".
Readable state
Anything an agent modifies should be readable by ID at any time. This lets agents verify their own work and recover after interruptions.
{
"id": "cart_8f2",
"version": 6,
"updatedAt": "2026-10-06T14:02:11Z",
"items": [
{ "sku": "TRAIL-RUNNER-42-BLK", "quantity": 1, "unitPrice": { "amount": 129.0, "currency": "EUR" } }
],
"totals": {
"subtotal": { "amount": 129.0, "currency": "EUR" },
"discount": { "amount": 12.9, "currency": "EUR" },
"total": { "amount": 116.1, "currency": "EUR" }
},
"actions": [
{ "name": "start_checkout", "available": true },
{ "name": "apply_coupon", "available": true }
]
}Versioning and concurrency
People and agents may edit the same resource. Include a version (or an ETag header) and require it on updates, so an agent working from a stale view gets a clear conflict instead of silently overwriting:
PATCH /carts/cart_8f2
If-Match: "6"
Content-Type: application/json
{ "items": [{ "sku": "TRAIL-RUNNER-42-BLK", "quantity": 2 }] }HTTP/1.1 412 Precondition Failed
Content-Type: application/problem+json
{ "code": "version_conflict", "currentVersion": 7, "retryable": true }Context budgets
Agents have finite working memory. A resource that returns 400 fields forces the agent to sift. Provide compact representations by default, and let agents request more:
GET /products/trail-runner?fields=sku,price,availability,deliveryRelated
Last updated 2026-10-06. AX Framework documentation describes proposals unless a section is marked as an established standard.