Let an agent investigate an event

# Let an agent investigate an event

Canonical: https://docs.flowrelay.app/use-cases/agent-assisted-operations/
Markdown: https://docs.flowrelay.app/use-cases/agent-assisted-operations.md

Use this path when a merchant wants an authorized agent to help answer what happened to an event without receiving broad store authority or private event data.

## Investigation job
An authorized agent can identify the endpoint, read the receipt, explain the current outcome, and suggest the next safe step from FlowRelay facts.


## Recovery job
If the grant allows, the agent can prepare a replay or diagnostics action for operator confirmation. Execution only follows preview, explicit human confirmation, idempotency, and audit.


## Hard boundaries
Agents cannot self-escalate, approve billing, mint or widen their own grants, access raw secrets or payloads, submit support outside scoped FlowRelay support paths, or edit Shopify Flow without separate Shopify authorization.


## Typical path
A typical path starts from the scenario, then moves into setup and verification.
1. Use a trusted private client
   Use a private agent client the merchant trusts, such as Codex, Claude Code, the FlowRelay CLI run by a coding or ops agent, direct Agent Operations API calls, or MCP Agent Operations access where enabled.
2. Confirm the grant
   Create or inspect the merchant-authorized grant and confirm the agent has only the scopes needed for investigation.
3. Configure scoped access
   Give the agent the Agent Operations base URL and scoped token through private secret, environment, CLI, or MCP configuration rather than public docs, tickets, or shared prompts.
4. Orient through public docs
   Have the agent start from /llms.txt, the relevant Markdown page, and /agent/v1/manifest before making authenticated calls.
5. Read before acting
   Let the agent read setup state, event history, receipt facts, replay availability, and diagnostics state through the same Agent Operations contract.
6. Preview state-changing work
   Require action previews for work that changes setup or recovery state, including replay preview, confirmation, idempotency, metering, and audit.
7. Escalate human-only actions
   Escalate to a human for billing approval, grant changes, Shopify Flow workflow edits, secrets, raw event data, support requests, or anything outside the grant.

## Related
- [Agent Access](https://docs.flowrelay.app/agent-access.md)
- [Agent orientation](https://docs.flowrelay.app/agent-access/agent-orientation.md)
- [API Reference](https://docs.flowrelay.app/reference/api.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.