GUIDE

Node.js యాప్‌కు actor context ఎలా జోడించాలి

ప్రతి request వెనుక ఎవరు లేదా ఏమి ఉందో నమోదు చేసే middleware ను నిర్మించడానికి step-by-step guide, తద్వారా మీరు ఏదైనా enforce చేసే ముందు real traffic ను study చేయవచ్చు.

రచన Toshendra SharmaFounder & CEO, AgentCredia · Updated November 13, 2026

ప్రారంభ స్థాయి · 9 min read

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, లేదా ఇంకా వేరు చేయలేని ఏదో. ఆ view వెనుక ఉన్న evidence ను నమోదు చేస్తారు, మరియు request outcome పక్కనే దాన్ని ఉంచుతారు. ఇది వారం లేదా రెండు చేసిన తర్వాత, ఏ rule template కూడా ఇవ్వలేని ఒక విషయం మీకు ఉంటుంది: మీ own traffic యొక్క map. Agents మీ site కు వస్తున్నారా లేదాని ఇంకా నిర్ణయిస్తున్నట్లయితే, website traffic AI agents నుండి వస్తుందో ఎలా చెప్పాలి తో ప్రారంభించండి.

ఈ guide సాధారణ middleware ఉపయోగించి Node.js application లో ఆ layer ను నిర్మిస్తుంది. ఇది Express తో పనిచేస్తుంది, అలాగే ఇదే ideas Fastify, Koa, Hono లేదా Next.js route handler కు కూడా వర్తిస్తాయి.

మీరు ఏమి నిర్మించబోతున్నారు

చివరికి మీ వద్ద ఇవి ఉంటాయి:

ప్రతి request నుండి actor evidence ను extract చేసే middleware.
ప్రతి result కోసం పేర్కొన్న basis తో కూడిన చిన్న, స్పష్టమైన classification.
request ఎలా handle చేయబడుతుందో ఎప్పుడూ మార్చని structured observation logs.
తరువాతి handlers చదవడానికి result ను request కు attach చేసే విధానం.

ఇక్కడ ఏదీ 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 లో self-chosen clientInfo name ను report చేస్తాయి, మరియు 2026-07-28 revision client identity ను per-request metadata గా carry చేస్తుంది. ఇవి declarations, మరియు ఎవరైనా వాటిని copy చేయగలరు.
Authentication context. Request ఒక session cookie, bearer token లేదా API key ను carry చేస్తుందా, మరియు అది ఏ kind of credential అనేది.
Protocol shape. Accept headers, client HTML లేదా JSON request చేస్తున్నదా, page assets ను load చేస్తున్నదా, మరియు redirects మరియు cookies ను అది ఎలా handle చేస్తున్నదో.
Application declarations. మీ own product network చూడలేని విషయాలను తెలుసుకుని ఉండవచ్చు, ఉదాహరణకు user "AI assisted" option ను ఎంచుకోవడం, లేదా request మీ built-in assistant feature నుండి రావడం.

ప్రతి signal కు వేర్వేరు strength ఉంటుంది. Validated signature check చేయగలది. User agent string ఒక claim. Missing cookie అంటే కేవలం missing. ఇవన్నీ separate గా ఉంచడమే ఈ exercise యొక్క మొత్తం point.

Step 2: Result ను స్పష్టంగా model చేయండి

Detection logic రాయకముందే actor result యొక్క shape ను define చేయండి. ఒక చిన్న, typed model classification అంటే ఏమిటో అందరినీ honest గా ఉంచుతుంది. ఇక్కడ ఉపయోగించిన నాలుగు classes ను Human, AI-assisted లేదా agent: application traffic కోసం practical taxonomy లో వివరించారు.

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 అంటే మీరు ఎందుకు అలా నమ్ముతున్నారో చెబుతుంది. Validated signature పై ఆధారపడిన agent result మరియు user agent string పై ఆధారపడిన agent result రెండూ "agent" అయినా, తరువాత అవి చాలా వేర్వేరు treatment కు అర్హత పొందుతాయి, కాబట్టి వాటిని ఎప్పుడూ collapse చేయవద్దు.

Step 3: Middleware లో evidence ను extract చేయండి

Extraction step 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 గురించి కొన్ని notes:

signaturePresent signature headers ఉన్నాయని మాత్రమే record చేస్తుంది. Validation అనేది వేరే step, signed agent requests ను verify చేయడం పై ఉన్న guide లో covered అయింది.
User agent token list ఉద్దేశపూర్వకంగా simple గా ఉంది. ఇది declaration ను మాత్రమే produce చేస్తుంది, verification ను కాదు.
x-app-assist మీ own frontend user మీ built-in AI feature ద్వారా పనిచేసేటప్పుడు పంపే ఏ mechanism‌కైనా placeholder. దీన్ని మీ real mechanism తో replace చేయండి.

Step 4: Stated basis తో classify చేయండి

ఇప్పుడు evidence ను result గా మార్చండి. Rules ను చిన్నగా, strongest evidence నుండి weakest వరకు order లో ఉంచండి, మరియు ఎప్పుడూ 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 గా upgrade చేయదు. Interactive signal లేని request కు Human ను assign చేయదు. అది చెప్పలేనప్పుడు, Unknown అంటుంది. Unknown చెల్లుబాటు అయ్యే, ఉపయోగకరమైన answer, మరియు visibility ఎక్కడ ముగుస్తుందో ఖచ్చితంగా చెబుతుంది. పూర్తి సందర్భాన్ని AI traffic కోసం Unknown చెల్లుబాటు అయ్యే result ఎందుకు లో వివరిస్తాము.

Step 5: Observation mode లో దాన్ని wire చేయండి

Middleware ను ప్రారంభంలో mount చేయండి, result ను request కు attach చేయండి, మరియు 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();
});

ఈ విధానం safe గా ఉండేలా మూడు details సహాయపడతాయి:

try block detection లో failure వచ్చినా response ను ఎప్పుడూ ప్రభావితం చేయదు అని నిర్ధారిస్తుంది. Observation తప్పనిసరిగా fail open కావాలి.
Logging finish పై జరుగుతుంది, కాబట్టి మీరు నిజమైన status code ను capture చేసి, తరువాత classifications ను outcomes తో compare చేయవచ్చు.
నిజమైన validation implement చేసే వరకు 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 అవసరం లేదు. Correlation కోసం ఏదైనా identifier ను ఉంచితే, దాన్ని rotating salt తో hash చేసి, short retention period ను సెట్ చేయండి.

Step 7: చర్య తీసుకునే ముందు data ను చదవండి

సాధారణ weekly patterns కనిపించేంత వరకు observation mode లో నడపండి. తరువాత కొన్ని ప్రశ్నలకు సమాధానం ఇవ్వండి:

ఏ routes agents ను ఆకర్షిస్తున్నాయి? Documentation, catalog మరియు search endpoints సాధారణంగా ఆకర్షిస్తాయి. Account మరియు checkout flows సాధారణంగా అలా చేయకూడదు.
Agent results లో verified versus declared వాటి వాటా ఎంత? Policies రాసేటప్పుడు identity పై మీరు ఎంతవరకు safe గా rely కావచ్చో ఆ ratio చెబుతుంది.
Unknown ఎక్కడ కేంద్రీకృతమై ఉంది? ఒక route పై high Unknown rate రావడం తరచుగా అక్కడ ఒక signal missing ఉన్నట్లు సూచిస్తుంది, ఉదాహరణకు మీ frontend code ఎప్పుడూ run కాని page.
Class ప్రకారం outcomes భిన్నంగా ఉన్నాయా? Classes across error rates, conversion steps లేదా abuse reports ను compare చేయండి. ఇక్కడినుంచే నిజమైన policy ideas వస్తాయి.

సమాధానాలు తరచుగా ఆశ్చర్యపరుస్తాయి. Teams సాధారణంగా తమ "bot problem" లో పెద్ద భాగం వాస్తవానికి చట్టబద్ధమైన automation అని, అది ఉన్నట్లయితే structured endpoint ను సంతోషంగా ఉపయోగించేదని కనుగొంటాయి.

Step 8: ఫలితాన్ని మీ app మిగతా భాగానికి expose చేయండి

Data ప్రవహించడం ప్రారంభమైన తరువాత, non-enforcing ఉపయోగాల కోసం handlers ను res.locals.actor చదవనివ్వండి: analytics tags, response format ఎంచుకోవడం, లేదా ఒక support ticket AI-assisted session నుండి వచ్చిందని record చేయడం. ఈ ఉపయోగాలు ఎవరినీ lock out చేయకుండా experience ను మెరుగుపరుస్తాయి.

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 ను మీరు measure చేసిన తరువాత. actor-aware policies ను rollout చేయడం పై guide ఆ ప్రక్రియను కవర్ చేస్తుంది.

ఏ తప్పులను నివారించాలి?

User agent ను identity గా treat చేయడం. అది మార్చడానికి అత్యంత సులభమైన header. దాన్ని declaration గా record చేయండి. AI operators కూడా ఇదే అంటారు: Anthropic యొక్క దాని hosted browser agent కోసం guidance లో ఎవరైనా అదే User-Agent header పంపగలరని, మరియు traffic ను genuine గా treat చేసే ముందు దాని published IP addresses ను check చేయాలని సూచిస్తుంది.
Default గా Human కు వెళ్లడం. మీ code bot signals కనుగొననిప్పుడు ఎప్పుడూ Human అని చెబితే, మీ Human numbers inflated అవుతాయి, మరియు మీ policies తప్పు traffic ను నమ్ముతాయి.
Class మరియు basis ను కలపడం. రెండింటినీ ఎప్పుడూ store చేయండి. కేవలం "Agent" మాత్రమే చూపించే dashboard, verified operator మరియు copied string మధ్య తేడాను దాచేస్తుంది.
Observation సమయంలో block చేయడం. తాత్కాలిక block కూడా మీ measurements ను invalid చేస్తుంది, ఎందుకంటే blocked clients తమ behavior ను మార్చుకుంటాయి.

Proof of Actor ఎక్కడ సరిపోతుంది

పై middleware ఒక solid starting point, మరియు ఇది core model ను చూపిస్తుంది: ముందు evidence, ప్రతి result కోసం explicit basis, Unknown visible గా ఉంచడం, మరియు decisions ను మీ application కు వదిలేయడం. Proof of Actor ఇదే model పై ఆధారపడి server, edge, browser మరియు MCP contexts అంతటా deeper signal coverage ను, అలాగే మీరు Detect, Understand మరియు Route ను confidence తో చేయడానికి సహాయపడే analytics ను అందిస్తుంది.

Production app పై దీనిని మరింత ముందుకు తీసుకెళ్లడంలో సహాయం కావాలంటే, early access కోసం apply చేయండి. పూర్తి decision flow చూడటానికి, Proof of Actor ఎలా పనిచేస్తుంది ను చదవండి.

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 ను copy చేయవచ్చని హెచ్చరిక

మాతో కలిసి నిర్మించండి.

Proof of Actor founding developer program లో చేరండి.

తొందరగా యాక్సెస్ పొందండి developer hub

ముందుగా మాట్లాడాలనుకుంటున్నారా? foundersతో మాట్లాడండి