Agent mission playbooks

# Agent mission playbooks

Canonical: https://docs.flowrelay.app/agent-access/agent-mission-playbooks/
Markdown: https://docs.flowrelay.app/agent-access/agent-mission-playbooks.md

Use these playbooks when an operator asks an authorized agent to help with FlowRelay setup, investigation, recovery, diagnostics, support, or expansion requests.

## Agent workflow
Agents should orient through docs before using authenticated tools.
1. Start with the operator's mission and identify the smallest FlowRelay job that can answer it.
2. Read /llms.txt, the task-specific Markdown page, /agent/v1/manifest, and the current grant before authenticated work.
3. Read setup state, plan usage, and the relevant endpoint or event facts before proposing an action.
4. Compare the mission against the manifest capability, required scopes, object state, usage state, and safety boundary.
5. Prepare only the lowest-risk action that fits the mission, such as a read, preview, sender handoff, support request, or expansion request.
6. Escalate when the mission asks for billing approval, grant changes, Shopify Flow edits, raw private data, unsupported platforms, or judgment outside the merchant-authorized grant.

## Mission routing
Agents should translate the operator's request into a FlowRelay mission before choosing routes or tools. The same playbook applies whether the agent uses direct API calls, the CLI, or MCP Agent Operations access.


- Operator mission: Set up the first endpoint; Gather first: Manifest, grant, setup state, trigger mapping reference, and plan usage.; Allowed next step: Create or inspect an endpoint when endpoint write authority is present, then guide the merchant through Shopify Flow trigger setup.; Escalate when: The agent is asked to edit Shopify Flow directly, approve billing, expose secrets, or choose an unclear trigger variant without operator confirmation.
- Operator mission: Investigate a failed event; Gather first: Event history, event detail, receipt facts, support code, endpoint snapshot, and retention state.; Allowed next step: Explain what FlowRelay can prove, identify the likely boundary, and suggest resend, setup fix, replay preview, or diagnostics.; Escalate when: The receipt cannot prove downstream Shopify Flow behavior or the operator asks for raw event bodies or private logs.
- Operator mission: Recover an event; Gather first: Event detail, replay availability, endpoint state, Shopify Flow readiness, plan usage, grant scopes, and replay guidance.; Allowed next step: Preview replay when retained event material and authority are available; execute only with required confirmation.; Escalate when: Retention expired, replay may duplicate customer-visible actions, the grant lacks replay authority, or the merchant needs Shopify Flow workflow changes.
- Operator mission: Share diagnostics; Gather first: Receipt or endpoint target, support code, diagnostics state, grant scopes, and diagnostics guidance.; Allowed next step: Preview and create a redacted diagnostics share when authorized.; Escalate when: The request asks to include raw payloads, full headers, secrets, tokens, customer data, or copied private incidents.
- Operator mission: Request support; Gather first: Support consent, diagnostics share, endpoint ID, event ID, support code, urgency, and redacted summary.; Allowed next step: Preview and submit a structured support request when the grant and operator consent allow it.; Escalate when: Consent is unclear, contact ownership is unclear, or the request would expose private material.
- Operator mission: Request expansion; Gather first: Merchant task, requested platform or capability, FlowRelay fit, business impact, and current edition boundary.; Allowed next step: Submit a non-binding expansion request when it is tied to FlowRelay event intake, reliability, handoff recovery, diagnostics, or approved agent operation.; Escalate when: The request is a generic product wishlist item or asks the agent to treat an unsupported edition as live.

## Context order
Use a fixed context order so the agent does not jump from a mission directly to side effects.


- Step: 1; Context: Docs and manifest; Purpose: Confirm live edition, public guidance, route names, capability metadata, and safety boundaries.
- Step: 2; Context: Grant and scopes; Purpose: Confirm the merchant-authorized authority for this agent and task.
- Step: 3; Context: Plan usage; Purpose: Avoid broad reads, repeated previews, or recovery work that would hit published limits.
- Step: 4; Context: Setup, endpoint, event, or diagnostics target; Purpose: Ground the answer in the specific store, endpoint, receipt, event, or share.
- Step: 5; Context: OpenAPI request shape; Purpose: Call the exact contract only after the product meaning and authority are clear.

## Acting on the mission
After context gathering, the agent should choose the lowest-risk action that satisfies the operator's mission. Reads come before previews; previews come before execution; sender or human handoffs come before actions outside FlowRelay's boundary.


## Output expectations
Agent responses should state what FlowRelay knows, what FlowRelay cannot prove, which docs or receipt facts support the answer, what action is available, what is blocked, and which human approval or external system is needed when the mission goes beyond FlowRelay.


## Related
- [Agent orientation](https://docs.flowrelay.app/agent-access/agent-orientation.md)
- [Availability and refusals](https://docs.flowrelay.app/agent-access/availability-and-refusals.md)
- [Trigger variants and mapping](https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping.md)
- [Replay an event](https://docs.flowrelay.app/recover/replay.md)
- [Share diagnostics](https://docs.flowrelay.app/recover/diagnostics.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.