Vercel / Next.js

This guide walks through adding Inception Agents as Edge Middleware to your Vercel-deployed application. The middleware intercepts requests at the edge, detects AI agent traffic, and serves optimized content — all before your application code runs. Human visitors pass through unmodified with zero latency impact.

What to Expect

After deployment, the middleware begins intercepting and analyzing traffic immediately. The first AI agent visits typically appear in your dashboard within 24-48 hours, depending on how actively AI platforms crawl your domain. Content optimization runs automatically — no manual configuration of individual pages is required.

Prerequisites

• Node.js 18 or later
• Next.js 14 or later (App Router or Pages Router)
• A project deployed on Vercel
• An Inception Agents API key (sign up, then find it in Settings > API Keys)

SvelteKit and other frameworks that support Vercel Edge Middleware also work. The middleware API is the same.

Step 1: Install the Package

npm install @inception-agents/vercel

Step 2: Set Your API Key

Add your API key as an environment variable. Use the Vercel CLI or the Vercel dashboard.

Option A: Vercel CLI

vercel env add INCEPTION_API_KEY

Enter your API key when prompted. Select all environments (Production, Preview, Development) or just Production.

Option B: .env.local (local development)

# .env.local
INCEPTION_API_KEY=ia_live_xxxxxxxxxxxxxxxxxxxx

Never commit .env.local to version control. Add it to .gitignore.

Step 3: Create the Middleware

If You Do Not Have an Existing middleware.ts

Create middleware.ts in your project root (next to package.json):

// middleware.ts
import { createInceptionMiddleware } from '@inception-agents/vercel';

export default createInceptionMiddleware({
  apiKey: process.env.INCEPTION_API_KEY!,
});

export const config = {
  matcher: [
    /*
     * Match all paths except:
     * - _next/static (static files)
     * - _next/image (image optimization)
     * - favicon.ico
     * - public folder assets
     */
    '/((?!_next/static|_next/image|favicon\\.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp|ico)$).*)',
  ],
};

If You Already Have a middleware.ts

Wrap your existing middleware with the Inception Agents handler:

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { withInceptionAgents } from '@inception-agents/vercel';

function myMiddleware(request: NextRequest) {
  // Your existing middleware logic
  const response = NextResponse.next();
  response.headers.set('x-custom-header', 'my-value');
  return response;
}

export default withInceptionAgents(myMiddleware, {
  apiKey: process.env.INCEPTION_API_KEY!,
});

export const config = {
  matcher: [
    '/((?!_next/static|_next/image|favicon\\.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp|ico)$).*)',
  ],
};

The withInceptionAgents wrapper runs agent detection first. If the visitor is an AI agent, it serves optimized content and short-circuits. If the visitor is human, it calls your myMiddleware function and passes through normally.

Step 4: Deploy

vercel --prod

Or push to your connected Git repository. Vercel will deploy the middleware automatically.

Step 5: Verify

Run these three checks against your production URL:

Check Agent Detection

curl -s -o /dev/null -w "%{http_code}" \
  -H "User-Agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.0" \
  https://your-site.com/

Expected: 200. The response will include enriched content and the header X-Inception-Agent: detected.

Check Human Passthrough

curl -s -o /dev/null -w "%{http_code}" \
  -H "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/120.0.0.0 Safari/537.36" \
  https://your-site.com/

Expected: 200. The response is your normal page, unmodified. No X-Inception-Agent header present.

Check llms.txt

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

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

Configuration Options

Pass these options to createInceptionMiddleware or withInceptionAgents:

createInceptionMiddleware({
  apiKey: process.env.INCEPTION_API_KEY!,
  debug: false,
  excludePaths: ['/api/internal/', '/admin/'],
  detectionThreshold: 0.7,
  cacheMaxAge: 3600,
  enableLlmsTxt: true,
  enableJsonLd: true,
  enableAgentCard: true,
});

What Happens After Deployment

Once the middleware is live, the platform operates automatically:

1. Dashboard populates. Agent visits, detection events, and platform breakdowns appear in real-time under Analytics.
2. Content analysis runs. Your pages are crawled and analyzed for agent readability, structured data coverage, and content gaps.
3. Learning engine activates. After sufficient agent interactions (typically 1-2 weeks), the system begins adapting content variants per platform and intent.
4. Optimization tab unlocks. The dashboard surfaces actionable recommendations — structured data improvements, content gaps, and A/B test opportunities.

Troubleshooting

Middleware Not Running

• Confirm middleware.ts is in the project root (same directory as package.json), not inside src/ or app/.
• Check that the matcher pattern in export const config is not accidentally excluding your routes.
• Verify the middleware is deployed by checking Vercel’s Functions tab — you should see a middleware entry.
• Run vercel logs --follow to check for errors at the edge.

No Agent Traffic in Dashboard

• Agent traffic depends on AI platforms crawling your site. This typically begins within 24-48 hours.
• Verify detection is working with the curl commands in the Verify section.
• Check that your INCEPTION_API_KEY environment variable is set correctly in Vercel: Settings > Environment Variables.
• Enable debug: true in the middleware config and check Vercel function logs for detection decisions.

Latency Concerns

• The middleware adds less than 5ms to request processing for human visitors. Agent detection uses pattern matching and header analysis — no external API calls are made for Tier 0/1 detection.
• If you observe higher latency, confirm that excludePaths is set for high-traffic API routes that do not need agent detection (e.g., /api/internal/).
• The cacheMaxAge setting controls how long optimized agent content is cached at the edge. Higher values reduce origin calls.

ISR / Incremental Static Regeneration

• The middleware runs before ISR cache lookup. Agent-specific content is served from the Inception Agents edge cache, not from your ISR cache.
• Human visitors continue to use ISR normally. No configuration changes are needed for ISR compatibility.

App Router vs Pages Router

• The middleware file works identically for both App Router and Pages Router projects. Place middleware.ts in the project root regardless of which router you use.

Uninstall

Step 1: Remove the Middleware

Delete middleware.ts if Inception Agents was the only middleware. If you used withInceptionAgents as a wrapper, revert to your original middleware function.

Step 2: Remove the Package

npm uninstall @inception-agents/vercel

Step 3: Remove the Environment Variable

vercel env rm INCEPTION_API_KEY

Or remove it from the Vercel dashboard under Settings > Environment Variables.

Your site reverts to its default behavior on the next deployment. No residual code runs at the edge.