Install your Agentic Kit on Magento / Adobe Commerce

Magento (now Adobe Commerce) gives you direct filesystem access — your codebase has a pub/ directory that serves at the root of your domain. This makes the install the simplest of any major commerce platform: drop the three files into pub/, no redirects, no plugins, no workarounds.

You'll be done in under 6 minutes.

This guide covers both Magento Open Source and Adobe Commerce (cloud and on-premise). The steps are identical.

Step 1 — Place the files in `pub/`

SSH into your Magento server (or upload via SFTP) and drop the three files from your kit ZIP into the pub/ directory at your Magento root:

cd /var/www/html/pub        # adjust path to your install
cp /path/to/agents.json .
cp /path/to/llms.txt .
cp /path/to/agent-instructions.md .

Magento serves pub/ at the document root — these files are now reachable at:

https://yourdomain.com/agents.json
https://yourdomain.com/llms.txt
https://yourdomain.com/agent-instructions.md

with the correct content-types inferred from the extension.

Step 2 — Confirm `.htaccess` doesn't block them

Magento ships with a pub/.htaccess file that controls which extensions are servable. Check it:

grep -E "FilesMatch|Order|Deny" pub/.htaccess

If you see directives that block .json, .txt, or .md, you'll need to add an explicit allow. The cleanest way:

<FilesMatch "^(agents\.json|llms\.txt|agent-instructions\.md)$">
    Order allow,deny
    Allow from all
    Header set Content-Type "text/plain" env=is_text
</FilesMatch>

Save and restart Apache / your webserver if needed.

💡 On Nginx? Most Magento + Nginx setups serve pub/ as the document root with no extension filtering. You shouldn't need to touch nginx.conf.

Step 3 — Add cache rules (optional, recommended)

In production you want these files cached aggressively. Edit your pub/.htaccess or nginx config to add a short cache header:

<FilesMatch "^(agents\.json|llms\.txt|agent-instructions\.md)$">
    Header set Cache-Control "public, max-age=3600, must-revalidate"
</FilesMatch>

One hour is conservative — adjust to your content cadence.

Step 4 — Verify

Open each URL in a new tab:

https://yourdomain.com/agents.json
https://yourdomain.com/llms.txt
https://yourdomain.com/agent-instructions.md

Each should serve the file content directly with the correct content-type.

You can also confirm with curl:

curl -I https://yourdomain.com/agents.json
# Look for: HTTP/1.1 200 OK
#           Content-Type: application/json

Step 5 (recommended) — Add the auto-discovery snippet

Tell AI bots where to find these files directly from your homepage <head>.

In your active theme, find the layout file that controls the homepage head section — usually:

app/design/frontend/<Vendor>/<theme>/Magento_Theme/layout/default.xml

or, for legacy themes:

app/design/frontend/<Vendor>/<theme>/Magento_Theme/templates/html/header.phtml

In default.xml, add a <head>-level block:

<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <head>
        <link rel="alternate" src="application/json" type="agentic" defer="true" src_type="url" content="/agents.json"/>
    </head>
</page>

For most installs the cleaner path is to edit the head template directly and paste:

<link rel="alternate" type="application/json" title="Agent Action Map" href="/agents.json">
<link rel="alternate" type="text/plain" title="LLM Context" href="/llms.txt">
<link rel="alternate" type="text/markdown" title="Agent Runbook" href="/agent-instructions.md">

Flush Magento's cache:

bin/magento cache:flush

Adobe Commerce Cloud specifics

On Adobe Commerce Cloud (managed hosting), you don't have direct filesystem access — instead you push commits to the managed Git repository and the cloud builds your environment.

Add the three files to your repo under pub/:

pub/agents.json
pub/llms.txt
pub/agent-instructions.md

Commit and push to your integration branch.
Merge to master or your production branch — Adobe Commerce Cloud redeploys automatically.
Verify the live URLs as in Step 4.

Troubleshooting

404 on the live URL. Check that pub/ is your document root (not the Magento root). The default Magento install serves from pub/ since version 2.4; older installs sometimes serve from the project root, which requires placing the files there instead.

.htaccess rules ignored. Magento Cloud and some shared hosts disable AllowOverride. If your .htaccess changes don't apply, the directives need to go into the main webserver config — talk to your host or check the Nginx server block.

Wrong content-type served. Some hosts add a global AddType directive that overrides the extension-based mime inference. Force the type explicitly with Header set Content-Type per the example in Step 2.