Agent Tracking: See Which AI Agents Visit Your Docs

Add one line of middleware to detect AI coding agent visits to your website and documentation in real time, with zero performance impact.

Agent Tracking is a lightweight middleware layer that detects when AI coding agents visit your website or documentation. When Claude Code, OpenCode, ChatGPT, or any of the other supported agents reads your docs pages, Lightsage records the visit — giving you real data on which agents are actively researching your API.

Why this matters

You can optimize your documentation for AI agents without knowing which ones are actually visiting. But with Agent Tracking, you see the real picture: Claude Code visits your quick start 40 times a day, while Codex primarily reads your API reference. That's not a guess — it's a signal you can act on.

Understanding agent visit patterns helps you:

• Prioritize which agents to run API Performance evaluations against
• Identify which documentation pages agents read most (and which they skip)
• Detect when a new agent starts using your docs after you publish or update content
• Correlate documentation changes with changes in agent visit frequency

How it works

The middleware inspects incoming HTTP requests for agent-specific user agent strings. When it detects a known AI coding agent or answer engine, it logs the visit — including which page was accessed and a timestamp — and forwards the data to Lightsage. The middleware adds no detectable latency to normal user traffic.

Installation

Next.js

Create or update your middleware.ts file at the root of your project:

import { withAgentTracking } from '@lightsage/agent-tracker/next';

export default withAgentTracking({
  apiKey: process.env.LIGHTSAGE_API_KEY
});

export const config = {
  matcher: ['/((?!api|_next|admin).*)'],
};

Install the package:

npm install @lightsage/agent-tracker

Then add your API key to .env.local:

LIGHTSAGE_API_KEY=your_api_key_here

Vercel

If you're deploying to Vercel without Next.js, add the middleware directly to your Vercel project. Create middleware.ts at the project root:

import { withAgentTracking } from '@lightsage/agent-tracker/vercel';
import { NextRequest } from 'next/server';

export default withAgentTracking({
  apiKey: process.env.LIGHTSAGE_API_KEY
});

export const config = {
  matcher: ['/((?!api|_next|admin).*)'],
};

Set the environment variable in your Vercel project settings under Settings → Environment Variables:

LIGHTSAGE_API_KEY = your_api_key_here

Cloudflare Workers

Add the Lightsage tracker to your Cloudflare Worker:

import { createAgentTracker } from '@lightsage/agent-tracker/cloudflare';

const tracker = createAgentTracker({
  apiKey: env.LIGHTSAGE_API_KEY
});

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    await tracker.track(request);
    return fetch(request);
  }
};

Add the secret to your Worker via Wrangler:

wrangler secret put LIGHTSAGE_API_KEY

Express

Add the middleware to your Express app before your route handlers:

import express from 'express';
import { agentTracker } from '@lightsage/agent-tracker/express';

const app = express();

app.use(agentTracker({
  apiKey: process.env.LIGHTSAGE_API_KEY
}));

// Your routes below
app.get('/', (req, res) => {
  res.send('Hello world');
});

Set the environment variable before starting your server:

LIGHTSAGE_API_KEY=your_api_key_here node server.js

Netlify

Add an edge function to your Netlify project. Create netlify/edge-functions/agent-tracker.ts:

import { createAgentTracker } from '@lightsage/agent-tracker/netlify';

const tracker = createAgentTracker({
  apiKey: Deno.env.get('LIGHTSAGE_API_KEY')
});

export default tracker.handler;

export const config = {
  path: '/*'
};

Add the environment variable in the Netlify dashboard under Site configuration → Environment variables.

The LIGHTSAGE_API_KEY

Your API key connects the middleware to your Lightsage account. Find it in your Lightsage dashboard under Settings → API Keys.

The matcher config (Next.js and Vercel)

The matcher pattern controls which routes the middleware runs on:

export const config = {
  matcher: ['/((?!api|_next|admin).*)'],
};

This regex matches every path except:

• /api/* — your own API routes (no need to track these)
• /_next/* — Next.js internal assets and static files
• /admin/* — your admin panel (if one exists)

If your documentation lives on a subdirectory like /docs, you can narrow the matcher to only track those pages:

export const config = {
  matcher: ['/docs/:path*'],
};

What you see in the dashboard

After installing the middleware, the Agent Analytics section of your dashboard shows:

You can filter by agent, date range, and page path to drill into specific patterns.

Agents detected

Lightsage's middleware detects all 17 tracked AI platforms:

Coding agents (10)

Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, OpenClaw, OpenCode, Hermes, Pi, Kilo

Answer engines (7)

ChatGPT, Google AI Overviews, Google AI Mode, Gemini Search, Perplexity, Claude, Microsoft Copilot

The middleware tracks visits from AI agent user agents, not human developer visits. Your existing analytics tools continue to capture human traffic normally. Agent Tracking adds a parallel view of your AI audience without replacing or interfering with any existing analytics setup.

Performance impact

The middleware operates asynchronously — it sends tracking data to Lightsage without blocking the request. For your human users, response times are unaffected. For AI agent visits, tracking adds no perceptible delay because agents are making HTTP requests regardless and aren't sensitive to single-digit millisecond differences.

Lightsage does not proxy your traffic. Requests go directly from the agent to your server; the middleware reads the request headers and fires a non-blocking event to Lightsage in the background.