detectAgent(request)
Detect whether an incoming request is from an AI agent.import { detectAgent } from '@reaganhsu/agentxp-core'
const result = detectAgent(request)
if (result.isAgent) {
console.log(result.agent?.name) // e.g. "ClaudeBot"
}
Parameters
request
Type: Request (required)A standard Web API Request object. Inspects the Accept and User-Agent headers.Return type
interface DetectionResult {
isAgent: boolean
agent?: AgentInfo
}
interface AgentInfo {
name: string
confidence: number
method: 'accept-header' | 'user-agent' | 'http-signature' | 'behavioral'
}
isAgent (boolean, required): true when the request is identified as coming from an AI agent.agent (AgentInfo): Present when isAgent is true.
name (string, required): Matched agent name (e.g., "ClaudeBot", "GPTBot"), or "unknown" when detected via Accept: text/markdown with no matching User-Agent.confidence (number, required): Detection confidence score from 0 to 1. 1.0 for accept-header detection; 0.9 for user-agent pattern match.method (string, required): The signal that triggered detection. One of 'accept-header' | 'user-agent' | 'http-signature' | 'behavioral'.
Full HTML-to-markdown transformation pipeline. Processes a raw HTML string through four stages: expand hidden content, extract main content, convert to markdown, clean and finalize.import { transformForAgent } from '@reaganhsu/agentxp-core'
const result = transformForAgent(html, { baseUrl: 'https://example.com' })
console.log(result.markdown)
console.log(result.tokenEstimate)
Parameters
html
Type: string (required)Raw HTML string to transform.options
Type: TransformOptionsOptional transform configuration.
contentSelector (string): CSS selector for the main content area. Auto-detected when omitted.excludeSelectors (string[]): CSS selectors for elements to remove before conversion.baseUrl (string): Base URL for resolving relative links to absolute URLs in the output.maxTokens (number): Maximum token target. Content is truncated by section when exceeded.headingStyle (‘atx’ | ‘setext’): Markdown heading style. 'atx' uses # prefixes (default); 'setext' uses underlines.title (string): Page title override. Auto-extracted from the HTML when omitted.description (string): Page description written into the output metadata.includeNav (boolean | SiteHeaderConfig): Prepend a site navigation preamble to the output. Pass true to auto-extract from the page’s <header>/<nav>; pass a SiteHeaderConfig object to use a manual override. Omit or pass false for no preamble.
Return type
interface TransformResult {
markdown: string
tokenEstimate: number
metadata: {
title: string
sourceUrl?: string
description?: string
}
processingTimeMs: number
}
markdown (string, required): The agent-optimized markdown output.tokenEstimate (number, required): Estimated token count of the markdown output, calculated as Math.ceil(markdown.length / 4).metadata (object, required): Extracted page metadata.
title (string, required): Page title extracted from the HTML or provided via options.title.sourceUrl (string): Source URL, set from options.baseUrl when provided.description (string): Page description extracted from the HTML or provided via options.description.
processingTimeMs (number, required): Wall-clock time in milliseconds for the full pipeline.
generateLlmsTxt(options)
Generate a standards-compliant llms.txt file following the llmstxt.org specification.import { generateLlmsTxt } from '@reaganhsu/agentxp-core'
const content = generateLlmsTxt({
siteName: 'My App',
description: 'Developer documentation for My App.',
baseUrl: 'https://example.com',
pages: [
{ path: '/docs', title: 'Documentation', section: 'Documentation' },
{ path: '/pricing', title: 'Pricing', section: 'Product' },
],
})
Parameters
options
Type: LlmsTxtOptions (required)
siteName (string, required): Site name written as the top-level # Heading of the file.description (string): Site description written as a > blockquote below the heading.baseUrl (string, required): Base URL prepended to each page path to form absolute links.pages (LlmsTxtPage[], required): List of pages to include. Each entry:
interface LlmsTxtPage {
path: string // URL path, e.g. "/pricing"
title: string // Page title
description?: string
section?: string // Section grouping, e.g. "Documentation"
}
maxPages (number): Maximum number of pages to include. Defaults to 15. Pages beyond this limit are silently omitted.
Return type
Returns a string containing the complete llms.txt content.
defineConfig(config)
Type-safe configuration factory for agentxp.config.ts. Returns the config object unchanged — its only purpose is to provide TypeScript type inference and editor autocompletion.// agentxp.config.ts
import { defineConfig } from '@reaganhsu/agentxp-core'
export default defineConfig({
permissions: {
aiTrain: false,
aiInput: true,
search: true,
},
transform: {
maxTokens: 6000,
},
})
Parameters
config
Type: AgentXPConfig (required)Your AgentXP configuration object. All fields are optional.interface AgentXPConfig {
detection?: {
signals?: ('accept-header' | 'user-agent' | 'http-signature')[]
customAgents?: { name: string; pattern: RegExp }[]
}
transform?: {
contentSelector?: string
excludeSelectors?: string[]
handlers?: Record<string, (el: Element) => string>
maxTokens?: number
}
llmsTxt?: {
autoGenerate?: boolean
include?: string[]
exclude?: string[]
description?: string
maxPages?: number
}
analytics?: {
enabled?: boolean
endpoint?: string
}
permissions?: {
aiTrain?: boolean
aiInput?: boolean
search?: boolean
}
}
Return type
Returns the config typed as AgentXPConfig. Use with a default export in agentxp.config.ts.defineConfig is a zero-overhead identity function — it exists purely for TypeScript autocompletion. When using Edge Runtime middleware, pass your config directly to withAgentXP() rather than loading it from a separate file, since dynamic import() and process.cwd() are not available in the Edge Runtime.
