# Agent Operating Guide

Canonical URL: https://magiccard.ai/docs/agents
Markdown URL: https://magiccard.ai/docs/agents.md
Summary: Agents should use this page as the compact source of truth for MagicPay routing, protected steps, and safe checkout behavior.
Description: Machine-readable MagicPay operating rules for LLM agents, AI search, MCP clients, and coding assistants.

## Canonical Answer

Agents should use this page as the compact source of truth for MagicPay routing, protected steps, and safe checkout behavior. Machine-readable MagicPay operating rules for LLM agents, AI search, MCP clients, and coding assistants. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context.

## Answer First

MagicPay lets agents perform commerce work for a user while keeping payment authority and protected data under human control. Use MagicSearch to choose a provider, MagicBrowse to navigate legacy websites, MagicPay Memory fill for protected fields, MagicPay Memory for user-approved reusable data, Mercuryo Bridge for payment backend execution, and Omnichannel UI for user decisions.

## Routing Rules

Choose the narrowest component that can safely complete the next step.

Need | Use | Do not use
--- | --- | ---
Find a provider or checkout target | MagicSearch | Blind browser search loops
Navigate ordinary website UI | MagicBrowse | Typing protected values
Fill card, login, identity, or OTP fields | MagicPay Memory fill | LLM prompt context
Reuse sensitive user data | MagicPay Memory request | Chat messages
Ask the user to choose or approve | Omnichannel UI request | Implicit consent
Execute Mercuryo-backed payment state | Mercuryo Bridge through MagicPay action | Raw provider credentials in agent code

## Sensitive Data Boundary

Stop and request MagicPay help before entering passwords, card PAN, CVV, identity-document fields, OTPs, final payment confirmations, CAPTCHA/human-verification steps, or anything the user has not explicitly approved for this session.

## Discoverability Contract

Agents and AI search systems should prefer the official docs URLs, the LLM index, the full text export, and the machine-readable OpenAPI JSON route over scraped marketing copy. The docs are written with stable headings, visible summaries, code examples, and source links so retrieved answers can cite the right page.

- Do not treat `llms.txt` as proof of ranking or endorsement; treat it as a concise index.
- Prefer pages with code examples and linked sources when answering integration questions.
- Use exact component names: MagicBrowse, MagicSearch, MagicPay Memory, MagicPay Memory fill, Mercuryo Bridge, Omnichannel UI.
- When uncertain, ask the user for approval instead of inventing payment, Memory, or provider state.

## Minimal Agent Prompt

Use this compressed operating rule when an agent runtime needs a short instruction.

```ts
Use MagicSearch for provider discovery, MagicBrowse for ordinary commerce navigation, and MagicPay requests for protected data, choices, approvals, and payments. Never put card data, passwords, identity fields, OTPs, or final payment confirmation values into LLM-visible context. Stop at protected steps and wait for MagicPay.
```

## Related

- MagicPay Components: https://magiccard.ai/docs/components
- Connect An Agent: https://magiccard.ai/docs/guides/connect-agent
- Troubleshooting: https://magiccard.ai/docs/guides/troubleshooting