Quick Start

Install AgentXP and serve your first markdown response in minutes.

Install the package

Add @reaganhsu/agentxp-next to your project.

npm install @reaganhsu/agentxp-next

Add middleware

Create middleware.ts in your project root (next to package.json). If your project uses a src/ directory, create src/middleware.ts instead.

middleware.ts

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

export default withAgentXP()

That’s all you need for a working installation. AgentXP detects AI agents and serves markdown automatically from this point forward.Already have middleware? If you use Clerk, next-intl, or any other middleware, pass it as the second argument:

middleware.ts

import { withAgentXP } from '@reaganhsu/agentxp-next'
import { clerkMiddleware } from '@clerk/nextjs/server'

export default withAgentXP({}, clerkMiddleware())

AgentXP runs first. If the request is from an AI agent, it handles the response. Otherwise, it passes the request to your existing middleware unchanged.

Add the AgentExperience component (optional)

Add the AgentExperience component to your root layout to inject structured metadata for agents — a JSON-LD WebSite schema, a link to /llms.txt, and AI-specific robots directives.

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

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <AgentExperience siteName="My Site" description="What my site does" />
      </body>
    </html>
  )
}

The component renders no visible UI. It injects:

JSON-LD structured data (WebSite schema)
A <link> to /llms.txt
AI-specific meta robots directives (noai, noimageai) based on your permissions settings

Verify it works

Start your dev server and send a request with Accept: text/markdown to any page:

curl -H "Accept: text/markdown" http://localhost:3000/

You should see clean markdown instead of HTML:

# Your Page Title

Your page content, converted to clean markdown.
Lists, links, tables, and code blocks are preserved.

---

*Source: [http://localhost:3000](http://localhost:3000)*

Check the response headers to confirm AgentXP is active:

curl -I -H "Accept: text/markdown" http://localhost:3000/

content-type: text/markdown; charset=utf-8
x-agentxp-agent: unknown
x-agentxp-version: 0.1.0
x-markdown-tokens: 342
content-signal: ai-train=no, ai-input=yes, search=yes

You can also verify the auto-generated endpoints:

# Site index for AI agents
curl http://localhost:3000/llms.txt

# Machine-readable capabilities manifest
curl http://localhost:3000/.well-known/agent-experience.json

Configuration

withAgentXP() accepts an optional configuration object. Here is a full example showing the available options:

export default withAgentXP({
  transform: {
    contentSelector: 'main',
    excludeSelectors: ['.chat-widget', '.cookie-banner'],
    maxTokens: 8000,
  },
  permissions: {
    aiTrain: false,
    aiInput: true,
    search: true,
  },
  llmsTxt: {
    siteName: 'My Site',
    description: 'What my site does',
    pages: [
      { path: '/docs', title: 'Docs', section: 'Documentation' },
      { path: '/pricing', title: 'Pricing', section: 'Product' },
    ],
  },
})

See Configuration overview for the full reference.

AgentXP requires Next.js 14 or later.

Getting Started

Configuration

Guides

Reference

Quick Start

Quick Start

Configuration

​Quick Start

​Configuration

Quick Start

Configuration