@inception-agents/vercel

v1.0.1

Published

13 days ago

Vercel Edge Middleware integration for Inception Agents — agent detection, signed MCP proxy, Tier-1 Edge Config short-circuit, trace beacon, and Tier-2 classify-fill for Next.js apps.

0High
0Medium
0Low

inceptionagents

vercel nextjs edge-middleware ai-agents mcp edge-config inception-agents

@inception-agents/vercel

Vercel Edge Middleware integration for Inception Agents — agent detection, signed MCP proxy, Tier-1 Edge Config short-circuit, trace beacon, and Tier-2 classify-fill for Next.js apps.

Install

npm install @inception-agents/vercel
# or
pnpm add @inception-agents/vercel

Requires Next.js 14+ and React 18+.

Quickstart

1. Add middleware

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

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

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

2. Add the trace beacon

// app/layout.tsx
import { InceptionTraceScript } from '@inception-agents/vercel/beacon';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
      <InceptionTraceScript tenantId={process.env.INCEPTION_TENANT_ID!} />
    </html>
  );
}

3. Configure environment variables

Set these in your Vercel project — the Inception Agents OAuth installer does this automatically:

INCEPTION_API_KEY — per-tenant API key
INCEPTION_TENANT_ID — tenant UUID
EDGE_CONFIG — connection string for your provisioned Edge Config (auto-set by installer)
INCEPTION_BEACON_SRC — beacon CDN override (optional)

That's it. Agent traffic now hits Edge Config Tier-1 cache (<15 ms p99); humans pass through unchanged.

Subpath imports for tree-shaking

Phase H (v1.0.0) ships subpath exports so customers using only one feature avoid the full middleware bundle:

| Import path | Bundle size (ESM) | Use when | |---|---:|---| | @inception-agents/vercel | ~711 KB | Default — full surface | | @inception-agents/vercel/middleware | ~702 KB | Just withInception | | @inception-agents/vercel/beacon | ~1 KB | Just <InceptionTraceScript /> | | @inception-agents/vercel/mcp | ~4 KB | Just MCP proxy / createMcpRoute | | @inception-agents/vercel/classify | ~7 KB | Just classify-fill route | | @inception-agents/vercel/trace | ~5 KB | Just detectBuyerArrival + cookies | | @inception-agents/vercel/tier-cache | ~8 KB | Just Tier-1 EC reader | | @inception-agents/vercel/variants | ~5 KB | Just variant decision reader |

Most customers use the default — middleware automatically wires every layer.

Optional features

MCP server (auto-proxied)

withInception auto-proxies /mcp requests to our hosted MCP backend with a HMAC-signed envelope. Set enableMcpProxy: false to opt out + mount your own:

// app/mcp/route.ts
import { createMcpRoute } from '@inception-agents/vercel/mcp';

export const POST = createMcpRoute({
  apiKey: process.env.INCEPTION_API_KEY!,
  tenantId: process.env.INCEPTION_TENANT_ID!,
});

Tier-2 classify-fill (opt-in)

When agents hit /agent/<endpoint> paths that aren't yet cached in Edge Config, you can have your middleware fire a fire-and-forget classify request to populate the cache for the next request. Two-step setup:

// app/api/_inception/classify/route.ts
import { createClassifyRoute } from '@inception-agents/vercel/classify';

export const POST = createClassifyRoute({
  apiKey: process.env.INCEPTION_API_KEY!,
  tenantId: process.env.INCEPTION_TENANT_ID!,
});

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

export const middleware = withInception({
  apiKey: process.env.INCEPTION_API_KEY!,
  tenantId: process.env.INCEPTION_TENANT_ID!,
  enableClassifyDelegate: true,  // ← opt in
});

The middleware fires event.waitUntil(enqueueClassify(...)) on cache misses; the route forwards to our backend's content generator + writes to Edge Config.

Direct buyer-arrival detection

For custom analytics integrations:

import { detectBuyerArrival } from '@inception-agents/vercel/trace';

const arrival = detectBuyerArrival(request);
if (arrival.isBuyerArrival) {
  console.log('AI-referred:', arrival.aiProvider, arrival.intentContextId);
}

Configuration reference

withInception({
  apiKey: string,                     // required — INCEPTION_API_KEY
  tenantId?: string,                  // recommended — INCEPTION_TENANT_ID
  apiUrl?: string,                    // override apps/api base
  bypassPaths?: string[],             // skip middleware entirely
  excludePaths?: string[],            // skip detection but still write trace cookies
  detectionThreshold?: number,        // 0-1, default 0.7
  enableMcpProxy?: boolean,           // default true when tenantId set
  mcpOriginUrl?: string,              // override MCP backend URL
  enableClassifyDelegate?: boolean,   // default false; requires classify route
  classifyPath?: string,              // default /api/_inception/classify
  cacheMaxAge?: number,               // CDN max-age for Tier-1 responses
  enableLlmsTxt?: boolean,            // default true
  enableJsonLd?: boolean,             // default true
  enableAgentCard?: boolean,          // default true
})

Documentation

Verification runbook — docs/runbooks/layer-b-verification-vercel.md
Security threat model — docs/security/vercel-threat-model.md
Phase A spike findings — tasks/ws2-phase-a-spike.md
Phase changelog — CHANGELOG.md

License

Apache-2.0

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@inception-agents/vercel

Install

Quickstart

1. Add middleware

2. Add the trace beacon

3. Configure environment variables

Subpath imports for tree-shaking

Optional features

MCP server (auto-proxied)

Tier-2 classify-fill (opt-in)

Direct buyer-arrival detection

Configuration reference

Documentation

License