{"slug": "detecting-ai-agents-in-next-js-with-vouched-kya", "title": "Detecting AI Agents in Next.js with Vouched KYA", "summary": "Vouched released @kya-os/checkpoint-nextjs, an npm package that adds Vouched KYA's Detect engine to a Next.js 16 app's proxy.ts so every request is classified as human, ai_agent, bot or incomplete_data, adding a few milliseconds per request. The package requires Node.js 22.12 or later and a free Vouched KYA account with an sk_ API key, and runs in \"observe\" enforcementMode by default so requests are reported to the Vouched KYA dashboard but not blocked; Vouched built KYA on KYA-OS, an open standard it donated to the Decentralized Identity Foundation, and reserves policy enforcement and authorization checks for its paid Enforce and Govern plans.", "body_md": "Blog\n\n# Detecting AI Agents in Next.js with Vouched KYA\n\nAI agents like ChatGPT, Claude and Perplexity are already browsing websites on behalf of real people, and most of our websites can't tell them apart from humans or crawlers. But the good news is that we can fix that! In this post, we'll add Vouched KYA's Detect to a Next.js app in about 5 minutes, for free.\n\nPrefer to watch? Here's the video walkthrough.\n\n## What are Know Your Agent and Detect?\n\nYou've probably heard of KYC (Know Your Customer). [Know Your Agent](https://kya.vouched.id/?utm_source=vouched-blog&utm_medium=blog&utm_campaign=kya-brandon-nextjs-2026-11&utm_content=intro-kya) (KYA) is the same idea for the agent era: knowing which AI agents are interacting with our business, and which human authorized them. [Vouched](https://www.vouched.id/?utm_source=vouched-blog&utm_medium=blog&utm_campaign=kya-brandon-nextjs-2026-11&utm_content=intro-vouched) built Vouched KYA on KYA-OS, an open standard it has donated to the [Decentralized Identity Foundation](https://identity.foundation).\n\n[Vouched Detect](https://kya.vouched.id/docs/detect?utm_source=vouched-blog&utm_medium=blog&utm_campaign=kya-brandon-nextjs-2026-11&utm_content=intro-detect) classifies every request that reaches our servers as `human`, `ai_agent`, `bot` or `incomplete_data`. In Next.js, we run Vouched's detection engine right inside our app's [Proxy](https://nextjs.org/docs/app/getting-started/proxy), adding just a few milliseconds to each request. And - the best part - Detect has a [free tier](https://kya.vouched.id/pricing?utm_source=vouched-blog&utm_medium=blog&utm_campaign=kya-brandon-nextjs-2026-11&utm_content=intro-pricing), no card required. Vouched KYA's paid plans add [Enforce](https://kya.vouched.id/docs/enforce?utm_source=vouched-blog&utm_medium=blog&utm_campaign=kya-brandon-nextjs-2026-11&utm_content=intro-enforce) and [Govern](https://kya.vouched.id/docs/govern?utm_source=vouched-blog&utm_medium=blog&utm_campaign=kya-brandon-nextjs-2026-11&utm_content=intro-govern), where we can apply policies to agents and verify who authorized them. (We'll cover those in future posts!)\n\n## Code\n\nYou can find the completed code sample here: [https://github.com/vouched/KnowYourAgentWebsite-Nextjs-Sample](https://github.com/vouched/KnowYourAgentWebsite-Nextjs-Sample)\n\n### Prerequisites\n\n- A Next.js 16 app, using the App Router or the Pages Router\n- [Node.js 22.12](https://nodejs.org/en/download) or later\n- A free [Vouched KYA account](https://kya.vouched.id/signup?utm_source=vouched-blog&utm_medium=blog&utm_campaign=kya-brandon-nextjs-2026-11&utm_content=prereq-signup) with a project and an API key (it starts with`sk_` ).\n\n### 1. Add the npm Package\n\n```\nnpm install @kya-os/checkpoint-nextjs\n```\n\n### 2. Store our API Key (Safely!)\n\nOur API key is a secret, so it should NEVER be committed to source control. Next.js loads environment variables from `.env.local`, and the `.gitignore` that `create-next-app` generates already ignores it. Be sure to double-check your `.gitignore`; your future-self will thank you 💯.\n\nIn the root of our project, create `.env.local`:\n\n```\nCHECKPOINT_API_KEY=<your api key>\n```\n\nAnd when we deploy to production, be sure to set the same environment variable in our host, like Vercel.\n\n### 3. Add Vouched KYA to proxy.ts\n\nNext.js runs `proxy.ts` before every request, which makes it the perfect place for Detect. Create `proxy.ts` in the root of our project, or in `src/` if our app uses one:\n\n``` js\nimport { withCheckpoint } from \"@kya-os/checkpoint-nextjs\";\n\nexport default withCheckpoint({\n  // Reports every request to our Vouched KYA dashboard\n  apiKey: process.env.CHECKPOINT_API_KEY,\n\n  // Observe mode: classify and report every request, but don't block them\n  enforcementMode: \"observe\",\n});\n\nexport const config = {\n  // Run on every page, skipping Next.js' static files\n  matcher: [\"/((?!_next/static|_next/image|favicon.ico).*)\"],\n};\n```\n\nAnd that's it! Just one function call and we're up and running.\n\n`withCheckpoint` enforces policies by default, so in this example, we turn on observe mode explicitly. And if we forget our API key, our app still works; the SDK just can't report to our dashboard.\n\n### 4. Run the App\n\n```\nnpm run dev\n```\n\nOur website looks exactly the same, and that's the point.\n\n### 5. Simulate Agent + Bot Traffic\n\nNow let's pretend to be ChatGPT.\n\nIn a second terminal (on Windows PowerShell, type `curl.exe` instead of `curl`):\n\n```\ncurl -I -A \"Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; ChatGPT-User/1.0; +https://openai.com/bot\" http://localhost:3000/\n```\n\nAmong the response headers, we'll find these:\n\n```\nHTTP/1.1 200 OK\nx-checkpoint-mode: observe\nx-checkpoint-would-have-been: Permit\n```\n\nIt works! Detect is running in observe mode, and `Permit` is what it would have done if it were enforcing. Within a minute, our request shows up in the [Vouched KYA dashboard](https://kya.vouched.id/dashboard?utm_source=vouched-blog&utm_medium=blog&utm_campaign=kya-brandon-nextjs-2026-11&utm_content=step5-dashboard) under **Detect → Activity** as an `ai_agent` named ChatGPT. 🎉 Not seeing it? Add `debug: true` to `withCheckpoint`, and the SDK logs why a report didn't reach Vouched, like a mistyped API key.\n\nNext, try OpenAI's GPTBot user agent:\n\n```\ncurl -I -A \"Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.4; +https://openai.com/gptbot\" http://localhost:3000/\n```\n\nThe dashboard labels it a `bot`, because it's a crawler collecting training data, not an AI assistant browsing on behalf of a person.\n\n### 6. Logging in Code\n\nThe SDK calls `onResult` after it classifies each request, the perfect place to log it, send it to our analytics, or save it to our database. Let's add it to `proxy.ts`:\n\n```\nexport default withCheckpoint({\n  apiKey: process.env.CHECKPOINT_API_KEY,\n  enforcementMode: \"observe\",\n\n  // Runs after Vouched KYA classifies each request\n  onResult: (result, request) => {\n    const { detectionClass, detectedAgent, confidence } = result.detectionDetail;\n    console.log(\n      `${request.nextUrl.pathname}: ${detectionClass.type} ${detectedAgent?.name ?? \"\"} (${Math.round(confidence)}%)`,\n    );\n  },\n});\n```\n\nSend the ChatGPT and GPTBot requests again, plus plain old `curl -I http://localhost:3000/`, and our terminal shows:\n\n```\n/: AiAgent ChatGPT (100%)\n/: Bot GPTBot (100%)\n/: Bot Dev Tools (100%)\n```\n\nVouched KYA even knows curl is a developer tool! One thing to know: the SDK waits for `onResult` before it responds, so for slow work, use [`after()`](https://nextjs.org/docs/app/api-reference/functions/after) to run it after the response is sent.\n\n## Bonus: Unit Testing our Proxy\n\nBecause the engine runs inside our app, we can unit test `proxy.ts` with any user agent we like, no network required. The sample's [Vitest tests](https://github.com/vouched/KnowYourAgentWebsite-Nextjs-Sample/tree/main/test) do exactly that, with [helpers](https://github.com/vouched/KnowYourAgentWebsite-Nextjs-Sample/tree/main/test/support) that fake Vouched's API, so our CI catches any `@kya-os/checkpoint-nextjs` update that changes how our traffic is classified.\n\n## Conclusion\n\nAI agents are already visiting our websites, and with `@kya-os/checkpoint-nextjs`, it only takes one function call (and zero dollars) to start seeing them.\n\nThe [completed sample](https://github.com/vouched/KnowYourAgentWebsite-Nextjs-Sample) does everything in this post, plus one fun extra: paste your Project ID and API key into the page, click **Send simulated traffic**, and watch ChatGPT, Claude, Perplexity, GPTBot and more arrive in your dashboard!\n\n*Why \"Would be blocked\"?* The sample adds `engineConfig: { tier3Action: \"block\" }`, which tells Vouched KYA to block known AI agents, AI crawlers and headless browsers. Our `proxy.ts` leaves it out, which is why ChatGPT got `Permit`. In observe mode, nothing gets blocked either way.\n\nBuilding with .NET instead? Check out the [Blazor Server sample](https://github.com/vouched/KnowYourAgentWebsite-Dotnet-Blazor).\n\nNext, we'll move from observing to enforcing with Enforce. Subscribe to the Vouched KYA newsletter at the bottom of the [Vouched KYA home page](https://kya.vouched.id/?utm_source=vouched-blog&utm_medium=blog&utm_campaign=kya-brandon-nextjs-2026-11&utm_content=conclusion-newsletter) so you don't miss it!", "url": "https://wpnews.pro/news/detecting-ai-agents-in-next-js-with-vouched-kya", "canonical_source": "https://www.vouched.id/learn/blog/detecting-ai-agents-in-next.js-with-vouched-kya", "published_at": "2026-11-21 01:10:10+00:00", "updated_at": "2026-11-21 01:44:32.462014+00:00", "lang": "en", "topics": ["ai-agents", "ai-crawlers", "developer-tools", "agent-protocols", "ai-tools"], "entities": ["Vouched", "Vouched KYA", "Detect", "@kya-os/checkpoint-nextjs", "Next.js", "KYA-OS", "Decentralized Identity Foundation", "Enforce"], "also_reported_by": [], "takeaway": "Install @kya-os/checkpoint-nextjs and wrap proxy.ts with withCheckpoint in \"observe\" mode to classify every Next.js request as human, ai_agent, bot or incomplete_data at a few milliseconds of added latency, without blocking traffic.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/detecting-ai-agents-in-next-js-with-vouched-kya", "markdown": "https://wpnews.pro/news/detecting-ai-agents-in-next-js-with-vouched-kya.md", "text": "https://wpnews.pro/news/detecting-ai-agents-in-next-js-with-vouched-kya.txt", "jsonld": "https://wpnews.pro/news/detecting-ai-agents-in-next-js-with-vouched-kya.jsonld"}}