Skip to content
AX Framework
Discovery pattern

Action Discovery

Expose the actions available on a resource in its current state, alongside the resource itself.

Problem

A global capability list says what is possible in general, but not what is possible right now. An agent looking at a shipped order cannot tell whether it can still be cancelled without trying.

Context

Use this pattern when:

  • Resources move through states (draft, submitted, shipped) and the allowed actions change with each one.
  • Agents are making decisions turn by turn and benefit from knowing their options at each point.

Recommended solution

Include an actions collection in each resource response listing the actions currently permitted, with references to their contracts. Omit actions that are not available, or include them with an explicit reason.

This is the agent equivalent of disabling a button and showing a tooltip explaining why.

  1. 01Model resource states and the transitions each permits.
  2. 02Return currently available actions with each resource.
  3. 03Include unavailable actions with a reason when the reason is useful.
  4. 04Reference the same action names used in the capability manifest.

Interaction diagram

Interaction diagram for Action Discovery. 1. AI agent to Product · AX layer: GET /orders/ORD-1042. 2. Product · AX layer to AI agent: order + actions[]. 3. AI agent to AI agent: cancel unavailable: already shipped. 4. AI agent to Product · AX layer: POST start_return.AI agentProduct · AX layerGET /orders/ORD-10421order + actions[]2cancel unavailable: already shipp…POST start_return4
request response internal step

Example implementation

Illustrative example

Examples use a fictional store and illustrative field names. Adapt the shape to your stack; the qualities matter more than the exact format.

GET /orders/ORD-1042json
{
  "id": "ORD-1042",
  "status": "shipped",
  "actions": [
    { "name": "track_shipment", "available": true },
    { "name": "start_return", "available": true, "until": "2026-11-05" },
    {
      "name": "cancel_order",
      "available": false,
      "reason": "Orders cannot be cancelled after shipping. Use start_return instead."
    }
  ]
}

Accessibility and security

Accessibility

  • The same reasons used to explain unavailable actions to agents can be shown to people as helper text next to disabled controls.

Security

  • Computing available actions per request can leak information about other users' resources if not authorization-checked. Scope it to what the caller may see.

Applies the principles Explicit Capabilities and Transparent State.