AI agentlarına uygulamanız içinde yapılandırılmış bir yol nasıl verilir

AI agentlarının uygulamanız içinde neden farklı bir yola ihtiyacı var?

Uygulamanıza gelen isteklerin giderek artan bir kısmı AI agentlarından geliyor: bir kullanıcı için dokümantasyon getiren asistanlar, ürün sayfalarını okuyan araştırma araçları, API'nizi çağıran otonom iş akışları. Bunların çoğu, insanlar için tasarlanmış arayüzler üzerinden çalışır. Tam HTML sayfalarını indirir, düzeni ayrıştırır, fareye göre tasarlanmış gezinmeyi izler ve script ağırlıklı bir sayfa bekledikleri gibi görüntülenmediğinde yeniden denerler.

Bu herkes için verimsizdir. Agentlar gürültülü içerik alır ve hata yapar. Sunucularınız kimsenin bakmadığı sayfaları oluşturmak için kaynak harcar. Ve trafik, garip davranan bir tarayıcı gibi göründüğü için bunu anlamlandırmak zordur. Trafiğinizin ne kadarının bundan oluştuğundan henüz emin değilseniz, web sitesi trafiğinin AI agentlarından gelip gelmediğini nasıl anlarsınız ile başlayın.

Daha iyi yaklaşım, agentlara yapılandırılmış bir yol vermektir: programlar için oluşturulmuş, standart yerlerden keşfedilebilir, kendini doğru şekilde tanımlayan istemcileri ödüllendiren sınırlarla birlikte içerik ve işlemler. Bu kılavuz, ikinci bir uygulama kurmadan bunu nasıl yapacağınızı gösterir.

Adım 1: Agentların ne yapabilmesi gerektiğine karar verin

Teknolojiyle değil, niyetle başlayın. Zaten agent trafiği gördüğünüz route'lara bakın ve bunları gruplandırın:

• İçeriği oku: dokümantasyon, ürün bilgileri, fiyatlandırma sayfaları, yardım makaleleri, herkese açık profiller.
• Veriyi sorgula: arama, katalog sorguları, kullanılabilirlik, durum.
• İşlem yap: bir kullanıcı adına bir şey oluştur, güncelle veya sil.

Okuma ve sorgulama, iyi davranan her istemciye açık olan yapılandırılmış bir yol için iyi adaylardır. İşlemler ise istemci kendini nasıl tanımlarsa tanımlasın kimlik doğrulama ve yetkilendirme gerektirir ve hassas işlemleri koruma kılavuzunda ele alınır.

Adım 2: Makine dostu formatlar sunun

İçerik route'ları için, sayfa kabuğu olmadan aynı bilgiyi sunun. Çoğu ihtiyacı iki format karşılar:

• Markdown, dokümantasyon ve makaleler gibi düz yazı içeriği için, RFC 7763 içinde kaydedilen text/markdown medya türüyle sunulur. Başlıkları, listeleri, bağlantıları ve kod bloklarını korur ve kompakttır.
• JSON, ürünler, planlar veya durum gibi yapılandırılmış kayıtlar için.

İçerik pazarlaması kullanın, böylece URL aynı kalır ve istemci istediği formatı ister:

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 });
});

Her temsili ayrı ayrı saklayabilmesi için bir Vary: Accept başlığı gönderin (RFC 9110 on Vary). Birçok ekip ayrıca, örneğin bir dokümantasyon yoluna .md ekleyerek açık bir alternatif URL de sunar, çünkü bazı istemciler bunu pazarlık mekanizmasına tercih eder. Bunu HTML sayfasından <link rel="alternate" type="text/markdown" href="..."> ile bağlayın, böylece keşfedilebilir olur. Bu tür adlandırılmış bağlantılar Web Linking modelini izler.

Adım 3: Agentlar yapılandırılmış yolunuzu nasıl keşfeder?

Bulamadıkları şeyi kullanamazlar. Otomatik istemcilerin zaten baktığı yerlere giriş noktaları yayınlayın:

1. Site kökünde /llms.txt: sitenizin sunduğu şeyin kısa bir Markdown özeti, en yararlı sayfalara ve bunların yapılandırılmış sürümlerine bağlantılarla birlikte, llms.txt önerisini izleyerek.
2. Geliştirici dokümantasyonunuzdan ve /llms.txt üzerinden bağlantılanmış bir OpenAPI belgesi gibi bir API açıklaması.
3. HTML sayfalarında Markdown veya JSON sürümlerine işaret eden alternatif bağlantılar.
4. Sitemaps protocol ile tanımlanan biçimde, kanonik içerik URL'lerinizi listeleyen bir site haritası.

Minimum bir 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

Otomatik istemciler için kurallarınızı açıklayan bir sayfa tutun: hangi route'lar açık, hangi sınırlar geçerli ve bir istemci daha iyi muamele görmek için imzalı isteklerle kendini nasıl tanıtabilir. Net kurallar, tahmini işbirliğine dönüştürür.

Adım 4: Kullanıcı ajanı string'ine göre değil, aktör sınıfına göre yönlendirin

Yapılandırılmış yanıtlarınız olduğunda, varsayılan olarak bunları kimin alacağına karar verin. Kullanıcı ajanı string'lerini gelişigüzel ayrıştırmak yerine aktör sınıfını ve dayanağını kullanın. AI operatörleri kendi user agent'larını yayınlar, tıpkı OpenAI ve Anthropic'in tarayıcıları ve getiricileri için yaptığı gibi, ancak bir string eşleşmesi yine de yalnızca bir beyan niteliğindedir.

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");
}

İki ilke bunu güvenli tutar:

• Açık istekler her zaman önceliklidir. Bir istemci Markdown veya JSON istiyorsa, sınıf ne olursa olsun onu sunun.
• Varsayılanlar hiçbir şeyi geri almaz. Bir Human veya Unknown ziyaretçi her zaman tam sayfayı alır. Agentlar için yapılandırılmış bir varsayılan seçmek, onların görebileceği şeyi değil, formatı değiştirir.

Adım 5: AI agentlarına hangi hız sınırları verilmelidir?

Hız sınırları, aktör bağlamının en görünür şekilde karşılığını verdiği yerdir. Herkes için tek bir sınır yerine, her sınıf ve dayanak birleşimine makul bir kota verin:

Sınırı mevcut en kararlı tanımlayıcıya göre belirleyin. Doğrulanmış agentlar için bu, operatör origin'i ve key identifier'dır. Diğerleri için credential veya ağ düzeyinde bir key kullanın.

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;
}

Sayılar yer tutucudur. Sizinkini gözlemlediğiniz taban çizgisine göre belirleyin. Bir istemci sınırı aşarsa, 429 Too Many Requests ile birlikte bir Retry-After başlığı ve otomatik erişim sayfanıza bağlantı döndürün. İyi oluşturulmuş agentlar geri çekilir ve bunu okur.

Adım 6: İşlemleri yetkilendirmenin arkasında tutun

Okuma için yapılandırılmış bir yol, güvenlik modelinizin etrafından dolaşan bir yol değildir. Veriyi değiştiren herhangi bir işlem yine şunları gerektirir:

1. uygulamanızın verdiği bir credential ile kimlik doğrulama,
2. o belirli işlem için yetkilendirme ve
3. route'un risk seviyesinin gerektirdiği ek kontroller.

Doğrulanmış bir imza size hangi istemcinin çağrı yaptığını söyler. Ancak bu, istemcinin belirli bir kullanıcı adına işlem yapabileceğini söylemez. Bu soruları ayrı tutun. İmzalı AI agent isteklerinin neyi kanıtladığını anlatan yazımız farkı açıklar.

Adım 7: Etkiyi ölçün

Yapılandırılmış yolu önce gözlem modunda çalıştırın, ardından şunları karşılaştırın:

• yapılandırılmış formatları kullanan agent isteklerinin oranı,
• agent trafiği için sunucu maliyeti ve gecikme, önce ve sonra,
• agent istemcileri için hata ve yeniden deneme oranları,
• imzalama rehberinizi yayınladıktan sonra declared'dan verified'a geçen otomatik istemci sayısı.

Bu sayılar, yapılandırılmış yolun işini yapıp yapmadığını ve bir sonraki adımda nereye genişletilmesi gerektiğini gösterir.

Adım 8: Yapılandırılmış yolu sürümlendirin ve belgelendirin

Yapılandırılmış yolu kamuya açık bir arayüz olarak ele alın, çünkü agentlar bunun üzerine inşa edecektir. Birkaç alışkanlık onu güvenilir kılar:

1. URL'leri sabit tutun. Bir agent /docs/getting-started.md'in var olduğunu öğrendiyse, çalışmaya devam etmelidir. İçerik taşındığında, yeni konuma bir 301 döndürün, bir 404 değil.
2. Güncelleme zamanlarını ekleyin. JSON yanıtlarına bir updatedAt alanı ve Markdown'a bir Last-Modified başlığı koyun, böylece agentlar makul şekilde önbelleğe alabilir ve yalnızca bir şey değiştiğinde yenileyebilir.
3. Koşullu istekleri destekleyin. 304 Not Modified ile If-None-Match ve If-Modified-Since'ye yanıt verin. İçeriğinizi yoklayan agentlar, her şeyi yeniden indirmek yerine yeniden doğrulayabildiğinde çok daha düşük maliyetle çalışır.
4. Kırıcı değişiklikleri sürümlendirin. JSON yapısı değişmek zorundaysa, yeni bir sürüm yolu veya medya türü ekleyin ve eskisini yayımlanmış bir süre boyunca koruyun.
5. Otomatik erişim sayfası için bir değişiklik günlüğü yayınlayın. İyi davranan agent operatörleri bunu okur ve size yeni yapılandırılmış route'ları duyurmak için bir yer sağlar.

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 });
});

Bu uygulamalar kendi frontend'inize ve iş ortağı entegrasyonlarınıza da fayda sağlar. Kararlı, önbelleğe alınabilir ve belgelenmiş bir yapılandırılmış yol, herhangi bir programın uygulamanızla çalışması için hızla en kolay yol haline gelir.

Yaygın hatalar

• Agentlara ve insanlara farklı gerçekler sunmak. Yapılandırılmış sürüm, sayfa ile aynı bilgileri içermelidir. Farklı içerik, bir asistana ürününüz hakkında soru soran kullanıcıları şaşırtır.
• Yapılandırılmış yolu gizlemek. Eğer /llms.txt'den, API dokümanlarınızdan veya sayfaların kendisinden bağlantılanmıyorsa, agentlar HTML kazımaya devam eder.
• İddiaları ödüllendirmek. Daha yüksek sınırlar doğrulanmış istemcilere aittir. Kopyalanmış bir kullanıcı ajanı string'i daha büyük bir kota kazanmamalıdır.
• Önbellekleri unutmak. Vary: Accept olmadan, bir önbellek Markdown'ı bir tarayıcıya sunabilir.

Proof of Actor burada nereye oturur?

Proof of Actor, agentları yapılandırılmış içeriğe yönlendirmek ve adil sınırlar belirlemek için ihtiyaç duyduğunuz aktör sınıfını ve dayanağını size verir. İmzalı, declared ve inferred agentları tespit eder, route'larınızı nasıl kullandıklarını anlamanıza yardımcı olur ve yönlendirme kararını kodunuzda bırakır.

Kendi uygulamanız için ekibimizle yapılandırılmış bir yol tasarlamak istiyorsanız, erken erişim için başvurun. Özellikle API ve MCP senaryoları için API'ler ve MCP Sunucuları sayfalarına bakın ve MCP server'ınıza kim çağrı yapıyor? yazısını okuyarak aktör bağlamının Model Context Protocol araç çağrılarına nasıl uygulandığını öğrenin.

Kaynaklar

• RFC 9110: HTTP Semantics: içerik pazarlaması (Section 12), Vary (Section 12.5.5), koşullu istekler (Section 13) ve Retry-After (Section 10.2.3)
• RFC 7763: The text/markdown Media Type: Markdown temsillerini sunma
• RFC 8288: Web Linking: türlendirilmiş alternate bağlantıları
• RFC 6585: Additional HTTP Status Codes, Section 4: 429 Too Many Requests
• llms.txt proposal: /llms.txt dosya biçimi
• OpenAPI Specification: makine tarafından okunabilir API açıklamaları
• Sitemaps protocol: site haritası dosya biçimi
• OpenAI: Overview of OpenAI Crawlers: OpenAI'nin yayımlanmış user agent'ları ve IP aralıkları
• Anthropic: crawler and fetcher documentation: ClaudeBot, Claude-User ve Claude-SearchBot
• Model Context Protocol specification (2026-07-28): November 2026 itibarıyla mevcut MCP revizyonu