Install your Agentic Kit on Drupal

Drupal gives you direct filesystem access (or, on managed hosts like Acquia and Pantheon, indirect access via Git deploy). Either way, the install is straightforward: place the three files in Drupal's public files directory or webroot, then set the right .htaccess exceptions so they're served raw rather than rewritten through Drupal's front controller.

You'll be done in under 5 minutes if you have shell or SFTP access.

This guide covers Drupal 9, 10, and 11. Drupal 7 instructions are similar but the paths differ slightly — see the note at the bottom.

Step 1 — Place the files in the webroot

SSH or SFTP into your Drupal server and drop the three files from your kit ZIP into the Drupal webroot (the directory that serves at /):

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

On standard Drupal installs the webroot is the directory containing index.php, core/, modules/, and sites/.

💡 Don't put them in sites/default/files/. That path serves at /sites/default/files/..., not at the root. Agents won't find them there.

Step 2 — Tell Drupal's `.htaccess` to serve them raw

By default Drupal's .htaccess rewrites all unknown requests to index.php (the Drupal front controller). You need to exclude the three new files so Apache serves them directly.

Open .htaccess at your Drupal root and find the section that begins:

# Pass all requests not referring directly to files in the filesystem to
# index.php.

Just above the existing RewriteRule for that section, add:

# Serve the BridgeToAgent kit files raw from the webroot.
RewriteRule ^agents\.json$ - [L]
RewriteRule ^llms\.txt$ - [L]
RewriteRule ^agent-instructions\.md$ - [L]

The [L] flag tells Apache to stop rewriting if the path matches. Save the file.

If you're on Nginx, the equivalent block in your server config:

location = /agents.json { try_files $uri =404; }
location = /llms.txt { try_files $uri =404; }
location = /agent-instructions.md { try_files $uri =404; }

Reload your webserver if needed.

Step 3 — 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 with the right content-type.

curl -I https://yourdomain.com/agents.json
# HTTP/2 200
# content-type: application/json

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

Add the three <link rel="alternate"> tags to your theme's html.html.twig template, which controls the <head> for every page.

Locate your active theme: usually themes/custom/<yourtheme>/ or, for a contributed theme, themes/contrib/<theme>/.
Open templates/html.html.twig. If it doesn't exist in your theme, copy it from core/themes/<base-theme>/templates/.
Find the <head> block and add immediately before </head>:

<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">

Clear the Drupal cache:

drush cr

or, in the UI: Configuration → Performance → Clear all caches.

Acquia, Pantheon, and other managed hosts

Managed Drupal hosts don't give you SSH-and-edit access to the webroot directly. The flow is:

Add the three files to your Git repository, at the webroot path used by the host (docroot/ on Acquia, web/ on Pantheon, plain root on Lando-style local dev).
Add the .htaccess exceptions (or Nginx config in the host's provisions/) per Step 2.
Commit and push to the host's deploy branch. The platform builds and the files are live.
Verify per Step 3.

Drupal 7 notes

Drupal 7 follows the same pattern but the rewrite block in .htaccess is structured slightly differently. The fix is the same: add three explicit RewriteRule ^...$ - [L] lines above the index.php rewrite. The auto-discovery <link> tags go into page.tpl.php instead of html.html.twig.

Troubleshooting

The URL returns the Drupal 404 page. Drupal's rewrite caught the request before Apache could serve the file. Double-check the .htaccess exceptions are above the existing index.php rewrite rule.

Permission denied. Files in the Drupal webroot need to be readable by the webserver user. Set: chmod 644 agents.json llms.txt agent-instructions.md.

Cache layer (Varnish, Cloudflare) serves stale content. Purge your edge cache for the three URLs after install. Varnish: varnishadm "ban req.url ~ /agents.json". Cloudflare: purge from the dashboard or via API.