@clickport/agents

See which AI agents read your site. This is the server-side connector for Clickport's AI Agent Analytics.

AI assistants like ChatGPT, Claude and Perplexity fetch your pages without executing JavaScript, so no browser tracker can see them. This package observes requests on your server and forwards their metadata to Clickport, where every hit is classified and IP-verified. The connector itself never classifies anything, which means it never needs an update when new AI agents appear.

What it sends per request: timestamp, path, method, status, duration, and a fixed whitelist of request headers (user agent, referrer, IP forwarding headers, and bot-signature headers). Never cookies, never authorization headers, never request bodies.

Setup

You need a Clickport site and an agent key: Site settings, AI Agents, Generate key. Set it as CLICKPORT_AGENT_KEY in your environment, or pass { key } in the config.

Next.js

Create middleware.ts (Next 12.2 to 15) or proxy.ts (Next 16) at the project root:

import { withClickportAgents } from '@clickport/agents/next';

export default withClickportAgents({ key: process.env.CLICKPORT_AGENT_KEY });

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

Already have middleware? Wrap it:

export default withClickportAgents({ key: process.env.CLICKPORT_AGENT_KEY }, myMiddleware);

Works on Vercel (including the Hobby plan), Netlify, and self-hosted. Delivery rides the platform's waitUntil, so it adds zero latency and is not lost when the serverless environment freezes after the response.

Honest limitation: middleware runs before your routes, so these reports carry no response status. A request that ends up a 404 is still counted as a fetch. If you need exact status codes, use the Express adapter (self-hosted) or wrap individual route handlers with withAgentTelemetry.

Express

import { clickportAgents } from '@clickport/agents/express';

app.use(clickportAgents({ key: process.env.CLICKPORT_AGENT_KEY }));

Full fidelity: real status codes and durations, only successful GET/HEAD content responses are reported. Lines are batched (20 lines or 5 seconds) and the queue is memory-bounded. For clean shutdowns:

import { flushAll } from '@clickport/agents/express';
process.on('SIGTERM', async () => { await flushAll(); process.exit(0); });

Plain node:http

import { instrument } from '@clickport/agents/node';

const server = createServer(handler);
instrument(server, { key: process.env.CLICKPORT_AGENT_KEY });

Verify it works

In your Clickport site settings, open AI Agents and click "Test my connector", or fetch any page of your site with:

curl -A "ClickportConnectorTest/1.0 (+https://clickport.io/docs/ai-agents)" https://your-site.com/

The connection status flips to connected within seconds.

Config

| Option | Default | Purpose | | --- | --- | --- | | key | CLICKPORT_AGENT_KEY env | Site API key with the agent-visits scope | | endpoint | Clickport production API | Override for testing | | exclude | none | Extra RegExp[] path patterns to skip | | flushAt | 20 | Batch size (Express/node adapters) | | flushIntervalMs | 5000 | Batch interval (Express/node adapters) | | onError | silent | Callback for failed deliveries |

Static assets, /_next/* internals, and non-GET/HEAD requests are always skipped. Reporting is wrapped so it can never break or slow your site.

License

MIT