WordPress

This guide covers three ways to connect your WordPress site to Inception Agents: the WordPress plugin (recommended), a script tag, or a Cloudflare proxy. WooCommerce support is included for product-level optimization.

What to Expect

After activation, the plugin begins detecting agent traffic and serving optimized content immediately. First agent visits typically appear in your dashboard within 24-48 hours. Content optimization runs automatically.

Prerequisites

• WordPress 6.0 or later
• PHP 8.0 or later
• An Inception Agents API key (sign up, then find it in Settings > API Keys)
• Your Tenant ID (found in Settings > API Keys in the Inception Agents dashboard)

Option 1: WordPress Plugin (Recommended)

Step 1: Download the Plugin

Download the plugin .zip from your Inception Agents dashboard under Settings > Integrations > WordPress.

Step 2: Upload and Install

1. In your WordPress admin, go to Plugins > Add New > Upload Plugin
2. Select the downloaded .zip file
3. Click Install Now

Step 3: Activate

Click Activate after installation completes.

Step 4: Configure

1. Navigate to Settings > Inception Agents
2. Enter your API Key and Tenant ID
3. Click Save Changes

API Key:   ia_live_xxxxxxxxxxxxxxxxxxxx
Tenant ID: tn_xxxxxxxxxxxxxxxxxxxx

The plugin is now active. It will:

• Auto-generate /llms.txt and /.well-known/agent.json
• Detect AI agent traffic and log events to the dashboard
• Enrich structured data on pages, posts, and WooCommerce products
• Track AI agent referral traffic

Option 2: Script Tag

If you cannot install plugins (e.g., managed hosting restrictions), add the beacon script to your theme.

Step 1: Edit Your Theme Header

Go to Appearance > Theme File Editor and open header.php (or your theme’s head output file). Add the following before the closing </head> tag:

<script
  src="https://cdn.inceptionagents.com/beacon.js"
  data-api-key="YOUR_API_KEY"
  data-tenant-id="YOUR_TENANT_ID"
  defer
></script>

Step 2: Save

Click Update File.

Alternatively, use a plugin like Insert Headers and Footers to add the script tag without editing theme files directly.

Note: The script tag method provides agent detection and referral tracking but does not auto-generate llms.txt or provide edge-level content optimization. For full functionality, use the plugin or Cloudflare Proxy.

Option 3: Cloudflare Proxy

Route your WordPress site through a Cloudflare Worker for full edge-level interception.

npm install @inception-agents/cloudflare

Configure the Worker with your WordPress origin:

// src/index.ts
import { createInceptionHandler } from '@inception-agents/cloudflare';

export interface Env {
  INCEPTION_API_KEY: string;
  INCEPTION_CACHE: KVNamespace;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const handler = createInceptionHandler({
      apiKey: env.INCEPTION_API_KEY,
      originUrl: 'https://your-wordpress-site.com',
      kvCache: env.INCEPTION_CACHE,
      kvCacheTtl: 3600,
    });

    return handler(request);
  },
};

Deploy with Wrangler and point DNS to the Worker. See the full Cloudflare Worker guide for detailed setup.

Manual llms.txt Setup

If you are using the Script Tag method and need to serve llms.txt manually:

Step 1: Create the File

Create an llms.txt file with your site’s content description and upload it to your WordPress root directory (typically /var/www/html/ or your webroot).

Step 2: Add Rewrite Rules

Add these rules to your .htaccess file (before the WordPress block):

# Inception Agents - llms.txt
RewriteEngine On
RewriteRule ^llms\.txt$ /llms.txt [L]
RewriteRule ^\.well-known/agent\.json$ /agent.json [L]

If you use nginx instead of Apache:

location = /llms.txt {
    root /var/www/html;
    default_type text/plain;
}

location = /.well-known/agent.json {
    root /var/www/html;
    default_type application/json;
}

The plugin handles this automatically. Manual setup is only needed for the Script Tag method.

WooCommerce Support

If WooCommerce is active, the plugin automatically optimizes product data for AI agent consumption.

What Gets Optimized

Product JSON-LD Enrichment

The plugin adds competitive positioning and review summaries to WooCommerce product structured data:

{
  "@type": "Product",
  "name": "Your Product",
  "offers": {
    "@type": "Offer",
    "price": "29.99",
    "availability": "https://schema.org/InStock",
    "deliveryLeadTime": {
      "@type": "QuantitativeValue",
      "minValue": 2,
      "maxValue": 5,
      "unitCode": "DAY"
    }
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.6",
    "reviewCount": "142"
  }
}

This data is served to AI agents alongside your product pages. Human visitors see your normal WooCommerce pages without modification.

Verification

After setup, verify the integration:

Check llms.txt

curl -s https://your-wordpress-site.com/llms.txt

Expected: a markdown document describing your site and its content structure.

Check Agent Detection

curl -s -D - \
  -H "User-Agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.0" \
  https://your-wordpress-site.com/ | head -20

Expected: response headers include X-Inception-Agent: detected.

Check Agent Card

curl -s https://your-wordpress-site.com/.well-known/agent.json

Expected: a JSON object declaring your site’s agent capabilities.

Check Product Structured Data (WooCommerce)

curl -s \
  -H "User-Agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.0" \
  https://your-wordpress-site.com/product/your-product-slug/

Expected: enriched JSON-LD in the response body with Product, Offer, and AggregateRating data.

Caching Plugin Compatibility

WordPress caching plugins may cache the optimized agent responses and serve them to human visitors, or cache human responses and serve them to agents. The Inception Agents plugin includes cache-busting headers, but some caching plugins require explicit exclusion rules.

WP Super Cache

Add these rules to WP Super Cache > Advanced > Rejected URI Strings:

llms.txt
.well-known/agent.json
agent/

W3 Total Cache

In W3 Total Cache > Page Cache > Advanced, add to Never cache the following pages:

/llms.txt
/.well-known/agent.json
/agent/*

WP Rocket

In WP Rocket > Advanced Rules > Never Cache URLs, add:

/llms.txt
/.well-known/agent.json
/agent/(.*)

LiteSpeed Cache

In LiteSpeed Cache > Excludes > Do Not Cache URIs, add:

/llms.txt
/.well-known/agent.json
/agent/

General Rule

If your caching plugin is not listed above, exclude these URL patterns from page caching:

• /llms.txt
• /.well-known/agent.json
• /agent/*

The Inception Agents plugin sets a Vary: User-Agent header and Cache-Control: no-cache on agent-specific responses. If your caching plugin respects these headers, no additional configuration is needed.

Configuration Options

These settings are available under Settings > Inception Agents in the WordPress admin:

Troubleshooting

llms.txt Returns 404

• Plugin method: Confirm the plugin is activated and your API key is entered in Settings > Inception Agents. Click Save Changes to re-register rewrite rules, then go to Settings > Permalinks and click Save Changes (this flushes WordPress rewrite rules).
• Script Tag method: llms.txt is not auto-generated with this method. Set it up manually using the Manual llms.txt Setup instructions.
• Caching: Your caching plugin may be serving a cached 404. Purge the cache and retry.

No Agent Traffic in Dashboard

• Agent traffic depends on AI platforms crawling your site. This typically begins within 24-48 hours.
• Verify detection with the curl commands in the Verification section.
• Ensure your site is not password-protected, in maintenance mode, or behind a “coming soon” page.
• Check that your API key and Tenant ID are correct in Settings > Inception Agents.

WooCommerce Products Not Syncing

• Confirm WooCommerce is active and the WooCommerce Product Sync setting is enabled.
• Trigger a manual sync from Settings > Inception Agents > Sync Products.
• Check that products are published (not drafts) and visible in the WooCommerce catalog.

Plugin Conflicts

• Deactivate other SEO or structured data plugins temporarily to test. Plugins like Yoast SEO, Rank Math, and All in One SEO may output conflicting JSON-LD. The Inception Agents plugin is designed to complement — not replace — these plugins, but conflicts can occur.
• If you see duplicate JSON-LD on a page, check the page source for multiple <script type="application/ld+json"> blocks and identify which plugin is generating each.

Multisite Compatibility

• The plugin supports WordPress Multisite. Activate it network-wide or on individual sites. Each site requires its own API key and Tenant ID.

PHP Errors After Activation

• Confirm you are running PHP 8.0 or later: check Tools > Site Health > Info > Server > PHP Version.
• Check the WordPress debug log (wp-content/debug.log) for specific error messages.
• If the error persists, deactivate the plugin and contact support.

Uninstall

Plugin

1. Go to Plugins in your WordPress admin
2. Click Deactivate on Inception Agents
3. Click Delete

The plugin removes its rewrite rules, settings, and cached data on deletion. No residual code remains.

Script Tag

1. Go to Appearance > Theme File Editor (or your headers plugin)
2. Remove the <script> tag from header.php
3. Click Update File

Cloudflare Proxy

See the Cloudflare Worker uninstall instructions.