← Platform guides

Magento: A Personal Guide for Every Buyer Who Asks

2026-07-19 · Platform guides · magentooperational layerpersonalizationecommerce

Magento — Adobe Commerce — is the most API-complete commerce platform in mainstream use: REST endpoints and a GraphQL API cover catalog, cart, and checkout natively. Which makes the current situation absurd: when a shopper's AI agent visits a Magento store, it sees none of that. The machinery for full agent operation already exists on your server; nothing declares it, and nothing establishes the consent frame an aligned agent needs before acting. Publishing an operational layer on Magento is therefore mostly a declaration exercise — you're documenting real endpoints, not building new ones. Few platforms get this much operability for this little work.

What an agent sees on your Magento store today

Rendered storefront HTML (Luma or Hyvä or headless), a sitemap, and structured data if your theme emits it. Meanwhile /rest/V1/... and /graphql sit live on the same domain, capable of guest carts and full checkout flows — invisible to a visiting agent because nothing links or describes them. Descriptive surface, operable core, zero connection between them. The operational layer is that connection.

Step 1 — Write your llms.txt (it goes in pub/)

Magento serves the docroot from pub/. Place llms.txt there — alongside where robots.txt lives — so it resolves at https://yourstore.com/llms.txt. Content: store identity, catalog scope, shipping regions, policy summaries, pointers to your manifests and Service Control Map, consent declaration. On Adobe Commerce Cloud, static root files are managed through your repo and deploy process rather than direct upload — commit the file and check your deploy configuration includes it.

Step 2 — Publish JSON manifests (.json twins) for key pages

Static .json twins in pub/manifests/ for home, top categories, and policy pages. On Magento, keep the twins thin: their job is operational meaning and pointers; the live data belongs to the APIs you'll map next. A twin for a category page should say "browse this category via GraphQL products query or via this URL" — not embed the product list.

Step 3 — Add the consent gate and transparency declaration

In llms.txt and every manifest:

The published layer identifies the authorized store publisher and explains that supported operations remain subject to the user's confirmation. Payment stays in the store's normal human-confirmed checkout.

Open publication and explicit confirmation make the source and authority easier to assess, but do not eliminate prompt-injection, authorization, or platform-specific risks.

Step 4 — Build an API-first Service Control Map

This is where Magento shines. Your Service Control Map declares each operation's actuation — API endpoints first, interface controls as fallback — in the Adoption + Operation categories (evaluate · enroll · transact · configure · use · manage):

{
  "service": "Example Commerce (Magento / Adobe Commerce)",
  "layer": "operational",
  "consent_gate": "Explicit user consent required before any operation; payment is human-confirmed.",
  "operations": [
    {
      "id": "evaluate.browse_catalog",
      "type": "api_endpoint",
      "protocol": "graphql",
      "url": "https://example.com/graphql",
      "example_query": "{ products(search: \"jacket\", pageSize: 10) { items { name sku price_range { minimum_price { final_price { value currency } } } } } }"
    },
    {
      "id": "transact.create_guest_cart",
      "type": "api_endpoint",
      "method": "POST",
      "url": "https://example.com/rest/V1/guest-carts",
      "expected_result": "Returns cart ID for subsequent item operations"
    },
    {
      "id": "transact.add_to_cart",
      "type": "api_endpoint",
      "method": "POST",
      "url": "https://example.com/rest/V1/guest-carts/{cartId}/items",
      "inputs": ["sku", "qty", "quote_id"],
      "fallback": {
        "type": "interface_control",
        "url": "https://example.com/{product-url-key}.html",
        "notes": "Product page add-to-cart form"
      }
    },
    {
      "id": "transact.checkout",
      "type": "interface_control",
      "url": "https://example.com/checkout",
      "notes": "Hand off to the human user for payment confirmation"
    },
    {
      "id": "enroll.account",
      "type": "api_endpoint",
      "method": "POST",
      "url": "https://example.com/rest/V1/customers",
      "inputs": ["customer.email", "customer.firstname", "customer.lastname", "password"],
      "notes": "Verify anonymous customer creation is permitted on your instance"
    },
    {
      "id": "manage.support",
      "type": "interface_control",
      "url": "https://example.com/contact/",
      "inputs": ["name", "email", "telephone?", "comment"]
    }
  ]
}

Save as pub/agent.json. Verification notes: guest-cart REST endpoints and the GraphQL API are standard Magento Open Source / Adobe Commerce features, but instances differ — headless builds, API rate limiting, WAF rules, or security modules may restrict anonymous access. Test every mapped call against your production instance before publishing, and map only what actually responds.

Step 5 — Link it all for discovery

Add sitewide head and footer pointers — via your theme's default_head_blocks.xml (link tag) and footer template or CMS block, or a tiny module if you prefer config over theme edits:

<link rel="alternate" type="application/json" href="/agent.json" title="Operational layer">

Footer line: "This store publishes an operational layer for AI agents — /llms.txt". Cross-reference all manifests from llms.txt.

Honest limitations on Magento

• Complexity cuts both ways: WAFs, bot mitigation (often correctly) and Fastly/Varnish caching on Cloud can block or stale-serve API calls and manifests — configure exceptions deliberately.
• Checkout involves payment integrations that must remain human-confirmed; never map payment submission as agent-actuated.
• Multi-store/multi-site instances need per-domain layers with per-store URLs and currencies.
• Version and edition differences (Open Source vs Adobe Commerce, 2.4.x lines) change API behavior — re-verify the map after upgrades.
• If you run headless (PWA Studio or custom), your interface-control fallbacks are JavaScript-heavy; lean even harder on the API entries.

FAQ

Magento already has APIs — what does the layer add?

Declaration, discovery, and consent. The APIs are capability; the operational layer is what tells a user's agent they exist, how to use them, and that acting requires the user's yes. Capability without declaration is invisible.

Should I expose admin REST endpoints?

Never. Map only anonymous/guest-scope endpoints. Admin and integration tokens have no place in a public layer.

GraphQL or REST in the map?

Both if both are open on your instance. Declaring each operation across actuation types lets each agent choose the path it handles best — that is the point of the Service Control Map.

Want it generated for you?

The Free plan makes your store's most important page agent-ready — one hosted page, free, forever. The Basic plan (14-day trial, then $29/month) covers your full store, and Pro ($99/month) keeps a managed layer current as agent platforms evolve.

swa:1:aHR0cHM6Ly9zaGFyZXdpdGhteWFnZW50LmFpL3BsYXRmb3Jtcy9tYWdlbnRvLmpzb24

Keep reading