Skip to content
AX Framework

Architecture

Actions and Workflows

Modelling single actions and multi-step tasks agents can execute reliably.

Actions are how agents change things. Workflows are how they change several things in order. This page describes how to model both so agents can execute them predictably.

Anatomy of an action

Every action, however small, answers the same questions:

QuestionField
What is it called?name
What does it do?description
What does it need?input schema
What must be true first?preconditions
What will it change?sideEffects
How risky is it?risk, requiresApproval
Is it safe to repeat?idempotent
What does it return?output schema

The Action Contracts page shows how to express this in TypeScript.

Result statuses

Use a small, fixed set of statuses so agents can branch reliably:

StatusMeaningAgent's next move
completedDone. Receipt attached.Verify, continue
acceptedQueued. Status URL attached.Poll or subscribe
approval_requiredWaiting for the principal.Relay, then resume
needs_clarificationInput was ambiguous. Options attached.Choose or ask
partially_completedSome items succeeded. Per-item results attached.Handle the rest
failedNot done. Error attached.Recover

Idempotency

Any action that creates, charges, sends, or books must be safe to retry. Accept an idempotency key and store the result against it:

ts
export async function withIdempotency<T>(key: string | null, scope: string, run: () => Promise<T>) {
  if (!key) return run();
  const existing = await idempotency.get(scope, key);
  if (existing) return { ...existing, replayed: true } as T;
  const result = await run();
  await idempotency.put(scope, key, result, { ttlHours: 24 });
  return result;
}

Scope keys to the grant, so one agent cannot replay another's request.

Workflows

When a task spans multiple steps, model it as a workflow resource. The workflow tells the agent where it is and what comes next.

json
{
  "id": "wf_19",
  "type": "checkout",
  "status": "in_progress",
  "steps": [
    { "name": "shipping", "status": "completed" },
    { "name": "payment", "status": "awaiting_input", "requires": ["paymentMethodId"] },
    { "name": "review", "status": "pending" }
  ],
  "next": { "action": "submit_payment" },
  "expiresAt": "2026-10-06T16:00:00Z"
}

Designing steps

  • One decision per step. Shipping method and payment method are separate steps because they are separate decisions.
  • Name steps after decisions, not screens. shipping, not page_2.
  • Expose holds and expiry. If a step reserves inventory or a fare, say until when.
  • Allow going back. Agents, like people, change plans. Support revise_step where it makes sense.

Compensation

When a workflow fails after some steps have side effects, undo them in reverse order and report what was undone. See the Rollback pattern.

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