Skip to content
AX Framework
Feedback pattern

Execution Status

Give long-running actions a status resource that agents can poll or subscribe to.

Problem

Some actions take seconds or hours: generating a report, processing a refund, provisioning infrastructure. Agents see a spinner, or nothing, and cannot tell whether to wait, retry, or give up.

Context

Use this pattern when:

  • The action completes asynchronously.
  • The agent may need to report progress to a person or continue other work meanwhile.

Recommended solution

Respond to long-running actions with 202 Accepted and a status resource URL. The status resource reports the state (queued, running, succeeded, failed), progress where measurable, an estimated completion time, and the final result or error.

  1. 01Return 202 with a Location header pointing to the status resource.
  2. 02Report state, progress, and estimated completion.
  3. 03Include the result or error when finished.
  4. 04Offer webhooks or server-sent events for agents that can receive them.

Interaction diagram

Interaction diagram for Execution Status. 1. AI agent to Product · AX layer: POST export_report. 2. Product · AX layer to AI agent: 202 → /jobs/job_55. 3. Product · AX layer to Backend service: process. 4. AI agent to Product · AX layer: GET /jobs/job_55. 5. Product · AX layer to AI agent: running 60%. 6. AI agent to Product · AX layer: GET /jobs/job_55. 7. Product · AX layer to AI agent: succeeded + result URL.AI agentProduct · AX layerBackend servicePOST export_report1202 → /jobs/job_552process3GET /jobs/job_554running 60%5GET /jobs/job_556succeeded + result URL7
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 /jobs/job_55json
{
  "id": "job_55",
  "action": "export_report",
  "state": "running",
  "progress": { "completed": 6, "total": 10, "unit": "sections" },
  "estimatedCompletion": "2026-10-06T14:05:30Z",
  "pollAfterSeconds": 5
}

Accessibility and security

Accessibility

  • Expose progress to people with the same data, using live regions for status updates.

Security

  • Status resources should be readable only by the grant that started the job.

Applies the principles Transparent State and Verifiable Outcomes.