State diagram
Status reference
| Status | Meaning |
|---|---|
qualifying | Pre-flight is parsing the raw intent and validating the linked PINT’s scopes. |
searching | The agent is crawling for candidate products or services. |
validating | Candidates are being scored against the IPA’s constraints. |
pending_clarification | The agent needs more information from the user. clarification_questions is populated and the answers link is available. |
pending_approval | A valid candidate is ready; the decision link is available. |
approved | The user has approved. The IPA then transitions into monitoring. |
monitoring | Entered after approval regardless of autonomy level. When conditions are attached they are evaluated against live offers; when conditions are empty the monitor signals readiness immediately and the IPA advances to executing. |
executing | The purchase transaction is in flight. |
completed | Terminal. Purchase was executed successfully. |
failed | Terminal. An error occurred during qualification, search, validation, or execution. failure_reason is populated. |
cancelled | Terminal. The user cancelled before completion. |
expired | Terminal. monitor_until elapsed without conditions being met. |
How transitions map to the public API
The following response fields are populated as the IPA advances:| Field | Populated when |
|---|---|
preflight_workflow_id | On create — identifies the durable workflow validating the intent and PINT scopes. |
originating_agent_task | Via expand=originating_agent_task — the agent task that produced the IPA. |
executing_agent_task | Via expand=executing_agent_task. Spawned during pre-flight, so available before approval is granted. |
pint_uris | The PINTs linked to the originating and (once present) executing agent tasks. |
failure_reason | Populated when status reaches failed. |
completed_at | Populated when status reaches any terminal state. |
_links map on every response declares which actions the current state allows:
| Link | Present when |
|---|---|
self | Always. |
events | Always. |
answers | qualifying or pending_clarification. |
decision | pending_approval. |
cancel | Any non-terminal status. |
Event stream
Every state change is recorded as an event. Fetch them withGET /v0/user/ipa/{ipa_id}/events, or embed them via expand=events. Event types include ipa.status_change, ipa.clarification_sent, ipa.clarification_received, ipa.approval_requested, ipa.approval_received, ipa.workflow_started, ipa.workflow_completed, ipa.workflow_failed, ipa.cancelled, ipa.workflow_resumed, ipa.monitor_started, and ipa.price_checked.
Related
- IPA guide — request/response shape and drive-the-lifecycle recipes.
- IPAs — concept page and composition with PINTs.
- Enrol in perpetual search — an end-to-end quickstart that walks the diagram above.
- PINTs and scopes — the primitives an IPA rides on.