BridgeToAgent
Get the kit — $49
All posts
Explainer5 min read

Add agents.json to WordPress in 5 minutes (with or without a plugin)

Three install paths for putting an agents.json file at the root of a WordPress site — File Manager plugin (no code, no FTP), direct SFTP upload (existing hosting access), and AI-readiness plugin (managed). Each path covered with the exact steps, time required, and the gotchas WordPress's permalink rewriter introduces for non-WordPress files.

BridgeToAgentEditorial team

Add agents.json to WordPress in 5 minutes (with or without a plugin)

WordPress doesn't ship an agents.json file by default. The file is a 2024-vintage spec (github.com/wild-card-ai/agents-json) that lives at your domain root and tells AI agents which actions on your site they can call — search, contact, browse products, subscribe. Most WordPress sites need to add the file manually, and most site owners don't want to touch FTP, themes, or wp-config.php to do it.

This post walks the three install paths for an agents.json at the root of a WordPress site, ranked by who each path is right for. Pick one, follow it, verify with a single curl, done.

Path A — WP File Manager plugin (no code, no FTP)

Right for: site owners who don't have FTP/SFTP credentials and don't want to ask their host for them. Time: 5 minutes including plugin install.

  1. WordPress admin → Plugins → Add New → search "File Manager" (the one by mndpsingh287 is fine, ~2M active installs). Install and activate.
  2. Sidebar now has a WP File Manager entry. Click it.
  3. Browse to the public root of your site — the directory that contains wp-config.php, index.php, and folders like wp-admin/ and wp-content/. The file manager opens there by default on most installs.
  4. Click New → File → name it exactly agents.json (lowercase, with the .json extension).
  5. Right-click the file → Edit. Paste your agents.json content. Save.
  6. Right-click the file → Permissions → set to 644 (read for everyone, write for owner). This matters — 600 makes it unreachable from the web.

Verify with curl -sI https://yourdomain.com/agents.json — you want HTTP/2 200 and content-type: application/json (or text/plain is also acceptable per the spec). If you get a 404 or HTML, see the gotchas section below.

The WordPress install guide has screenshots of the same flow for the full kit (all three files in one drag-and-drop).

Path B — Direct SFTP / cPanel upload

Right for: site owners who already have hosting-panel access and prefer not to add a plugin. Time: 2-3 minutes.

If you have cPanel:

  1. Log in to cPanel → File Manager.
  2. Navigate to public_html/ (the public root — same directory as wp-config.php).
  3. Upload → drag in your agents.json file.
  4. Right-click → Change Permissions → set to 644.

If you have raw SFTP/SSH:

scp agents.json user@yourdomain.com:/path/to/public_html/agents.json
ssh user@yourdomain.com 'chmod 644 /path/to/public_html/agents.json'

Replace /path/to/public_html with your actual document root — varies by host (Bluehost, SiteGround, DreamHost, Kinsta, WP Engine each use different paths; check your host's docs).

Verify the same way: curl -sI https://yourdomain.com/agents.json.

Path C — AI-readiness plugin (managed)

Right for: site owners who'd rather have a plugin manage the file (auto-update when site content changes, integrated with WordPress admin). Time: depends on plugin — usually 5-10 minutes for setup, then ongoing zero-effort.

A handful of plugins now offer agents.json generation as a feature alongside llms.txt and Schema markup. Names shift by quarter — search the WordPress plugin directory for "agents.json" or "AI readiness" before installing. Verify the plugin actively maintains the file and re-validates URLs (many free generators ship once and forget — the file rots as your site changes).

The tradeoff: a plugin generates a file from your site's pages automatically, but generated files are only as good as the plugin's extraction logic. If your site has custom post types, custom search endpoints, or non-WP forms, plugin-generated agents.json often misses them. Worth checking the output against your actual site before relying on it.

The two gotchas WordPress introduces

Permalink rewriting. WordPress's .htaccess (on Apache) or Nginx config sometimes routes unknown root paths through index.php. If your curl returns HTML instead of JSON, your rewriter is catching /agents.json and serving the homepage. Fix: add a rule above the WordPress rule in .htaccess:

RewriteRule ^agents\.json$ - [L]

This tells Apache to serve the file directly without passing through WordPress. On Nginx, add location = /agents.json { try_files $uri =404; } above the index.php location block.

Security plugin blocks. WordFence, Sucuri, iThemes Security, and similar can block direct access to root-level .json files as a default-deny rule. Symptom: curl returns 403 Forbidden. Fix: whitelist /agents.json in your security plugin's allowed-paths or file-access exceptions. Path varies per plugin — search the plugin's docs for "allowed file types" or "URL whitelist."

What to put in the file

A minimum-viable agents.json is about 30 lines covering 3-5 canonical actions on your site:

{
  "actions": [
    {
      "name": "search",
      "description": "Search posts and pages by keyword",
      "url": "https://yourdomain.com/?s=",
      "method": "GET",
      "parameters": {
        "type": "object",
        "properties": {
          "s": { "type": "string", "description": "Search query" }
        },
        "required": ["s"]
      }
    }
  ]
}

The full action shape and typing rules are in /docs/agents-json. The most-commonly-missed audit on hand-written files is agents-json-actions-typed — every action must have typed parameters. The per-audit fix reference covers the typing patterns in depth.

If you'd rather not hand-write the file, the BridgeToAgent kit generates a typed, link-validated agents.json from a real crawl of your site in two minutes for $49 — covers all three kit files plus a WordPress-specific install README in the ZIP.

Related

Keep reading

All posts →