வழிகாட்டி

Node.js app-க்கு actor context எப்படி சேர்ப்பது

ஒவ்வொரு request-க்குப் பின்னும் யார் அல்லது எது உள்ளது என்பதை பதிவு செய்யும் middleware-ஐ உருவாக்குவதற்கான படிப்படியான guide, ώστε நீங்கள் எதையும் enforce செய்வதற்கு முன் உண்மையான traffic-ஐ ஆய்வு செய்யலாம்.

ஆசிரியர் Toshendra SharmaFounder & CEO, AgentCredia · Updated November 13, 2026

தொடக்கநிலை · 9 நிமிட வாசிப்பு

rules-க்கு பதிலாக actor context-இல் ஏன் தொடங்க வேண்டும்?

தங்களுடைய traffic-ல் AI agents இருப்பதை கவனிக்கும் பெரும்பாலான teams முதலில் ஒரு rule-ஐத் தேடுகிறார்கள். ஒரு user agent-ஐ block செய்யவும், ஒரு challenge சேர்க்கவும், ஒரு rate limit-ஐ கடுக்கவும். ஆனால் traffic-ஐ புரிந்து கொள்வதற்கு முன் எழுதப்பட்ட rule, தவறான மக்களைத் தாக்கும் சாத்தியம் அதிகம். சட்டப்பூர்வமான assistants block செய்யப்படுகின்றன, உண்மையான users challenge செய்யப்படுகிறார்கள், மற்றும் நீங்கள் உண்மையில் கவலைப்பட்ட automation தன்னை ஒருபோதும் அடையாளப்படுத்தாததால் தொடர்ந்து வருவதைத் தொடர்கிறது.

Actor context என்பது rules-க்கு முந்தைய படி. ஒவ்வொரு request-க்கும், செயல்படுவது யார் அல்லது எது என்பதைக் குறித்து உங்கள் application கவனிக்கக்கூடியதை பதிவு செய்கிறீர்கள்: ஒரு interactive person, AI assistant-உடன் பணிபுரியும் ஒரு person, ஒரு autonomous agent, அல்லது இன்னும் வேறுபடுத்த முடியாத ஒன்றை. அந்த பார்வைக்கு பின்னுள்ள evidence-ஐ பதிவு செய்கிறீர்கள், மேலும் அதை request-ன் outcome-க்கு அருகில் வைத்திருக்கிறீர்கள். இதை ஒரு அல்லது இரண்டு வாரங்கள் செய்த பிறகு, எந்த rule template-மும் தர முடியாத ஒன்றை பெறுகிறீர்கள்: உங்கள் சொந்த traffic-ன் ஒரு map. agents உங்கள் site-க்கு வருகிறார்களா என்பதையே இன்னும் தீர்மானிக்கிறீர்கள் என்றால், website traffic AI agents-இலிருந்து வருகிறதா என்பதை எப்படி அறியலாம் என்பதிலிருந்து தொடங்கவும்.

இந்த guide, plain middleware-ஐப் பயன்படுத்தி ஒரு Node.js application-ல் அந்த layer-ஐ உருவாக்குகிறது. இது Express உடன் வேலை செய்கிறது, அதே ideas Fastify, Koa, Hono அல்லது Next.js route handler-க்கும் பொருந்தும்.

நீங்கள் உருவாக்கப்போவது என்ன

முடிவில் உங்களிடம் இருக்கும்:

ஒவ்வொரு request-இலிருந்தும் actor evidence-ஐ எடுக்கும் middleware.
ஒவ்வொரு result-க்கும் குறிப்பிடப்பட்ட basis-உடன் ஒரு சிறிய, தெளிவான classification.
request எப்படி handle செய்யப்படுகிறது என்பதை ஒருபோதும் மாற்றாத structured observation logs.
பின்னர் வரும் handlers அதைப் படிக்க request-க்கு result-ஐ இணைக்கும் ஒரு வழி.

இங்கே எதுவும் request-ஐ block செய்யாது. அது திட்டமிட்டதே.

Step 1: உங்கள் server உண்மையில் எந்த evidence-ஐப் பார்க்க முடியும்?

ஒரு server, மக்கள் நினைப்பதை விட குறைவாகவே பார்க்கிறது. code எழுதுவதற்கு முன், உங்கள் edge-இல் கிடைக்கும் signals-ஐ பட்டியலிடவும்:

Request signatures. சில automated clients, HTTP Message Signatures (RFC 9421)-ஐப் பயன்படுத்தி requests-ஐ sign செய்கின்றன, Signature-Input மற்றும் Signature headers-ஐ அனுப்புகின்றன, மேலும் பெரும்பாலும் operator-ன் published keys-ஐச் சுட்டும் Signature-Agent header-உடன் வருகின்றன, இதை IETF Web Bot Auth protocol draft விவரிக்கிறது.
Declared identity. Clients தங்களை User-Agent header-இல், From header-இல், அல்லது MCP client name போன்ற protocol metadata வழியாகப் பெயரிடலாம். MCP clients, 2025-11-25 revision-ன் initialize request-இல் தாங்களே தேர்ந்தெடுத்த clientInfo name-ஐ தெரிவிக்கின்றன, மேலும் 2026-07-28 revision client identity-ஐ per-request metadata ஆகக் கொண்டுசெல்கிறது. இவை declarations, யாரும் அவற்றைப் பிரதிபலிக்க முடியும்.
Authentication context. request-ல் session cookie, bearer token அல்லது API key உள்ளதா, மற்றும் அது எந்த வகையான credential என்பதா.
Protocol shape. Accept headers, client HTML அல்லது JSON-ஐ request செய்கிறதா, page assets-ஐ load செய்கிறதா, மற்றும் redirects மற்றும் cookies-ஐ எப்படிக் கையாளுகிறது என்பதைக் கவனிக்கவும்.
Application declarations. உங்கள் own product, network அறிய முடியாத விஷயங்களை அறிந்திருக்கலாம், உதாரணமாக ஒரு user "AI assisted" option-ஐத் தேர்வு செய்திருப்பது, அல்லது உங்கள் built-in assistant feature-இலிருந்து request வருவது.

ஒவ்வொரு signal-க்கும் வேறு வலிமை உள்ளது. சரிபார்க்கப்பட்ட signature check செய்யக்கூடியது. user agent string என்பது ஒரு claim. காணாமல் போன cookie என்பது வெறுமனே காணாமல் போனதுதான். இவைகளைத் தனித்தனியாக வைத்திருப்பதே இந்த exercise-ன் முழு நோக்கம்.

Step 2: முடிவை தெளிவாக மாதிரியாக்கவும்

Detection logic-ஐ எழுதுவதற்கு முன் actor result-ன் வடிவத்தை வரையறுக்கவும். ஒரு சிறிய, typed model, ஒரு classification என்ன பொருள் கொண்டது என்பதில் அனைவரையும் நேர்மையாக வைத்திருக்கும். இங்கே பயன்படுத்தப்படும் நான்கு classes Human, AI-assisted or agent: a practical taxonomy for application traffic-இல் விளக்கப்பட்டுள்ளன.

export type ActorClass = "human" | "human_ai" | "agent" | "unknown";
export type EvidenceBasis = "verified" | "declared" | "inferred" | "unknown";

export interface ActorEvidence {
  signaturePresent: boolean;
  signatureAgent?: string;
  declaredClient?: string;
  credentialType: "session" | "api_key" | "bearer" | "none";
  acceptsHtml: boolean;
  appDeclaredAssist: boolean;
}

export interface ActorResult {
  actor: ActorClass;
  basis: EvidenceBasis;
  reasons: string[];
  evidence: ActorEvidence;
  observedAt: string;
}

இரண்டு fields மிக முக்கியம். actor என்பது class. basis என்பது ஏன் அப்படிச் சொல்கிறீர்கள் என்பதைக் காட்டுகிறது. சரிபார்க்கப்பட்ட signature-ஐ அடிப்படையாகக் கொண்ட agent result-உம், user agent string-ஐ அடிப்படையாகக் கொண்ட agent result-உம் இரண்டும் "agent" தான், ஆனால் பின்னர் அவை மிகவும் வேறுபட்ட முறையில் கையாளப்பட வேண்டும், ஆகவே அவற்றை ஒருபோதும் ஒன்றாகக் கரைக்க வேண்டாம்.

Step 3: middleware-இல் evidence-ஐ எடுக்கவும்

Extraction படி headers மற்றும் request state-ஐ வாசிக்கிறது. இது இன்னும் எதையும் தீர்மானிக்காது.

import type { Request, Response, NextFunction } from "express";

const KNOWN_AGENT_TOKENS = ["bot", "crawler", "spider", "agent", "gpt", "claude"];

export function extractEvidence(req: Request): ActorEvidence {
  const ua = (req.get("user-agent") || "").toLowerCase();
  const auth = req.get("authorization") || "";
  const hasSession = Boolean(req.cookies?.session);

  let credentialType: ActorEvidence["credentialType"] = "none";
  if (hasSession) credentialType = "session";
  else if (auth.toLowerCase().startsWith("bearer ")) credentialType = "bearer";
  else if (req.get("x-api-key")) credentialType = "api_key";

  const declaredToken = KNOWN_AGENT_TOKENS.find((t) => ua.includes(t));

  return {
    signaturePresent: Boolean(req.get("signature") && req.get("signature-input")),
    signatureAgent: req.get("signature-agent") || undefined,
    declaredClient: declaredToken ? ua.slice(0, 200) : undefined,
    credentialType,
    acceptsHtml: (req.get("accept") || "").includes("text/html"),
    appDeclaredAssist: req.get("x-app-assist") === "1",
  };
}

இந்த code குறித்து சில குறிப்புகள்:

signaturePresent signature headers இருக்கின்றன என்பதை மட்டும் பதிவு செய்கிறது. Validation என்பது தனித்த step, signed agent requests-ஐ verify செய்வது குறித்த guide-இல் அது விரிவாக உள்ளது.
user agent token list திட்டமிட்டு எளிமையாக உள்ளது. இது ஒரு declaration-ஐ உருவாக்குகிறது, verification-ஐ ஒருபோதும் அல்ல.
x-app-assist என்பது user உங்கள் built-in AI feature வழியாக வேலை செய்யும்போது உங்கள் own frontend அனுப்பும் எதற்காகவும் ஒரு stand-in ஆகும். அதை உங்கள் உண்மையான mechanism-ஆல் மாற்றவும்.

Step 4: குறிப்பிடப்பட்ட basis-உடன் classify செய்யவும்

இப்போது evidence-ஐ result-ஆக மாற்றவும். rules-ஐ சுருக்கமாக வைத்திருக்கவும், வலுவான evidence-இலிருந்து பலவீனமானதுவரை வரிசைப்படுத்தவும், மற்றும் எப்போதும் Unknown-க்கு fall through செய்யவும்.

export async function classify(
  evidence: ActorEvidence,
  verifySignature: () => Promise<boolean>,
): Promise<ActorResult> {
  const reasons: string[] = [];
  const observedAt = new Date().toISOString();

  if (evidence.signaturePresent && (await verifySignature())) {
    reasons.push("request signature validated");
    return { actor: "agent", basis: "verified", reasons, evidence, observedAt };
  }

  if (evidence.appDeclaredAssist) {
    reasons.push("application reported its built-in assistant");
    return { actor: "human_ai", basis: "declared", reasons, evidence, observedAt };
  }

  if (evidence.declaredClient) {
    reasons.push("client declared itself as automated");
    return { actor: "agent", basis: "declared", reasons, evidence, observedAt };
  }

  if (evidence.credentialType === "session" && evidence.acceptsHtml) {
    reasons.push("interactive browser session");
    return { actor: "human", basis: "inferred", reasons, evidence, observedAt };
  }

  reasons.push("insufficient evidence");
  return { actor: "unknown", basis: "unknown", reasons, evidence, observedAt };
}

இது என்ன செய்யாது என்பதை கவனிக்கவும். இது ஒருபோதும் ஒரு declaration-ஐ verification-ஆக உயர்த்தாது. interactive signal இல்லாத request-க்கு Human-ஐ ஒருபோதும் ஒதுக்காது. அது புரியாவிட்டால், Unknown என்று சொல்கிறது. Unknown என்பது செல்லுபடியாகும், பயனுள்ள பதில், மேலும் உங்கள் visibility எங்கு முடிகிறது என்பதைக் துல்லியமாகச் சொல்கிறது. முழு காரணத்தை AI traffic-க்கு Unknown ஏன் செல்லுபடியாகும் result என்பதில் விளக்குகிறோம்.

Step 5: observation mode-ல் இணைக்கவும்

middleware-ஐ ஆரம்பத்திலேயே mount செய்யவும், result-ஐ request-க்கு இணைக்கவும், அதை log செய்யவும். அதன் அடிப்படையில் branch செய்ய வேண்டாம்.

import express from "express";
import cookieParser from "cookie-parser";

const app = express();
app.use(cookieParser());

app.use(async (req, res, next) => {
  try {
    const evidence = extractEvidence(req);
    const result = await classify(evidence, async () => false);
    res.locals.actor = result;

    res.on("finish", () => {
      logActor({
        route: req.route?.path ?? req.path,
        method: req.method,
        status: res.statusCode,
        actor: result.actor,
        basis: result.basis,
        reasons: result.reasons,
      });
    });
  } catch {
    res.locals.actor = undefined;
  }
  next();
});

இதை பாதுகாப்பாக்கும் மூன்று விவரங்கள்:

try block detection-இல் ஏற்படும் எந்த failure-யும் response-ஐ பாதிக்காது என்பதை உறுதி செய்கிறது. Observation என்பது fail open ஆக இருக்க வேண்டும்.
Logging finish-ல் நடக்கிறது, ஆகவே நீங்கள் உண்மையான status code-ஐப் பிடிக்க முடியும், பின்னர் classifications-ஐ outcomes-உடன் ஒப்பிட முடியும்.
உண்மையான validation-ஐ நீங்கள் செயல்படுத்தும் வரை verifySignature என்பது false ஆக stub செய்யப்பட்டிருக்கும். இதனால் signed requests-ஐ declared அல்லது unknown buckets-இல் வைத்திருக்கும், அவற்றை அதிகமாகக் காட்டாமல்.

Step 6: debugging-க்கு மட்டுமல்ல, analysis-க்காகவும் log செய்யவும்

aggregate செய்யக்கூடிய logs-ஐ எழுதவும். ஒவ்வொரு request-க்கும் ஒரு structured line போதும்.

function logActor(entry: Record<string, unknown>) {
  process.stdout.write(JSON.stringify({ type: "actor_observation", ...entry }) + "\n");
}

இந்த logs-இல் personal data-வை வைக்க வேண்டாம். உங்களுக்குத் தேவை route, class, basis, reasons மற்றும் outcome. உங்கள் traffic mix-ஐப் புரிந்துகொள்ள முழுமையான IP addresses, raw cookies அல்லது request bodies தேவையில்லை. தொடர்பு வைத்திருக்க எந்த identifier-ஐயாவது வைத்தால், அதை rotating salt-உடன் hash செய்து, குறுகிய retention period-ஐ அமைக்கவும்.

Step 7: செயல்படுவதற்கு முன் data-வைப் படிக்கவும்

சாதாரண வாராந்திர patterns-ஐக் காணும் அளவுக்கு observation mode-ல் இயக்கவும். பிறகு சில கேள்விகளுக்குப் பதிலளிக்கவும்:

எந்த routes agents-ஐ ஈர்க்கின்றன? Documentation, catalog மற்றும் search endpoints பொதுவாக அப்படித் தான். Account மற்றும் checkout flows பொதுவாக அப்படியல்ல.
Agent results-இல் எவ்வளவு verified, எவ்வளவு declared? அந்த ratio, policies எழுதும்போது identity-யை எவ்வளவு நம்பமுடியும் என்பதைச் சொல்கிறது.
Unknown எங்கு அதிகமாகக் குவிகிறது? ஒரு route-ல் உயர்ந்த Unknown rate பெரும்பாலும் அங்கு signal ஒன்று காணாமல் போயிருப்பதை குறிக்கும், உதாரணமாக உங்கள் frontend code-ஐ ஒருபோதும் இயக்காத ஒரு page.
Class-ஐப் பொறுத்து outcomes வேறுபடுகிறதா? error rates, conversion steps அல்லது abuse reports-ஐ classes-க்கிடையில் ஒப்பிடுங்கள். இங்கிருந்துதான் உண்மையான policy ideas உருவாகின்றன.

இந்த பதில்கள் அடிக்கடி ஆச்சரியப்படுத்தும். பெரிய பகுதி "bot problem" என்பது உண்மையில் சட்டப்பூர்வமான automation ஆக இருப்பதைக் teams அடிக்கடி கண்டுபிடிக்கின்றன, அது ஒரு structured endpoint இருந்தால் மகிழ்ச்சியாகப் பயன்படுத்தியிருக்கும்.

Step 8: result-ஐ உங்கள் app-ன் மீதமுள்ள பகுதிக்கு வெளிப்படுத்தவும்

data ஓடத் தொடங்கியதும், enforcing அல்லாத பயன்பாடுகளுக்காக handlers res.locals.actor-ஐப் படிக்க விடுங்கள்: analytics tags, response format-ஐத் தேர்வு செய்தல், அல்லது ஒரு support ticket AI-assisted session-இலிருந்து வந்தது என்பதை பதிவு செய்தல். இந்த பயன்பாடுகள் யாரையும் lock out செய்யும் அபாயம் இல்லாமல் அனுபவத்தை மேம்படுத்தும்.

app.get("/docs/:page", (req, res) => {
  const actor = res.locals.actor as ActorResult | undefined;
  if (actor?.actor === "agent" && req.accepts("text/markdown")) {
    return res.type("text/markdown").send(renderMarkdown(req.params.page));
  }
  return res.render("doc", { page: req.params.page });
});

challenges, rate limits அல்லது step-up checks போன்ற enforcement, பின்னர்தான் வரும், false positives-ஐ அளந்த பிறகு. actor-aware policies-ஐ rollout செய்வது குறித்த guide அந்த செயல்முறையை விவரிக்கிறது.

எந்த தவறுகளைத் தவிர்க்க வேண்டும்?

user agent-ஐ identity என்று கருதுவது. மாற்ற எளிதான header அதுவே. அதை declaration-ஆகப் பதிவு செய்யவும். AI operators கூட அதையே சொல்கிறார்கள்: Anthropic-ன் அதன் hosted browser agent-க்கான guidance-ல், யாரும் அதே User-Agent header-ஐ அனுப்ப முடியும் என்றும், traffic-ஐ உண்மையானதாகக் கருதுவதற்கு முன் அதன் published IP addresses-ஐச் சரிபார்க்குமாறு பரிந்துரைக்கிறது.
Human-க்கு இயல்பாக மாறுவது. உங்கள் code bot signals-ஐக் காண முடியாதபோதெல்லாம் Human என்று சொன்னால், உங்கள் Human எண்கள் மிகைப்படுத்தப்படும், மேலும் உங்கள் policies தவறான traffic-ஐ நம்பும்.
class மற்றும் basis-ஐ கலப்பது. இரண்டையும் எப்போதும் சேமிக்கவும். "Agent" மட்டும் காட்டும் dashboard, verified operator மற்றும் copied string-க்கிடையிலான வேறுபாட்டை மறைக்கும்.
observation நேரத்தில் block செய்வது. தற்காலிக block கூட உங்கள் measurements-ஐ செல்லாததாக மாற்றும், ஏனெனில் block செய்யப்பட்ட clients தங்கள் நடத்தையை மாற்றிக்கொள்கின்றன.

Proof of Actor எங்கு பொருந்துகிறது

மேலே உள்ள middleware ஒரு உறுதியான தொடக்கப் புள்ளி, மேலும் இது core model-ஐக் காட்டுகிறது: முதலில் evidence, ஒவ்வொரு result-க்கும் தெளிவான basis, Unknown காணக்கூடியதாக வைத்தல், மற்றும் முடிவுகளை உங்கள் application-க்கு விட்டுவிடுதல். Proof of Actor அதே model-ஐ அடிப்படையாகக் கொண்டு, server, edge, browser மற்றும் MCP contexts across deeper signal coverage-உடன், மேலும் நீங்கள் Detect, Understand மற்றும் Route-ஐ நம்பிக்கையுடன் செய்ய உதவும் analytics-உடன் விரிவாக்குகிறது.

ஒரு production app-ல் இதை மேலும் எடுத்துச் செல்ல உதவி வேண்டுமென்றால், early access-க்கு விண்ணப்பிக்கவும். முழு decision flow-ஐப் பார்க்க, How Proof of Actor works-ஐப் படிக்கவும்.

Sources

RFC 9421: HTTP Message Signatures: signed requests-ன் பின்னுள்ள standard
draft-ietf-webbotauth-httpsig-protocol: Signature-Agent header-ஐ வரையறுக்கும் IETF Web Bot Auth draft (November 2026 நிலவரப்படி work in progress)
RFC 9110: HTTP Semantics, User-Agent and From: self-reported client identification headers
MCP specification 2025-11-25: Lifecycle: initialize request மற்றும் clientInfo
MCP specification 2026-07-28: Versioning and Compatibility: per-request version, identity மற்றும் capability metadata
Anthropic: Anthropic-hosted browsers தங்களை எப்படித் தாமே அடையாளப்படுத்துகின்றன: user agent token, published IP addresses மற்றும் header நகலெடுக்கப்படலாம் என்ற எச்சரிக்கை

அதை எங்களுடன் உருவாக்குங்கள்.

Proof of Actor founding developer program-இல் சேருங்கள்.

முன்கூட்டிய அணுகலைப் பெறுக டெவலப்பர் மையம்

முதலில் பேச விரும்புகிறீர்களா? founders-உடன் பேசுங்கள்