নিৰ্দেশিকা

Node.js অ্যাপত actor context কেনেকৈ যোগ কৰিব

প্ৰতি request-ৰ পিছত কোন বা কি আছে সেয়া record কৰা middleware বনাবলৈ এটা step-by-step guide, যাতে আপুনি কিবা enforce কৰাৰ আগতে real traffic অধ্যয়ন কৰিব পাৰে.

দ্বাৰা Toshendra SharmaFounder & CEO, AgentCredia · Updated November 13, 2026

শিক্ষানবিস · 9 min read

Rules-ৰ সলনি actor context-ৰ পৰা কিয় আৰম্ভ কৰিব?

AI agents আপোনাৰ traffic-ত আছে বুলি লক্ষ্য কৰা বেছিভাগ team-এ প্ৰথমে rule-ৰ ফালে হাত মেলে। user agent block কৰক, challenge যোগ কৰক, rate limit টান কৰক। সমস্যাটো হৈছে traffic বুজি নোপোৱাৰ আগতে লিখা rule-এ সাধাৰণতে ভুল মানুহক আঘাত কৰে। Legitimate assistant block হৈ যায়, real user-এ challenge পায়, আৰু আপুনি আসলতে যি automation লৈ চিন্তিত আছিল সেয়া চলিয়েই থাকে, কাৰণ সি প্ৰথমতে নিজকে চিনাকি দিয়া নাছিল।

Actor context হৈছে rule-ৰ আগৰ ধাপ। প্ৰতি request-ৰ বাবে, আপোনাৰ application-এ কিয় বা কি action কৰি আছে সেই বিষয়ে কি observe কৰিব পাৰে সেয়া record কৰে: এটা interactive ব্যক্তি, AI assistant-ৰ সৈতে কাম কৰা ব্যক্তি, এটা autonomous agent, বা এতিয়াও পৃথক কৰিব নোৱাৰা কিবা। সেই view-ৰ পিছৰ evidence record কৰে, আৰু request-ৰ outcome-ৰ কাষতে ৰাখে। এদুদিন বা এসপ্তাহ এইদৰে চলাৰ পাছত আপোনাৰ হাতত এনে এটা map থাকে যি কোনো rule template-এ দিব নোৱাৰে: আপোনাৰ নিজৰ traffic-ৰ map। যদি আপুনি এতিয়াও ভাবি আছে যে agents-এ আপোনাৰ site-ত সত্যতে আহে নে নাহে, তেন্তে website traffic AI agents-ৰ পৰা আহে নে নহয় কেনেকৈ বুজিব-ৰ পৰা আৰম্ভ কৰক।

এই guide-এ plain middleware ব্যৱহাৰ কৰি এটা Node.js application-ত সেই layer গঢ়ি তোলে। ই Express-ৰ সৈতে কাম কৰে, আৰু একে ধাৰণা Fastify, Koa, Hono বা Next.js route handler-লৈও যায়।

আপুনি কি গঢ়িব

শেষত আপোনাৰ হাতত থাকিব:

প্ৰতি request-ৰ actor evidence extract কৰা middleware.
প্ৰতিটো result-ৰ বাবে stated basis থকা এটা সৰু, স্পষ্ট classification.
Structured observation logs যি request কেনেকৈ handle কৰা হৈছে সেয়া কেতিয়াও সলনি নকৰে.
Result-টো request-ত attach কৰাৰ এটা উপায় যাতে পিছৰ handlers-এ তাক read কৰিব পাৰে.

ইয়াত কিবা এটা request block কৰা নহয়। সেয়া ইচ্ছাকৃত।

Step 1: আপোনাৰ server-এ প্ৰকৃততে কি evidence দেখিব পাৰে?

Server-এ মানুহে ধাৰণা কৰা ধৰণতকৈ কম দেখা পায়। Code লিখাৰ আগতে, আপোনাৰ edge-ত উপলভ্য signals-ৰ তালিকা কৰক:

Request signatures. কিছুমান automated client-এ HTTP Message Signatures (RFC 9421) ব্যৱহাৰ কৰি request sign কৰে, আৰু Signature-Input আৰু Signature headers পঠায়, সাধাৰণতে Signature-Agent header-ৰ সৈতে যি operator-ৰ published keys-লৈ ইঙ্গিত কৰে, IETF-ৰ Web Bot Auth protocol draft-ত বৰ্ণনা কৰা মতে.
Declared identity. Client-এ নিজকে User-Agent header-ত, From header-ত, বা protocol metadata-ৰ জৰিয়তে, যেনে MCP client name, নাম দিব পাৰে। MCP client-এ 2025-11-25 revision-ৰ initialize request-ত নিজৰ বাছি লোৱা clientInfo নাম report কৰে, আৰু 2026-07-28 revision-এ client identity-টো per-request metadata হিচাপে কঢ়িয়ায়। এইবোৰ declaration, আৰু যিকোনো এজনে copy কৰিব পাৰে।
Authentication context. Request-টোৱে session cookie, bearer token বা API key কঢ়িয়াইছে নে নাই, আৰু সেয়া কোন ধৰণৰ credential.
Protocol shape. Accept headers, client-এ HTML নে JSON request কৰিছে, সি page assets load কৰে নে নহয়, আৰু redirects আৰু cookies কেনেকৈ handle কৰে.
Application declarations. আপোনাৰ নিজৰ product-এ network-এ নেদেখা কথা জানিব পাৰে, যেনে user-এ "AI assisted" option বাছি লোৱা, বা request আপোনাৰ built-in assistant feature-ৰ পৰা অহা।

প্ৰতিটো signal-ৰ শক্তি বেলেগ। Validated signature check কৰিব পাৰি। User agent string এটা claim. Missing cookie মানে মাথোঁ missing. এইবোৰ পৃথককৈ ৰাখিয়েই এই exercise-ৰ মূল উদ্দেশ্য পূৰণ হয়.

Step 2: Result-টো স্পষ্টভাৱে model কৰক

Detection logic লিখাৰ আগতে actor result-ৰ shape define কৰক। এটা সৰু, typed model-এ সকলোকে classification-টোৱে কি অৰ্থ বহন কৰে সেই বিষয়ে সৎ ৰাখে। ইয়াত ব্যৱহৃত চাৰিটা class Human, AI-assisted or 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;
}

দুটা field আটাইতকৈ গুৰুত্বপূর্ণ। actor হৈছে class. basis-এ আপুনি কিয় সেয়া বিশ্বাস কৰে সেয়া কয়। Validated signature-ৰ ওপৰত ভিত্তি কৰা agent result আৰু user agent string-ৰ ওপৰত ভিত্তি কৰা agent result দুয়োটাই "agent", কিন্তু পিছত সিহঁতৰ treatment বহুত বেলেগ, সেয়েহে কেতিয়াও সিহঁতক একত্ৰ নকৰিব।

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-সম্পৰ্কে কেইটামান কথা:

signaturePresent কেৱল signature headers আছে বুলি record কৰে। Validation এটা পৃথক ধাপ, যি signed agent requests verify কৰাৰ guide-ত covered.
User agent token list ইচ্ছাকৃতভাৱে সৰল। ই verification নহয়, কেৱল declaration সৃষ্টি কৰে.
x-app-assist আপোনাৰ own frontend-এ user-এ built-in AI feature-ৰ মাজেৰে কাম কৰাৰ সময়ত যি পঠায় তাৰ placeholder। ইয়াক আপোনাৰ বাস্তৱ mechanism-ৰে সলনি কৰক.

Step 4: Stated basis-সহ classify কৰক

এতিয়া evidence-ৰ পৰা result বনাওক। Rule-বোৰ সংক্ষিপ্ত ৰাখক, শক্তিশালী 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 assign নকৰে। যেতিয়া সি বুজি নাপায়, তেতিয়া ই Unknown কয়। Unknown এটা বৈধ, উপযোগী উত্তৰ, আৰু ই আপোনাক স্পষ্টকৈ দেখুৱায় visibility ক’ত শেষ হয়। AI traffic-ৰ বাবে Unknown কিয় বৈধ result সেয়া আমি Unknown হৈছে AI traffic-ৰ বাবে বৈধ result কিয়-ত সম্পূৰ্ণকৈ ব্যাখ্যা কৰিছোঁ.

Step 5: Observation mode-ত wire in কৰক

Middleware-টো early 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();
});

তিনিটা detail-এ ইয়াক safe কৰে:

try block-এ detection-ত failure হ’লে response-ত কেতিয়াও প্ৰভাৱ নপৰে বুলি নিশ্চয়তা দিয়ে। Observation must fail open.
Logging finish-ত হয়, সেয়েহে আপুনি real status code capture কৰে আৰু পিছত classification-সমূহক outcome-ৰ সৈতে তুলনা কৰিব পাৰে.
verifySignature-ক real validation implement নকৰালৈ false-লৈ stub কৰা হৈছে। সেয়া signed request-সমূহক declared বা unknown bucket-তে ৰাখে, সিহঁতক অতিমূল্যায়ন নকৰি.

Step 6: কেৱল debugging-ৰ বাবে নহয়, analysis-ৰ বাবে log কৰক

আপুনি aggregate কৰিব পৰা log লিখক। প্ৰতি request-ত এটা structured line যথেষ্ট।

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

এই log-ৰ পৰা personal data আঁতৰাই ৰাখক। আপোনাক route, class, basis, reasons আৰু outcome লাগে। আপোনাৰ traffic mix বুজিবলৈ সম্পূৰ্ণ IP address, raw cookie বা request body-ৰ প্ৰয়োজন নাই। যদি correlation-ৰ বাবে কোনো identifier ৰাখে, rotating salt-ৰ সৈতে hash কৰক আৰু retention period চুটি ৰাখক.

Step 7: Action লোৱাৰ আগতে data পঢ়ক

সাধাৰণ weekly pattern দেখাৰ পৰ্যাপ্ত সময়লৈ observation mode-ত চলাওক। তাৰ পাছত কেইটামান প্ৰশ্নৰ উত্তৰ দিয়ক:

কোন routes-এ agents আকর্ষণ কৰে? Documentation, catalog আৰু search endpoints-এ সাধাৰণতে কৰে। Account আৰু checkout flows-এ সাধাৰণতে কৰা উচিত নহয়.
Agent result-ৰ কিমান অংশ verified আৰু কিমান declared? সেই ratio-এ policies লিখোঁতে identity-ৰ ওপৰত আপুনি কিমান নিৰ্ভয়ে নিৰ্ভৰ কৰিব পাৰে সেয়া কয়.
Unknown ক’ত কেন্দ্ৰীভূত হৈছে? এটা route-ত উচ্চ Unknown rate প্ৰায়ে বুজায় যে আপুনি তাত কোনো signal হেৰুৱাইছে, উদাহৰণস্বৰূপে এটা page যি আপোনাৰ frontend code কেতিয়াও চলায় নহয়.
Class অনুযায়ী outcome বেলেগ নেকি? Error rate, conversion step বা abuse report-সমূহ class-ভেদে তুলনা কৰক। বাস্তৱ policy idea-সমূহ ইয়াতেইৰ পৰা আহে.

উত্তৰবোৰে প্ৰায়ে আচৰিত কৰিব। Teams-এ নিয়মিতভাৱে পায় যে তেওঁলোকৰ "bot problem"-ৰ এটা ডাঙৰ অংশ আসলে legitimate automation, যি structured endpoint থাকিলে আনন্দেৰে ব্যৱহাৰ কৰিলেহেঁতেন.

Step 8: Result-টো আপোনাৰ app-ৰ বাকী অংশলৈ expose কৰক

Data চলিবলৈ আৰম্ভ কৰাৰ পাছত, handlers-এ res.locals.actor non-enforcing ব্যৱহাৰৰ বাবে পঢ়িবলৈ দিয়ক: 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 });
});

Enforcement, যেনে challenges, rate limits বা step-up checks, পাছত আহে, আপুনি false positive measure কৰাৰ পাছত। Actor-aware policies roll out কৰাৰ guide-এ সেই process covered.

আপুনি কি ভুল এড়াই চলা উচিত?

User agent-কে identity বুলি ধৰা। ইয়াক সলনি কৰা আটাইতকৈ সহজ header. ইয়াক declaration হিচাপে record কৰক। AI operators-এও সেয়া কয়: Anthropic-ৰ তাৰ hosted browser agent-ৰ বাবে guidance-এ নোট কৰে যে একেখিনি User-Agent header যিকোনো এজনে পঠাব পাৰে আৰু traffic-টোক genuine বুলি ধৰি লোৱাৰ আগতে তাৰ published IP address-সমূহ check কৰিবলৈ পৰামৰ্শ দিয়ে.
Human-লৈ default কৰা। যদি আপোনাৰ code-এ bot signal বিচাৰি নাপালে সদায় Human কয়, তেন্তে আপোনাৰ Human সংখ্যা inflated হ’ব আৰু আপোনাৰ policy-এ ভুল traffic-ৰ ওপৰত ভৰসা কৰিব.
Class আৰু basis মিশ্ৰণ কৰা। সদায় দুয়োটা store কৰক। কেৱল "Agent" দেখুওৱা dashboard-এ verified operator আৰু copied string-ৰ মাজৰ পাৰ্থক্য লুকুৱায়.
Observation চলি থাকোঁতেই block কৰা। সাময়িক block-এও আপোনাৰ measurement invalid কৰি তোলে, কাৰণ blocked client-এ নিজৰ আচৰণ সলায়.

Proof of Actor ক’ত fit হয়

ওপৰৰ middleware এটা শক্তিশালী আৰম্ভণি, আৰু ই core model দেখুৱায়: প্ৰথমে evidence, প্ৰতিটো result-ৰ বাবে স্পষ্ট basis, Unknown দৃশ্যমান হৈ থাকে, আৰু সিদ্ধান্ত আপোনাৰ application-ৰ ওপৰত এৰি দিয়া হয়। Proof of Actor-এ একে model-ৰ ওপৰত server, edge, browser আৰু MCP context-ত অধিক signal coverage, আৰু এনে analytics-ৰে নিৰ্মাণ কৰে যিয়ে আপোনাক নিশ্চয়তাৰে Detect, Understand আৰু Route কৰিবলৈ সক্ষম কৰে.

যদি আপুনি production app-ত ইয়াক আৰু আগুৱাই নিয়াত সহায় বিচাৰে, early access-ৰ বাবে apply কৰক. সম্পূৰ্ণ decision flow দেখিবলৈ, How Proof of Actor works পঢ়ক.

Sources

RFC 9421: HTTP Message Signatures: signed request-ৰ পিছৰ standard
draft-ietf-webbotauth-httpsig-protocol: Signature-Agent header define কৰা 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 browser-এ নিজকে কেনেকৈ identify কৰে: user agent token, published IP address আৰু header copy কৰিব পৰা যায় বুলি সতৰ্কবাণী

আমাৰ সৈতে ইয়াক নিৰ্মাণ কৰক।

Proof of Actor founding developer program-ত যোগদান কৰক।

Early Access লওক ডেভেলপাৰ হাব

আগতে কথা পাতিবলৈ পচন্দ কৰেনে? Founding team-ৰ সৈতে কথা পাতক