Set up with an agent

# Set up 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 an operator wants an authorized agent to help set up a new external-event lane without handing the agent broad store authority.

## Agent workflow
Agents should orient through docs before using authenticated tools.
1. Confirm the current edition is FlowRelay for Shopify Flow and the operator has authorized this store, grant, and task.
2. Run docs, whoami or grant, setup-state, and plan-usage before creating or changing anything.
3. Identify the sender, event purpose, supported trigger variant, payload fields, authentication method, expected monthly volume, and criticality.
4. Create or inspect one endpoint only when the grant includes endpoint write authority and the operator confirms the trigger choice.
5. 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. Send one synthetic test event, then confirm FlowRelay accepted it and handed it to Shopify Flow.
7. Ask the operator to confirm any downstream Shopify Flow result separately, because Delivered means handoff, not downstream completion.
8. Recommend monitoring cadence from traffic, criticality, and recent failures, then produce a short operator summary.

## Use this for
Use this setup guide when the merchant is creating a new external-event lane. For an existing endpoint, receiver, webhook app, serverless function, or agency-built path, use the endpoint swap plan instead.


## 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 recipes; 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.

## 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.

### 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 synthetic test event, 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, raw event bodies, customer records, copied private logs, or store passwords.

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.
- FlowRelay Delivered means handoff to Shopify Flow; 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 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.
```


## 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.


## Approval checkpoints
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.


## Proof checklist
A successful first setup needs one clean FlowRelay receipt. The agent should report Accepted, Delivered or the support code, endpoint readiness, Shopify Flow trigger readiness, plan fit, and whether downstream Shopify Flow behavior was confirmed separately by the operator.


## Monitoring cadence
During setup or cutover, monitor more closely until the first delivered proof is clean. After that, low-risk or low-volume lanes can use light periodic checks, while high-volume, revenue-impacting, or recently failing lanes should check more frequently and 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
- [Agent orientation](https://docs.flowrelay.app/agent-access/agent-orientation.md)
- [Usage limits](https://docs.flowrelay.app/operate/usage-limits.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)
- [CLI Reference](https://docs.flowrelay.app/reference/cli.md)

## Safety Boundary
Do not include raw event bodies, endpoint secrets, authentication headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.