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

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

```bash
npm install @lightsage/agent-tracker
```

Then add your API key to `.env.local`:

```bash
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:

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

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

```bash
wrangler secret put LIGHTSAGE_API_KEY
```

**Express**

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

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

```bash
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`:

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

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

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

## What you see in the dashboard

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

| Data point    | Description                                                                                           |
| -------------- | ----------------------------------------------------------------------------------------------------- |
| **Agent name** | Which AI agent made the visit (e.g., Claude Code, Cursor, ChatGPT)                                   |
| **Visit count**| Total visits from that agent over your selected time range                                            |
| **Pages visited** | Which specific pages the agent accessed, ranked by visit count                                         |
| **Timestamps** | When each visit occurred, shown in your local timezone                                               |
| **Visit trends** | Day-over-day and week-over-week visit volume per agent                                               |

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.