Skip to content
AX Framework
Principle 03

Predictable Actions

The same action with the same input in the same state should produce the same effect, and that effect should be documented before the action is taken.

AX proposalActionability

Why it matters

Agents chain actions together. If one step behaves differently depending on hidden UI state, the whole chain becomes unreliable.

Predictability is also what makes retries safe. An agent that cannot predict the effect of repeating an action has to choose between risking a duplicate and giving up.

Examples

Good exampleIllustrative

Creating an order accepts an idempotency key; repeating the request with the same key returns the original order instead of creating a second one.

http
POST /orders
Idempotency-Key: 7c1e2b9a-agent-task-31
Content-Type: application/json

{ "cartId": "cart_8f2", "shippingOptionId": "std_eu" }
Bad exampleIllustrative

Clicking "Apply" on a coupon twice applies a second discount if the page was not refreshed in between.

Implementation guidance

  1. 1Document preconditions and side effects for every state-changing action.
  2. 2Support idempotency keys on any action that creates, charges, sends, or books.
  3. 3Avoid behavior that depends on client-side state the agent cannot see.
  4. 4Version action contracts and keep old versions stable until they are retired.

Evaluation criteria

  • Repeating a state-changing request with the same key has no additional effect.
  • Action documentation lists preconditions and side effects.
  • The effect of an action does not depend on undocumented UI state.