Install it yourself

Prefer to wire it in yourself? Install the package directly. To have your agent do this instead, see the Quickstart.

Install the package

npm i @mintlify/agent-traffic

It has no dependencies and runs anywhere fetch does: Node 20.10+, Bun, Deno, Cloudflare Workers and Vercel Edge.

Classify a user agent

import { classify } from '@mintlify/agent-traffic'

classify({ userAgent: 'axios/1.13.2' })
// { category: 'bot', kind: 'http-client', name: 'axios', verified: null, confidence: 'medium',
//   reasons: ['user agent is axios'] }

The user agent alone is enough for logs and quick checks.

Classify a full request

Pass the request headers and the real client IP to unlock header checks and verification:

import { classify, loadIpRanges } from '@mintlify/agent-traffic'

const ipRanges = await loadIpRanges()

const result = classify(
  { headers: request.headers, ip: request.headers.get('cf-connecting-ip') },
  { ipRanges }
)

A spoofed crawler now comes back as an impersonator:

// { category: 'bot', kind: 'impersonator', verified: false, confidence: 'high',
//   reasons: ["claims to be GPTBot but 73.12.4.9 is outside OpenAI's published ranges"] }

Act on the category

if (result.category === 'agent') {
  // serve markdown, log it, meter it
}

See Categories for what each value means.

On Cloudflare Workers, load IP ranges inside the request handler rather than at the top of the module. Workers don’t allow fetch at global scope. See Request-time classification.

Get started

Concepts

Guides

Reference

Project