npm package: @inception-agents/express
Description: 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.
Latest version: 0.1.0

# @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

```bash
npm install @inception-agents/express
```

**Peer dependency:** `express` >= 4.18.0

## Quick Start

```typescript
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.

```typescript
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.

```typescript
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](https://www.inceptionagents.com/docs/integrations/express)
- [@inception-agents/core](https://www.npmjs.com/package/@inception-agents/core)