మీ యాప్‌లో AI ఏజెంట్లకు నిర్మిత మార్గం ఎలా ఇవ్వాలి

AI ఏజెంట్లకు మీ యాప్‌లో వేరే మార్గం ఎందుకు అవసరం?

మీ application కు వచ్చే requests లో పెరుగుతున్న భాగం AI ఏజెంట్ల నుంచే వస్తోంది: ఒక user కోసం documentation తీసుకువచ్చే assistants, product pages చదివే research tools, మీ API ని పిలిచే autonomous workflows. వీటిలో చాలా, మనుషుల కోసం రూపొందించిన interfaces ద్వారా పనిచేస్తాయి. అవి పూర్తి HTML pages ను download చేస్తాయి, layouts ను parse చేస్తాయి, mouse కోసం ఉద్దేశించిన navigation ను అనుసరిస్తాయి, మరియు script-heavy page తాము ఆశించినట్లుగా render కాకపోతే మళ్లీ ప్రయత్నిస్తాయి.

ఇది అందరికీ అసమర్థంగా ఉంటుంది. ఏజెంట్లు శబ్దభరితమైన content ను పొందుతారు మరియు పొరపాట్లు చేస్తారు. ఎవ్వరూ చూడని pages ను render చేయడానికి మీ servers వనరులు ఖర్చు చేస్తాయి. అలాగే ఈ traffic ను అర్థం చేసుకోవడం కష్టం, ఎందుకంటే ఇది విచిత్రంగా ప్రవర్తించే browser లాగా కనిపిస్తుంది. మీ traffic లో దీనిది ఎంత భాగమో ఇంకా ఖచ్చితంగా తెలియకపోతే, website traffic AI agents నుంచే వస్తుందో లేదో ఎలా తెలుసుకోవాలి తో ప్రారంభించండి.

మరింత మంచి విధానం ఏమిటంటే, ఏజెంట్లకు నిర్మిత మార్గం ఇవ్వడం: programs కోసం రూపొందించిన formats లో content మరియు actions, standard places లో discover చేయగలిగే విధంగా, తమను తాము సరిగ్గా గుర్తించే clients కు బహుమతి ఇచ్చే limits తో. second application నిర్మించకుండా ఇది ఎలా చేయాలో ఈ guide చూపిస్తుంది.

దశ 1: ఏజెంట్లు ఏమి చేయగలగాలి అనేది నిర్ణయించండి

Technology కంటే intent తో ప్రారంభించండి. ఇప్పటికే agent traffic కనిపిస్తున్న routes ను చూసి వాటిని సమూహాలుగా విభజించండి:

• Content చదవడం: documentation, product information, pricing pages, help articles, public profiles.
• Data query చేయడం: search, catalog lookups, availability, status.
• Actions చేయడం: user తరఫున ఏదైనా create, update లేదా delete చేయడం.

Reading మరియు querying అనేవి, ఏ well-behaved client‌కైనా తెరిచి ఉండే నిర్మిత మార్గానికి మంచి candidates. Actions కు client తనను తాను ఎలా గుర్తించినా సరే authentication మరియు authorization అవసరం, మరియు అవి sensitive actions ను రక్షించే guide లో కవర్ చేయబడ్డాయి.

దశ 2: machine-friendly formats అందించండి

Content routes కోసం, page chrome లేకుండా అదే సమాచారాన్ని అందించండి. రెండు formats ఎక్కువ అవసరాలను కవర్ చేస్తాయి:

• Markdown - documentation మరియు articles వంటి prose content కోసం, RFC 7763 లో నమోదు చేసిన text/markdown media type తో serve చేయండి. ఇది headings, lists, links మరియు code blocks ను నిలుపుతుంది, మరియు compact గా ఉంటుంది.
• JSON - products, plans లేదా status వంటి structured records కోసం.

content negotiation ను వాడండి, తద్వారా URL ఒకటే ఉంటుంది మరియు client తాను కోరుకున్న format ను అడుగుతుంది:

import express from "express";

const app = express();

app.get("/docs/:slug", async (req, res) => {
  const doc = await loadDoc(req.params.slug);
  if (!doc) return res.status(404).end();

  res.vary("Accept");
  const preferred = req.accepts(["text/html", "text/markdown", "application/json"]);

  if (preferred === "text/markdown") {
    return res.type("text/markdown; charset=utf-8").send(doc.markdown);
  }
  if (preferred === "application/json") {
    return res.json({ title: doc.title, updatedAt: doc.updatedAt, body: doc.markdown });
  }
  return res.render("doc", { doc });
});

ప్రతి representation ను caches వేరుగా నిల్వ చేయాలనే ఉద్దేశంతో Vary: Accept header (RFC 9110 on Vary) పంపండి. చాలామంది teams ఒక స్పష్టమైన alternate URL ను కూడా expose చేస్తారు, ఉదాహరణకు documentation path కు .md జోడించడం, ఎందుకంటే కొంతమంది clients కు negotiation కంటే అది సులభంగా అనిపిస్తుంది. HTML page నుంచి <link rel="alternate" type="text/markdown" href="..."> తో దానిని link చేయండి, అప్పుడు అది discover చేయగలుగుతుంది. ఇలాంటివి Web Linking model ను అనుసరిస్తాయి.

దశ 3: ఏజెంట్లు మీ నిర్మిత మార్గాన్ని ఎలా కనుగొంటారు?

తమకు కనిపించని దాన్ని ఏజెంట్లు ఉపయోగించలేరు. automated clients ఇప్పటికే చూస్తున్న చోట entry points ను ప్రచురించండి:

1. site root వద్ద /llms.txt: మీ site ఏమి అందిస్తుందో, అత్యంత ఉపయోగకరమైన pages మరియు వాటి structured versions కు links తో కూడిన ఒక చిన్న Markdown summary, llms.txt proposal ను అనుసరించి.
2. ఒక API description - ఉదాహరణకు OpenAPI document, మీ developer documentation నుంచీ మరియు /llms.txt నుంచీ linked గా.
3. HTML pages లో Markdown లేదా JSON versions కు pointing చేసే alternate links.
4. Sitemaps protocol నిర్వచించిన format లో, మీ canonical content URLs ను జాబితా చేసే sitemap.

ఒక కనిష్ఠ llms.txt:

# Example App

> Example App helps teams plan projects. This file lists the best entry points for automated clients.

## Docs
- [Getting started](https://example.com/docs/getting-started.md): setup in five steps
- [API reference](https://example.com/openapi.json): OpenAPI description of the public API

## Policies
- [Automated access](https://example.com/docs/automated-access.md): limits and how to sign requests

Automated clients కోసం మీ నియమాలను వివరిస్తున్న ఒక page ను ఉంచండి: ఏ routes తెరిచి ఉన్నాయి, ఏ limits వర్తిస్తాయి, మరియు better treatment పొందడానికి signed requests తో client తనను తాను ఎలా గుర్తించవచ్చు. స్పష్టమైన నియమాలు ఊహాగానాన్ని సహకారంగా మారుస్తాయి.

దశ 4: user agent string ఆధారంగా కాకుండా actor class ఆధారంగా route చేయండి

Structured responses కలిగిన తర్వాత, వాటిని డిఫాల్ట్‌గా ఎవరు పొందాలో నిర్ణయించండి. user agent strings ను ad hoc గా parse చేయడం బదులు actor class మరియు దాని basis ను ఉపయోగించండి. AI operators తమ user agents ను ప్రకటిస్తారు, OpenAI మరియు Anthropic తమ crawlers మరియు fetchers కోసం చేసినట్లే, కానీ string match అనేది ఇంకా కేవలం ఒక declaration మాత్రమే.

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

function preferStructured(actor: ActorClass, basis: Basis, accept: string): boolean {
  if (accept.includes("text/markdown") || accept.includes("application/json")) return true;
  return actor === "agent" && (basis === "verified" || basis === "declared");
}

రెండు సూత్రాలు దీనిని సురక్షితంగా ఉంచుతాయి:

• Explicit requests ఎప్పుడూ గెలుస్తాయి. ఒక client Markdown లేదా JSON అడిగితే, class ఏదైనా కావొచ్చు, దానిని serve చేయండి.
• Defaults ఎప్పుడూ ఏదీ తీసివేయవు. ఒక Human లేదా Unknown visitor కు ఎల్లప్పుడూ full page లభిస్తుంది. Agents కోసం structured default ఎంచుకోవడం format ను మాత్రమే మార్చుతుంది, వారికి చూడటానికి అనుమతి ఉన్న దాన్ని కాదు.

దశ 5: AI ఏజెంట్లకు ఏ rate limits ఇవ్వాలి?

Rate limits అనేవి actor context అత్యంత స్పష్టంగా ఉపయోగపడే చోటు. అందరికీ ఒకే limit బదులు, class మరియు basis యొక్క ప్రతి combination కు సరైన budget ఇవ్వండి:

Limit ను అందుబాటులో ఉన్న అత్యంత స్థిరమైన identifier తో key చేయండి. Verified agents కోసం, అది operator origin మరియు key identifier. ఇతరుల కోసం, credential లేదా network-level key ను వాడండి.

function limitKey(actor: { actor: ActorClass; basis: Basis; operator?: string }, ip: string, apiKey?: string) {
  if (actor.actor === "agent" && actor.basis === "verified" && actor.operator) return `op:${actor.operator}`;
  if (apiKey) return `key:${apiKey}`;
  return `ip:${ip}`;
}

function limitFor(actor: { actor: ActorClass; basis: Basis }): number {
  if (actor.actor === "agent" && actor.basis === "verified") return 600;
  return 120;
}

సంఖ్యలు placeholders. మీరు గమనించిన baseline ఆధారంగా వాటిని సెట్ చేయండి. ఒక client limit మించితే, 429 Too Many Requests ను Retry-After header తో, మరియు మీ automated access page కి link తో తిరిగి పంపండి. బాగా నిర్మితమైన agents back off చేసి దాన్ని చదువుతాయి.

దశ 6: actions ను authorization వెనుక ఉంచండి

Reading కోసం ఉన్న structured path, మీ security model చుట్టూ దారి కాదు. data ను మార్చే ఏ action అయినా ఇంకా అవసరం:

1. మీ application జారీ చేసిన credential తో authentication,
2. ఆ specific action కోసం authorization, మరియు
3. route యొక్క risk tier కోరే అదనపు checks ఏవైనా.

ఒక verified signature మీకు ఏ client పిలుస్తుందో చెబుతుంది. కానీ ఆ client ఒక given user తరఫున పని చేయవచ్చా లేదా అనేది చెప్పదు. ఈ ప్రశ్నలను వేరుగా ఉంచండి. signed AI agent requests ఏమి నిర్ధారిస్తాయి పై మా post ఆ తేడాను వివరిస్తుంది.

దశ 7: ప్రభావాన్ని కొలవండి

Structured path ను మొదట observation mode లో నడపండి, ఆపై compare చేయండి:

• structured formats వాడే agent requests యొక్క వాటా,
• ముందు మరియు తరువాత agent traffic కోసం server cost మరియు latency,
• agent clients కోసం error మరియు retry rates,
• మీరు మీ signing guidance ప్రచురించిన తర్వాత declared నుంచి verified కు మారే automated clients సంఖ్య ఎంత.

ఈ సంఖ్యలు structured path తన పని చేస్తున్నదా, తదుపరి దాన్ని ఎక్కడ విస్తరించాలో చూపుతాయి.

దశ 8: structured path ను version చేసి document చేయండి

Structured path ను public interface గా పరిగణించండి, ఎందుకంటే agents దాని మీద build చేస్తాయి. కొన్ని అలవాట్లు దాన్ని నమ్మదగినదిగా ఉంచుతాయి:

1. URLs ను స్థిరంగా ఉంచండి. ఒక agent కు /docs/getting-started.md ఉందని తెలిసితే, అది పనిచేయడం కొనసాగాలి. Content మారితే, 301 ను 404 కు redirect చేయండి, 404 గా మార్చకుండా.
2. Update times చేర్చండి. JSON responses లో ఒక updatedAt field ను, Markdown పై ఒక Last-Modified header ను ఉంచండి, తద్వారా agents సరైన విధంగా cache చేసి, ఏదైనా మారినప్పుడు మాత్రమే refresh చేయగలుగుతాయి.
3. conditional requests కు మద్దతు ఇవ్వండి. If-None-Match మరియు If-Modified-Since కు 304 Not Modified తో స్పందించండి. మీ content ను poll చేసే agents ప్రతిసారి అన్నింటినీ మళ్లీ download చేయకుండా revalidate చేయగలిగితే చాలా తక్కువ ఖర్చు అవుతుంది.
4. Breaking changes కు version ఇవ్వండి. ఒక JSON shape మారాల్సి వస్తే, కొత్త version path లేదా media type జోడించి, పాతదాన్ని ప్రచురిత కాలం పాటు ఉంచండి.
5. Automated access page కోసం changelog ప్రచురించండి. బాగా ప్రవర్తించే agents operators దాన్ని చదువుతారు, మరియు కొత్త structured routes ను ప్రకటించడానికి అది మీకు ఒక స్థలాన్ని ఇస్తుంది.

app.get("/api/plans", async (req, res) => {
  const plans = await loadPlans();
  const etag = `"${plans.version}"`;
  res.set("ETag", etag);
  res.set("Cache-Control", "public, max-age=300");
  if (req.get("if-none-match") === etag) return res.status(304).end();
  return res.json({ updatedAt: plans.updatedAt, plans: plans.items });
});

ఈ practices మీ own frontend మరియు partner integrations కీ లాభం చేకూరుస్తాయి. స్థిరమైన, cache చేయగల, document చేసిన structured path ఏ program అయినా మీ application తో పని చేయడానికి త్వరలోనే అత్యంత సులభమైన మార్గంగా మారుతుంది.

సాధారణ పొరపాట్లు

• Agents మరియు people కు వేర్వేరు facts ఇవ్వడం. Structured version page లోని అదే సమాచారాన్ని కలిగి ఉండాలి. విభిన్న content, మీ product గురించి assistant ను అడిగే users ను గందరగోళానికి గురిచేస్తుంది.
• Structured path ను దాచడం. అది /llms.txt, మీ API docs లేదా pages నుంచే link చేయబడకపోతే, agents HTML నే scrape చేస్తూనే ఉంటాయి.
• Claims కు reward ఇవ్వడం. ఎక్కువ limits verified clients కు చెందాలి. Copy చేసిన user agent string కు పెద్ద budget రావద్దు.
• Caches ను మర్చిపోవడం. Vary: Accept లేకుండా, ఒక cache browser కు Markdown ను serve చేయవచ్చు.

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

Proof of Actor, agents ను structured content కు route చేయడానికి మరియు fair limits సెట్ చేయడానికి అవసరమైన actor class మరియు basis ను మీకు ఇస్తుంది. ఇది signed, declared మరియు inferred agents ను detect చేస్తుంది, వారు మీ routes ను ఎలా ఉపయోగిస్తున్నారో అర్థం చేసుకోవడంలో సహాయపడుతుంది, మరియు routing decision ను మీ code లోనే వదిలేస్తుంది.

మా team తో మీ own application కోసం ఒక structured path రూపొందించడానికి, early access కోసం apply చేయండి. ప్రత్యేకంగా API మరియు MCP scenarios కోసం, APIs మరియు MCP Servers చూడండి, అలాగే who is calling your MCP server? చదవండి, అక్కడ actor context Model Context Protocol tool calls కు ఎలా వర్తిస్తుందో వివరించాం.

Sources

• RFC 9110: HTTP Semantics: content negotiation (Section 12), Vary (Section 12.5.5), conditional requests (Section 13) మరియు Retry-After (Section 10.2.3)
• RFC 7763: The text/markdown Media Type: Markdown representations ను serve చేయడం
• RFC 8288: Web Linking: typed alternate links
• RFC 6585: Additional HTTP Status Codes, Section 4: 429 Too Many Requests
• llms.txt proposal: /llms.txt file format
• OpenAPI Specification: machine-readable API descriptions
• Sitemaps protocol: sitemap file format
• OpenAI: Overview of OpenAI Crawlers: OpenAI's published user agents and IP ranges
• Anthropic: crawler and fetcher documentation: ClaudeBot, Claude-User and Claude-SearchBot
• Model Context Protocol specification (2026-07-28): November 2026 నాటికి current MCP revision