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.

Serving /mcp to visiting agents? Use the Cloudflare Worker or the WordPress plugin, which vouch for each visitor without operator powers and pass the go-live checks. On Vercel, set enableMcpProxy: false (the examples below do): the middleware’s MCP proxy is built for calls signed with your own key, not for visiting agents.

For headless storefronts, the middleware also enables the catalog route-through: when an AI shopping agent hits your dynamic agent surfaces (/agent/query, /agent/products, and the ACP/UCP endpoints), the request is signed and forwarded to the Inception engine, which resolves your store by hostname and serves your real, normalized catalog — at your own domain. See Catalog Route-Through below.

What to Expect

After deployment, the middleware begins intercepting and analyzing traffic. When the first AI agent visits appear depends on how actively AI platforms crawl your domain. 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 Environment Variables

The installer provisions these for you (plus a Vercel Edge Config store) and opens a GitHub pull request with the middleware pre-configured, for your team to review before merging. Check that the pull request sets enableMcpProxy: false, and add it if not. To set the variables by hand, use the Vercel CLI or dashboard:

vercel env add INCEPTION_API_KEY      # per-tenant API key (also your signing key)
vercel env add INCEPTION_TENANT_ID    # tenant UUID — required for the catalog route-through + trace beacon
vercel env add EDGE_CONFIG            # provisioned Edge Config connection string (installer sets this)

Select all environments (Production, Preview, Development) or just Production when prompted.

For local development, add them to .env.local:

# .env.local
INCEPTION_API_KEY=ia_live_xxxxxxxxxxxxxxxxxxxx
INCEPTION_TENANT_ID=your_tenant_uuid_here
EDGE_CONFIG=https://edge-config.vercel.com/...

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 { withInception } from '@inception-agents/vercel';

export const middleware = withInception({
  apiKey: process.env.INCEPTION_API_KEY!,
  tenantId: process.env.INCEPTION_TENANT_ID!,
  enableRouteThrough: true, // serve your catalog at /agent/* + ACP/UCP (the installer sets this)
  enableMcpProxy: false,    // /mcp for visiting agents goes through the Worker or the plugin
});

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

Compose Inception Agents with your existing middleware using createInceptionMiddleware. It returns null for human traffic, letting your existing logic run unchanged:

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

const inception = createInceptionMiddleware({
  apiKey: process.env.INCEPTION_API_KEY!,
});

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

export async function middleware(request: NextRequest) {
  // Inception runs first. If it detects an AI agent, it returns the
  // optimized response and we short-circuit. Otherwise, fall through.
  const inceptionResponse = await inception(request);
  if (inceptionResponse) return inceptionResponse;

  return myMiddleware(request);
}

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

createInceptionMiddleware runs agent detection first. If the visitor is an AI agent, it serves optimized content and short-circuits. If the visitor is human, it returns null and your myMiddleware function runs normally.

Catalog Route-Through

For headless storefronts, the middleware can serve your real catalog — not just discovery files — from your dynamic agent surfaces. When enableRouteThrough is set (the installer enables it by default; it requires tenantId), requests to /agent/query, /agent/products, /agent/*, and the ACP/UCP endpoints (/.well-known/acp/*, /.well-known/ucp/*) are:

1. Signed — HMAC-SHA256 over the path, query, and body with your per-tenant key.
2. Forwarded to the Inception engine, which verifies the signature and binds the request to your tenant by host (no cross-tenant access).
3. Resolved to your normalized catalog and served back with a short shared-CDN cache.

On any engine error or timeout, the request degrades to your origin — it never blocks. Your catalog is normalized from whichever backend connector you run (Shopify, WooCommerce, BigCommerce, Adobe Commerce, or Salesforce Commerce Cloud); Vercel is the delivery layer.

export const middleware = withInception({
  apiKey: process.env.INCEPTION_API_KEY!,
  tenantId: process.env.INCEPTION_TENANT_ID!,
  enableRouteThrough: true,
  enableMcpProxy: false,
});

Before you turn the route-through on for a production storefront, book a call and we will check it against your catalog with you.

Tier-1 discovery surfaces (/llms.txt, /.well-known/agent.json) continue to short-circuit from Edge Config, and /mcp and human traffic are unaffected whether or not the route-through is enabled.

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.

Check the Catalog Route-Through

# Your real catalog, not a brochure -- requires enableRouteThrough + tenantId
curl -s -H "User-Agent: GPTBot/1.0" https://your-site.com/.well-known/acp/products | head -40
curl -s -H "User-Agent: GPTBot/1.0" "https://your-site.com/agent/query?q=trail+running+shoes" | head -40

Expected: your normalized catalog as JSON — products with variants, GTINs, price, and availability. If the route-through is disabled or the engine is unreachable, the request degrades to your origin instead.

Configuration Options

Pass these options to withInception (or createInceptionMiddleware):

withInception({
  apiKey: process.env.INCEPTION_API_KEY!,
  tenantId: process.env.INCEPTION_TENANT_ID!,
  enableRouteThrough: true,
  enableMcpProxy: 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:

1. Dashboard populates. Agent visits, detection events, and platform breakdowns appear under Analytics.
2. Content analysis runs. Your pages are crawled and analyzed for agent readability, structured data coverage, and content gaps.
3. Recommendations surface. The dashboard shows structured data improvements and content gaps for you to act on.

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, and how soon that starts varies.
• 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 composed Inception with your own middleware, remove the createInceptionMiddleware import and the inceptionResponse short-circuit block, leaving only your original middleware function.

Step 2: Remove the Package

npm uninstall @inception-agents/vercel

Step 3: Remove the Environment Variables

vercel env rm INCEPTION_API_KEY
vercel env rm INCEPTION_TENANT_ID
vercel env rm EDGE_CONFIG

Or remove them 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.