FlowRelay
Agent Access
Availability and refusals
A capability being listed in the manifest does not mean an agent may execute it. Availability depends on authority, plan usage, target state, safety rules, and product boundaries.
Availability model #
An agent action is available only when every required layer allows it. A route can exist and still be unavailable for the current grant, plan state, target object, or safety boundary.
| Layer | Question | Where to check | If blocked |
|---|---|---|---|
| Capability | Does FlowRelay expose this operation in the current edition? | /agent/v1/manifest capabilityDetails and OpenAPI. | Explain that the operation is unavailable in the current Shopify Flow edition. |
| Authority | Did the merchant grant this agent the required scopes? | /agent/v1/grant and requiredScopes in manifest or OpenAPI. | Ask an authorized human to change the grant or perform the action. |
| Usage | Is there remaining plan capacity for the read, preview, or execution? | /agent/v1/plan-usage and the Usage limits page. | Reduce work, wait for reset, or ask a human to approve more capacity. |
| Target state | Is the endpoint, event, receipt, retained material, or diagnostics share in a state that supports the action? | Setup state, endpoint detail, event detail, receipt facts, retention state, and diagnostics state. | Use the safe next action, such as sender resend, setup fix, or diagnostics. |
| Safety | Does the action require preview, confirmation, idempotency, redaction, or human judgment? | Action preview docs, operation metadata, and refusal response. | Preview first, request confirmation, redact, or escalate. |
| Product boundary | Is the request within FlowRelay for Shopify Flow? | Manifest platform identity, docs, and support or expansion guidance. | Explain the boundary or submit an expansion request only when it is tied to FlowRelay's event reliability mission. |
Common refusals #
Refusals should be treated as product guidance, not generic errors. The agent should report the reason, the evidence, and the next safe action.
| Refusal type | Meaning | Next safe action |
|---|---|---|
| Missing scope | The merchant did not authorize this agent for the operation. | Ask an authorized human to perform the action or issue a more appropriate grant. |
| Human-only | The action stays under human control even if the agent can read related context. | Prepare a handoff with links and context, but do not execute. |
| Usage limit | The plan's published meter does not allow more of this work in the current period. | Stop loops, reduce reads or previews, wait for reset, or ask a human to approve more capacity. |
| Retention expired | FlowRelay no longer has replayable event material. | Ask the sender to send a fresh event rather than reconstructing private data. |
| Unsafe replay | Replay could duplicate downstream Shopify Flow actions or the required confirmation is missing. | Use replay preview, inspect downstream risk, and get explicit confirmation from an authorized operator. |
| Unsupported platform or capability | The request is outside the current Shopify Flow edition. | Explain the boundary or submit an in-bounds expansion request when the merchant asked for FlowRelay-adjacent support. |
| Ambiguous mapping | The correct trigger variant or identifier path is not clear from the operator's request or sender payload. | Use the trigger mapping reference and ask the operator to confirm before creating or editing the endpoint. |
How to respond #
When an action is unavailable, the agent should name the blocking layer, cite the relevant FlowRelay fact or docs URL, avoid asking for private data, and offer the next safe action. The response should not imply that a broader Shopify, billing, or platform action is available through FlowRelay.
API CLI MCP parity #
Direct API calls, the FlowRelay CLI, and MCP Agent Operations access all use the same manifest, scopes, OpenAPI contract, usage limits, action previews, redaction rules, audit model, and refusal semantics. A different surface does not create different authority.
Operating rules
Use these controls to keep agent access scoped and reversible.
- 01Read the manifest to learn which capabilities exist in the current Shopify Flow edition.
- 02Read the grant to learn which scopes the merchant authorized for this agent.
- 03Read plan usage before broad reads, loops, repeated previews, or recovery work.
- 04Read the target endpoint, event, diagnostics share, or setup state before deciding whether the object is actionable.
- 05Use action previews and idempotency for side-effecting work.
- 06Return the refusal reason and next safe action when any availability layer blocks the request.