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:
| Question | Field |
|---|---|
| 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:
| Status | Meaning | Agent's next move |
|---|---|---|
completed | Done. Receipt attached. | Verify, continue |
accepted | Queued. Status URL attached. | Poll or subscribe |
approval_required | Waiting for the principal. | Relay, then resume |
needs_clarification | Input was ambiguous. Options attached. | Choose or ask |
partially_completed | Some items succeeded. Per-item results attached. | Handle the rest |
failed | Not 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:
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.
{
"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, notpage_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_stepwhere 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.
Related
Last updated 2026-10-06. AX Framework documentation describes proposals unless a section is marked as an established standard.