Set up a new event path with an agent

# Set up a new event path with an agent

Canonical: https://docs.flowrelay.app/agent-access/setup-with-an-agent/
Markdown: https://docs.flowrelay.app/agent-access/setup-with-an-agent.md

Use this guide when no event path is being replaced and an authorized agent will help create a new FlowRelay endpoint. If a sender already points to a receiver, webhook app, middleware, or serverless function, use Move an existing event path with an agent instead.

## Choose what you need
- [Start here](#start-here): Confirm that this guide fits the job and choose the lowest useful grant.
- [Give the agent the job](#give-the-agent-the-job): Copy the setup brief, then follow the bounded setup procedure.
- [Handle boundaries](#handle-boundaries): Keep the operating rules visible and stop when FlowRelay returns a refusal.
- [Prove and hand off](#prove-and-hand-off): Confirm the first handoff, set a monitoring cadence, and leave an operator summary.

## Start here
Confirm that this guide fits the job and choose the lowest useful grant.

### Use this for
Start here for a new external event path. The agent may prepare or create the FlowRelay endpoint only within a scoped grant; Shopify Flow and sender changes remain with their separately authorized owners.


### Grant needed
Use a store-scoped, time-bounded Agent Access grant for the exact setup job. Operator is the default when the agent will create or edit endpoint setup, prepare endpoint tests, and prove one safe event. Use Observer when the agent only reviews setup, receipts, events, plan usage, or diagnostics state. Use Recovery Operator only when the task includes replay, diagnostics share creation, or secret rotation. Do not use Admin Assistant for normal setup guides; reserve it for exceptional broader store operations.

- [Grants and scopes](https://docs.flowrelay.app/agent-access/grants-and-scopes/): Compare Observer, Operator, Recovery Operator, and Admin Assistant.

## Give the agent the job
Copy the setup brief, then follow the bounded setup procedure.

### Copyable agent instructions
Paste this into an authorized agent session after the merchant has created a scoped Agent Access grant. Replace bracketed details, keep tokens in environment variables or the agent client's secret store, and do not include secrets, raw payloads, or customer records. Stop and get operator approval before: the Shopify Flow trigger, the endpoint, the sender URL/auth, any production traffic, replay, support submission, or requesting more capacity.

#### Agent setup brief
Use for one new FlowRelay endpoint and one safe proof event.

```text
You are helping set up FlowRelay for Shopify Flow for [store/domain].

Goal: create or prepare one new FlowRelay endpoint, prove one test event with synthetic data, and produce an operator-readable summary. Work only inside the store-scoped, time-bounded FlowRelay Agent Access grant for this task. Use Operator authority only when endpoint setup changes are authorized. Use Observer for read-only review. Use 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/setup-with-an-agent/.
2. Read the Agent Operations manifest at https://api.flowrelay.app/agent/v1/manifest.
3. Confirm the grant/store identity with whoami or GET /agent/v1/grant.
4. Read setup-state and plan-usage.

Inventory:
- sender/source system and owner
- event purpose and Shopify Flow trigger variant
- expected monthly event volume and criticality
- authentication mode the sender can support
- testing owner and rollback owner
- whether Shopify Flow trigger setup is separately authorized

Rules:
- Create or edit one endpoint only if the grant allows it and the operator approves the trigger choice.
- Stop for operator approval before sender URL/auth changes, Shopify Flow workflow changes, billing/capacity changes, grant changes, replay, diagnostics sharing, or 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.
- If FlowRelay returns 429, obey Retry-After, retryAfterSeconds, resetAt, rateLimitClass, scope, and recommendedAction.

Final output:
Give the operator a concise summary with the sender/workflow, endpoint and trigger choice, test result, plan fit, recommended monitoring cadence, risks, unresolved approvals, rollback owner, and next safe action.
```


### Agent workflow
Agents should orient through docs before using authenticated tools.
1. Confirm the edition and grant
   Confirm the current edition is FlowRelay for Shopify Flow and the operator has authorized this store, grant, and task.
2. Run orientation checks
   Run docs, whoami or grant, setup-state, and plan-usage before creating or changing anything.
3. Inventory one event path
   Identify the sender, event purpose, supported trigger variant, payload fields, authentication method, expected monthly volume, and criticality.
4. Prepare one authorized endpoint
   Create or inspect one endpoint only when the grant includes endpoint write authority and the operator confirms the trigger choice.
5. Hand off external changes
   Hand Shopify Flow trigger setup and sender URL/auth setup to the operator or separately authorized owner; FlowRelay does not edit Shopify Flow or the sender.
6. Prove one synthetic event
   Send one test event with synthetic data, then confirm FlowRelay accepted it and handed it to Shopify Flow.
7. Check downstream results separately
   Ask the operator to confirm any downstream Shopify Flow result separately. 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. Summarize and monitor
   Recommend monitoring cadence from traffic, criticality, and recent failures, then produce a short operator summary.

### Setup inventory
Before endpoint creation, the agent should collect only setup facts: sender owner, current platform or source type, event purpose, trigger variant, required JSON paths, authentication method, expected volume, criticality, testing owner, rollback owner, and whether Shopify Flow setup is separately authorized. Do not ask for endpoint secrets, auth headers, tokens, raw payloads, customer data, or copied private logs.


## Handle boundaries
Keep the operating rules visible and stop when FlowRelay returns a refusal.

### Approval checkpoints
- Agents operate only through scoped, revocable grants and explicit operator approval; they are governed operators, not privileged bypasses. They are bound by refusal reasons, action previews, idempotency, usage metering, redacted summaries, and audit. They must not ask for Shopify tokens, session data, database URLs, raw event bodies, full authentication headers, endpoint secrets, HMAC values, customer data, copied logs, browser storage, cookies, or broader Shopify authority through FlowRelay.
- Stop for operator approval before choosing an unclear trigger variant, creating an endpoint, changing sender URL/auth, enabling production traffic, replaying an event, submitting support, requesting more capacity, or treating another platform edition as live.
- 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.

### When FlowRelay refuses
A refusal is part of the product contract. The agent should preserve the refusal reason, docs URL, retry or usage guidance, required scope, and suggested next action instead of trying another surface. Missing scope, expired retention, no_workflow, rate limits, billing handoff, unsafe replay, and human-only grant changes each require the specific next safe action the response names.


## Prove and hand off
Confirm the first handoff, set a monitoring cadence, and leave an operator summary.

### Proof checklist
Record the receipt ID, endpoint, sender owner, test timestamp, and the operator's separate downstream check. Keep the FlowRelay handoff fact and the Shopify Flow result as two distinct lines in the handoff summary.


### Monitoring cadence
During setup or cutover, monitor more closely until the first delivered proof is clean. After that, low-risk or low-volume paths can use light periodic checks, while high-volume, revenue-impacting, or recently failing paths should be checked more frequently. Read plan-usage before broad reads or polling. Any 429 response means obey Retry-After, narrow the target set, and stop tight loops.


### Operator summary
End with a short summary the operator can scan: sender and workflow, endpoint and trigger choice, test result, plan fit, recommended monitoring cadence, risks, next approvals, and any external owner who still needs to act.


## Related
- [Existing-path swap with an agent](https://docs.flowrelay.app/agent-access/endpoint-swap-plan.md)
- [Agent orientation](https://docs.flowrelay.app/agent-access/agent-orientation.md)
- [Trigger variants and mapping](https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping.md)
- [Send your first test event](https://docs.flowrelay.app/getting-started/first-event.md)
- [Read receipts](https://docs.flowrelay.app/operate/receipts.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.