Move an existing event path with an agent

# Move an existing event path with an agent

Canonical: https://docs.flowrelay.app/agent-access/endpoint-swap-plan/
Markdown: https://docs.flowrelay.app/agent-access/endpoint-swap-plan.md

Use this guide when a sender already points to a receiver, webhook app, middleware, or serverless function and an authorized agent will help plan the replacement. For a new path, use Set up a new event path with an agent; for a merchant-led migration, use Swap over to FlowRelay.

## Choose what you need
- [Start here](#start-here): Confirm that the current path already exists, then check the grant and plan fit before changing traffic.
- [Plan the pilot](#plan-the-pilot): Inventory the current path, choose one reversible pilot, and prepare the agent brief.
- [Control the cutover](#control-the-cutover): Keep approval, rollback, and stop conditions attached to the production change.
- [Monitor and hand off](#monitor-and-hand-off): Set the follow-up cadence and leave the operator a concise plan.

## Start here
Confirm that the current path already exists, then check the grant and plan fit before changing traffic.

### Use this for
Start here when the current sender or receiver path already exists and an authorized agent will help inventory, test, or plan its replacement. The agent still needs operator approval before any sender, receiver, workflow, or production-traffic change.


### Grant needed
Use a store-scoped, time-bounded Agent Access grant for the exact swap-planning job. Observer is enough for inventory and read-only review. Operator is the default when the agent may create or edit endpoint setup or prepare endpoint tests for the pilot. Recovery Operator is required only when the pilot includes replay, diagnostics share creation, or secret rotation. Do not use Admin Assistant for normal swap-planning guides; reserve it for exceptional broader store operations.

- [Grants and scopes](https://docs.flowrelay.app/agent-access/grants-and-scopes/): Choose the lowest useful authority tier before starting the swap plan.

### Plan fit
Compare historical accepted-event volume plus expected migration traffic against the current plan and paid-plan grace. Also check diagnostics, replay, simple reads, rich reads, action previews, and executed actions for the work the agent plans to do. If volume may exceed the plan, recommend upgrade, custom capacity, or a smaller cutover window before production traffic moves.


## Plan the pilot
Inventory the current path, choose one reversible pilot, and prepare the agent brief.

### Copyable agent instructions
Paste this into an authorized agent session before any sender, receiver, or workflow is changed. Replace bracketed details, keep tokens in environment variables or the agent client's secret store, and keep private payloads or secrets out of the brief.

#### Agent swap-planning brief
Use for one existing sender path before a broader migration.

```text
You are helping plan a safe FlowRelay endpoint swap for [store/domain].

Goal: inventory candidate sender/receiver paths from available evidence, choose one low-risk pilot path, prove one FlowRelay handoff when authorized, check plan fit if FlowRelay is already installed, and prepare a broader cutover plan. Do not assume FlowRelay already has endpoints, receipts, setup state, or plan data. Work only inside the store-scoped, time-bounded FlowRelay Agent Access grant for this task when a grant exists. Use Observer for read-only FlowRelay review, Operator when endpoint setup changes or endpoint tests are authorized, and Recovery Operator only if replay, diagnostics share creation, or secret rotation is explicitly in scope. Do not ask for endpoint secrets, authentication headers, HMAC values, Shopify tokens, session data, raw event bodies, customer records, database URLs, store passwords, copied private logs, or screenshots containing private values.

Token handling:
- Receive the scoped Agent Access token only through private secret, environment variable, CLI profile, or MCP host secret configuration.
- Never paste the token into prompts, docs, tickets, screenshots, logs, repo files, or shared notes.

Before changing anything:
1. Read https://docs.flowrelay.app/llms.txt and https://docs.flowrelay.app/agent-access/endpoint-swap-plan/.
2. If FlowRelay is already installed and an Agent Access grant exists, read the Agent Operations manifest at https://api.flowrelay.app/agent/v1/manifest and confirm the grant/store identity with whoami or GET /agent/v1/grant.
3. If FlowRelay is already installed, read setup-state and plan-usage before broad reads, polling, or recommending rollout capacity.
4. If FlowRelay is not installed or no grant exists, mark FlowRelay data as unavailable and inventory from safe merchant/admin evidence only.

Inventory each candidate path:
- sender/source system, receiver/middleware, owner, current platform/source type
- workflow purpose and Shopify Flow trigger variant fit
- authentication method and retry behavior
- historical event volume, criticality, recent failures, and rollback path
- evidence source, confidence level, access gap, and next evidence step
- whether the path maps to FlowRelay for Shopify Flow today or should become a future-edition request

Pilot choice:
- Pick one safest, least-used, rollback-friendly path with a clear owner and a test event with synthetic data.
- Stop for operator approval before changing sender URL/auth, Shopify Flow workflows, billing/capacity, grants, replay, diagnostics sharing, or production traffic.
- Prove FlowRelay accepted and handed off one event; downstream Shopify Flow branch/action success must be confirmed separately by the operator.
- If FlowRelay returns 429, obey Retry-After, retryAfterSeconds, resetAt, rateLimitClass, scope, and recommendedAction.

Final output:
Give the operator an inventory table with evidence/confidence/gaps, selected pilot and rationale, test result if a FlowRelay handoff was authorized, plan fit if available, broader endpoint order, rollback path, stop conditions, monitoring cadence, unresolved approvals, and any future-edition request.
```


### Agent workflow
Agents should orient through docs before using authenticated tools.
1. Inventory current paths
   Inventory candidate event paths from available evidence before assuming FlowRelay already has endpoints or receipts: senders, receivers, workflow purpose, current platform or source type, auth category, owner, historical volume, criticality, rollback path, evidence source, confidence, and access gaps.
2. Classify current-product fit
   Classify the current path as supported now, Shopify Flow-only setup, or future-edition demand. Unsupported platform requests can become expansion requests only when tied to FlowRelay event reliability.
3. Choose one reversible pilot
   Choose one pilot endpoint that is low-risk, least-used, rollback-friendly, and representative enough to prove the handoff.
4. Check plan fit
   Check plan-usage and compare historical event volume, replay/diagnostics expectations, and agent-operation needs to the operator's current plan before recommending broader rollout.
5. Get operator approval
   Stop for operator approval before changing the sender URL/auth or moving any production traffic.
6. Prove one synthetic handoff
   Run one test event with synthetic data on Free/Test or the current plan, then confirm FlowRelay accepted it and handed it to Shopify Flow.
7. Check downstream results separately
   Ask the operator to verify the downstream Shopify Flow branch and action separately before moving production traffic. Delivered means FlowRelay handed the trigger to Shopify Flow. It does not mean downstream Shopify Flow branches, app calls, fulfillment changes, emails, or later systems completed.
8. Plan the wider cutover
   If the pilot works, produce a cutover plan for the remaining endpoints with sequence, owners, rollback, stop conditions, monitoring cadence, and capacity needs.

### Endpoint inventory
Build the inventory from evidence, not assumption. Do not assume which paths are FlowRelay endpoints or what receipts exist - read them first. Then classify each path: supported now, Shopify Flow setup only, or future-edition demand (review record only, not a live target).

Include the current sender, receiver or middleware, workflow purpose, event type if known, owner, auth category, historical event volume, criticality, last failure pattern, rollback owner, evidence source, confidence, access gaps, and whether the path maps to the current Shopify Flow edition. This inventory should not include secrets, auth header values, raw payloads, customer records, or private logs.


### Pilot selection
Pick one endpoint for testing before a broader migration. Prefer the safest, least-used, reversible path with a clear owner, a test event with synthetic data, known Shopify Flow trigger, and observable downstream test result. Do not bulk-swap first.


## Control the cutover
Keep approval, rollback, and stop conditions attached to the production change.

### Operating rules
- The production approval must name the sender URL/auth change, rollback owner, traffic window, and stop condition before any traffic moves.
- Revoke the grant when the work is finished or when the partner no longer needs access.
- Review audit entries for sensitive reads, action previews, confirmations, replays, and diagnostics shares.

### Cutover and rollback
The cutover plan should name each event path, owner, scheduled order, sender-side change, FlowRelay endpoint, expected receipt proof, rollback trigger, old receiver restoration path, stop condition, and who approves continuing to the next path. Delivered means FlowRelay handed the trigger to Shopify Flow. It does not mean downstream Shopify Flow branches, app calls, fulfillment changes, emails, or later systems completed. Confirm downstream completion separately before widening cutover.


## Monitor and hand off
Set the follow-up cadence and leave the operator a concise plan.

### Monitoring cadence
Recommend cadence from historical usage and importance: close checks during the pilot and immediately after cutover, lighter periodic checks for low-volume paths, and more frequent checks for critical or high-volume paths. Agents should use compact reads first, plan-usage before broad polling, and Retry-After/resetAt guidance when a 429 rate-limit response appears.


### Operator summary
End with a simple operator-readable plan: inventory table, selected pilot and why, test result, plan fit, broader endpoint order, rollback and stop conditions, monitoring cadence, unresolved approvals, and any future-edition expansion request.


## Related
- [New setup with an agent](https://docs.flowrelay.app/agent-access/setup-with-an-agent.md)
- [Swap over to FlowRelay](https://docs.flowrelay.app/use-cases/swapover-to-flowrelay.md)
- [Read receipts](https://docs.flowrelay.app/operate/receipts.md)
- [Usage limits](https://docs.flowrelay.app/operate/usage-limits.md)
- [Support, expansion, and feature requests](https://docs.flowrelay.app/agent-access/support-and-expansion-requests.md)

## Safety Boundary
Do not share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs in public examples.