@inception-agents/express

Express middleware for Inception Agents. Detects AI agent traffic and serves optimized responses, with an optional detect-only mode that attaches agent metadata to the request object.

Installation

npm install @inception-agents/express

Peer dependency: express >= 4.18.0

Quick Start

import express from 'express';
import { inceptionMiddleware } from '@inception-agents/express';

const app = express();

app.use(inceptionMiddleware({
  apiKey: process.env.INCEPTION_API_KEY!,
}));

app.get('/', (req, res) => {
  // Human visitors reach here normally
  // Agent traffic is intercepted and served optimized content above
  res.send('Hello, human!');
});

app.listen(3000);

API Reference

inceptionMiddleware(options)

Creates an Express middleware that detects AI agent traffic and serves optimized responses. For human traffic, calls next() transparently. Never blocks human traffic on SDK errors.

app.use(inceptionMiddleware({
  apiKey: 'iak_your_api_key',
}));

Returns: (req: Request, res: Response, next: NextFunction) => Promise<void>

Detect-Only Mode

When detectOnly is true, the middleware attaches detection results to the request object without intercepting the response. Use this to build your own agent-specific logic.

app.use(inceptionMiddleware({
  apiKey: process.env.INCEPTION_API_KEY!,
  detectOnly: true,
}));

app.get('/products/:id', (req, res) => {
  if (req.inceptionAgent?.isAgent) {
    // Custom agent-specific logic
    console.log(`Agent detected: ${req.inceptionAgent.identity}`);
    console.log(`Intent: ${req.inceptionIntent?.archetype}`);
    return res.json(getProductDataForAgent(req.params.id));
  }

  res.render('product', { id: req.params.id });
});

Request Properties

When the middleware runs, it attaches these properties to the Express request:

| Property | Type | Description | |----------|------|-------------| | req.inceptionAgent | AgentDetectionResult \| undefined | Agent detection result (always set) | | req.inceptionIntent | IntentClassification \| undefined | Intent classification (set when agent detected) |

Configuration

ExpressMiddlewareOptions

Extends InceptionConfig from @inception-agents/core.

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your Inception Agents API key | | detectOnly | boolean | false | Attach metadata to req without serving optimized content | | debug | boolean | false | Enable debug logging | | excludePaths | string[] | ['/api/', '/_next/', ...] | Paths that bypass detection | | detectionThreshold | number | 0.7 | Minimum confidence to classify as agent | | cacheMaxAge | number | 300 | Cache-Control max-age (seconds) | | enableLlmsTxt | boolean | true | Serve /llms.txt and /llms-full.txt | | enableJsonLd | boolean | true | Serve JSON-LD enrichment for agents | | enableAgentCard | boolean | false | Serve /.well-known/agent.json |

Error Handling

The middleware never blocks human traffic on errors. If the detection or optimization pipeline throws, the middleware calls next() and lets the request continue to your application.

Exported Types

• InceptionConfig — Base configuration interface
• AgentDetectionResult — Detection result with agent identity and confidence
• IntentClassification — Classified agent intent
• ExpressMiddlewareOptions — Express-specific options extending InceptionConfig

Related

• Full documentation
• @inception-agents/core