# Agent orientation

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

Agents learn FlowRelay from public docs first, then use authenticated API, CLI, or, when enabled, MCP only within the merchant-authorized grant.

## Agent workflow
Agents should orient through docs before using authenticated tools.
1. Confirm the agent client can keep bearer tokens private and call HTTP, CLI, or MCP tools without exposing the token in public prompts, files, or logs.
2. Fetch /llms.txt to discover canonical pages and Markdown equivalents.
3. Read the Markdown page for the task, such as setup, receipts, replay, diagnostics, or grants.
4. Read /agent/v1/manifest to confirm platform identity, capability metadata, docs URLs, safety boundaries, and route names.
5. Read /agent/v1/plan-usage before high-volume loops, broad investigation, or repeated action previews.
6. Use OpenAPI for exact request and response contracts before calling authenticated routes.
7. Use the CLI, or MCP Agent Operations access when enabled, only as wrappers over the same scoped Agent Operations contract.
8. Escalate to a human when the docs, grant, manifest, or refusal reason says the action is outside authority.

## Client requirements
Use an agent client only when it can keep the bearer token private and operate tools safely. Codex, Claude Code, the FlowRelay CLI, direct API clients, and enabled MCP Agent Operations access all use the same scoped contract. Other agent clients should meet the same private secret handling and tool-access requirements before receiving a grant token.


## Orientation order
Start with /llms.txt for the index, read the relevant Markdown page, check /agent/v1/manifest for edition and capability context, then use OpenAPI for exact request and response shapes. For endpoint create or edit work, read the trigger variants and event mapping reference before choosing triggerVariant or resource path fields.


## Endpoint setup work
When an agent creates or edits an endpoint, it should choose the trigger variant from product intent, send null for inactive resource path fields, and use the mapping reference to decide whether resourceIdPath or relatedResourceIdPath applies.

- [Trigger variants and event mapping](https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/): Human and agent reference for triggerVariant and mapping fields.

## Base URL and token
Use https://api.flowrelay.app as the Agent Operations base URL. Store the scoped Agent Access token in an environment variable, OS keychain, secret manager, or MCP host secret configuration. The token should not be pasted into public examples, docs, shared prompts, logs, support tickets, screenshots, or repo files.


## Which surface to use
The API is canonical. The CLI and MCP Agent Operations access behave as wrappers over the same Agent Operations contract when enabled and point agents back to these docs when they need product context.


## Check usage before loops
Use /agent/v1/plan-usage before broad investigation, polling, or repeated action previews. It exposes exact Agent Operations limits and enforcement state so agents can self-throttle instead of discovering a cap mid-task.


## Skills timing
Use the FlowRelay Operator Skill as the installable playbook over the canonical docs, OpenAPI, CLI, and MCP references. It points agents back to these docs for product meaning and safety boundaries.


## Escalation
Escalate when the grant, manifest, docs, API refusal, CLI response, or MCP tool result says the action is outside authority or requires human judgment.


## Related
- [Agent mission playbooks](https://docs.flowrelay.app/agent-access/agent-mission-playbooks.md)
- [Availability and refusals](https://docs.flowrelay.app/agent-access/availability-and-refusals.md)
- [API Reference](https://docs.flowrelay.app/reference/api.md)
- [OpenAPI](https://docs.flowrelay.app/reference/openapi.md)
- [CLI Reference](https://docs.flowrelay.app/reference/cli.md)
- [MCP Reference](https://docs.flowrelay.app/reference/mcp.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.