@inception-agents/cloudflare

Cloudflare Worker middleware for Inception Agents. Intercepts AI agent traffic at the edge with optional KV-backed caching for sub-millisecond cached responses.

Installation

npm install @inception-agents/cloudflare

Quick Start

Worker Setup

import { createInceptionHandler } from '@inception-agents/cloudflare';

const handler = createInceptionHandler({
  apiKey: 'iak_your_api_key',
  originUrl: 'https://your-origin.com',
});

export default {
  async fetch(request: Request, env: Record<string, unknown>, ctx: ExecutionContext) {
    return handler(request, env, ctx);
  },
};

With KV Caching

import { createInceptionHandler } from '@inception-agents/cloudflare';

interface Env {
  INCEPTION_CACHE: KVNamespace;
  INCEPTION_API_KEY: string;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const handler = createInceptionHandler({
      apiKey: env.INCEPTION_API_KEY,
      originUrl: 'https://your-origin.com',
      kvCache: env.INCEPTION_CACHE,
      kvCacheTtl: 600,
    });

    return handler(request, env, ctx);
  },
};

wrangler.toml

name = "my-site-inception"
main = "src/index.ts"
compatibility_date = "2024-12-01"

[[kv_namespaces]]
binding = "INCEPTION_CACHE"
id = "your-kv-namespace-id"

[vars]
INCEPTION_API_KEY = "iak_your_api_key"

API Reference

createInceptionHandler(options)

Creates a Cloudflare Worker fetch handler that intercepts agent traffic and serves optimized responses. Non-agent traffic is proxied to the configured origin.

Returns: (request: Request, env?: Record<string, unknown>, ctx?: ExecutionContext) => Promise<Response>

createDetectionHandler(config)

Creates a lightweight detection-only handler that returns agent detection metadata as JSON. Useful as a Worker binding for service-to-service detection without content optimization.

import { createDetectionHandler } from '@inception-agents/cloudflare';

const detect = createDetectionHandler({ apiKey: 'iak_...' });

export default {
  async fetch(request: Request) {
    return detect(request);
    // Returns: { isAgent: true, agentType: "assistant", identity: "ChatGPT-User", ... }
  },
};

Returns: (request: Request) => Promise<Response> (JSON response with AgentDetectionResult)

Configuration

CloudflareHandlerOptions

Extends InceptionConfig from @inception-agents/core.

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your Inception Agents API key | | originUrl | string | — | Origin URL for proxying non-agent traffic | | kvCache | KVNamespace | — | KV namespace for caching optimized responses | | kvCacheTtl | number | 300 | Cache TTL in seconds for KV-backed responses | | debug | boolean | false | Enable debug logging | | 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 |

KV Caching

When a kvCache namespace is provided, optimized responses are cached in Cloudflare KV for subsequent requests. The cache key is inception:{pathname}.

• Cache writes happen asynchronously via ctx.waitUntil() to avoid blocking the response
• Cached responses include an X-Inception-Cache: HIT header
• TTL defaults to 300 seconds (5 minutes), configurable via kvCacheTtl

Exported Types

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

Related

• Full documentation
• @inception-agents/core