Custom Agents

Add your own AI agent detection patterns to AgentXP.

AgentXP ships with 20+ built-in detection patterns covering common crawlers and AI agents — GPTBot, ClaudeBot, and others. See the full list for every pattern included by default. For internal tools, less-common agents, or integrations you control, you can add custom detection patterns without touching the built-in list.

Adding a custom agent

Pass a customAgents array inside the detection config to register additional User-Agent patterns:

import { withAgentXP } from '@reaganhsu/agentxp-next'

export default withAgentXP({
  detection: {
    customAgents: [
      { name: 'MyInternalBot', pattern: /MyInternalBot\/\d+/i },
      { name: 'PartnerCrawler', pattern: /PartnerCrawler/i },
    ],
  },
})

Each entry requires a name (used in the x-agentxp-agent response header) and a pattern (a regular expression tested against the incoming User-Agent string). Custom agents are evaluated in addition to the built-in patterns — they don’t replace them.

Using Accept header detection

Any client that sends Accept: text/markdown is automatically detected as an agent with a confidence of 1.0. No extra configuration is needed. This is the most reliable detection signal and the recommended approach for integrations you control — internal scrapers, LLM tool calls, or any custom client. If you control the client, use Accept: text/markdown instead of User-Agent matching. Accept header detection has a confidence of 1.0, compared to 0.9 for User-Agent patterns — it’s the strongest signal available and requires no configuration on the server side.

Testing detection

Use curl to verify that AgentXP detects your agent and returns markdown:

# Test Accept header detection
curl -H "Accept: text/markdown" https://yoursite.com/

# Test a custom User-Agent pattern
curl -A "MyInternalBot/1.0" https://yoursite.com/

A successful detection returns a content-type: text/markdown response with an x-agentxp-agent header identifying which agent was matched.

Built-in agents

For the complete list of User-Agent patterns included by default, see Supported Agents.

Getting Started

Configuration

Guides

Reference

Custom Agents

Custom Agents

Adding a custom agent

Using Accept header detection

Testing detection

Built-in agents

​Custom Agents

​Adding a custom agent

​Using Accept header detection

​Testing detection

​Built-in agents

Custom Agents

Adding a custom agent

Using Accept header detection

Testing detection

Built-in agents