@inception-agents/vercel
v1.1.1
Published
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.
Maintainers
inceptionagentsReadme
@inception-agents/vercel
Vercel Edge Middleware integration for Inception Agents — agent detection, the catalog route-through, 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/vercelRequires 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 keyINCEPTION_TENANT_ID— tenant UUIDEDGE_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 | ~257 KB | Default — full surface |
| @inception-agents/vercel/middleware | ~245 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
Catalog route-through (headless commerce)
For headless storefronts, withInception can serve your real catalog from the dynamic agent surfaces. Set enableRouteThrough: true (requires tenantId; the one-click installer enables it by default):
// middleware.ts
export const middleware = withInception({
apiKey: process.env.INCEPTION_API_KEY!,
tenantId: process.env.INCEPTION_TENANT_ID!,
enableRouteThrough: true,
});Requests to /agent/query, /agent/products, /agent/*, and the ACP/UCP endpoints (/.well-known/{acp,ucp}/*) are HMAC-SHA256-signed with your per-tenant key and forwarded to the Inception engine, which verifies the signature, binds the request to your tenant by host, and serves your normalized catalog. On any failure the request degrades to your origin — it never blocks. Tier-1 discovery surfaces, /mcp, and human traffic are unaffected.
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
enableRouteThrough?: boolean, // default false; requires tenantId — serve catalog at /agent/* + ACP/UCP
routeThroughOriginUrl?: string, // override route-through engine origin
routeThroughTimeoutMs?: number, // default 2500; degrades to origin on timeout
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