Actor farkındalıklı politikaları güvenli şekilde nasıl devreye alırsınız

Actor farkındalıklı politikaları devreye alırken ne ters gidebilir?

Actor farkındalıklı bir politika, uygulamanızın kimin ya da neyin işlem yaptığına göre nasıl yanıt verdiğini değiştirir. Doğru uygulandığında, insanlara akıcı bir deneyim sunar, meşru agent'ler için yapılandırılmış bir yol sağlar ve yalnızca gerekli yerde sürtünme ekler. Yanlış uygulandığında ise gerçek kullanıcıları dışarıda bırakır, müşterilerinizin bağımlı olduğu entegrasyonları bozar ve kimsenin açıklayamadığı destek talepleri üretir.

Fark çoğu zaman politika mantığında değildir. Fark devreye alma sürecindedir. (Politika modelinin kendisi için bkz. insanlar ve AI agent'leri için uygulama düzeyi politikalar tasarlama.) Bu kılavuz, ekiplerin herhangi bir route için uygulayabileceği aşamalı bir süreci açıklar: gözlemle, önizle, bir dilim için uygula, sonra genişlet. Her aşamanın net bir çıkış ölçütü ve hızlı bir geri dönüş yolu vardır.

Üç mod

Her politikayı, route başına üç moddan birinde çalışıyor olarak düşünün:

• Gözlemle. Sınıflandırmalar kaydedilir. Uygulama, bunlar yokmuş gibi tam olarak davranır.
• Önizle. Politika değerlendirilir ve kararı kaydedilir, ancak uygulanmaz. Neler olacağını görebilirsiniz.
• Uygula. Karar gerçek isteklere uygulanır.

Mod, tüm uygulamaya değil, route ve politika çiftine aittir. Belgelendirme sayfalarınız uygulanırken, checkout hâlâ gözlem modunda olabilir.

1. Adım: Temelinizi bilene kadar gözlemleyin

Her route'u gözlem modunda başlatın. En azından şunları toplayın:

• route ve method,
• actor sınıfı (Human, Human + AI, Agent veya Unknown) ve dayanağı (verified, declared, inferred veya unknown), uygulama trafiği için taksonomimizde tanımlandığı gibi,
• response status ve route için basit bir sonuç işareti, örneğin "account created" veya "search returned results".

Normal haftalık döngüleri ve o dönemde yayımladığınız tüm release'leri kapsayacak kadar uzun süre çalıştırın. Sonra önem verdiğiniz her route için temel değerinizi yazın: sınıf karışımı, Unknown oranı ve sınıf başına sonuç oranı. Bundan sonra gelecek her şeyi bu sayılarla karşılaştıracaksınız.

Çıkış ölçütü: Aday her route için, onu kimin kullandığını ve sonuçların sınıfa göre nasıl değiştiğini açıklayabiliyorsunuz.

2. Adım: Politikayı veri olarak yazın

Politikalar, dağınık if ifadeler yerine veri olarak tutulduğunda gözden geçirmek, test etmek ve geri almak daha kolay olur.

type ActorClass = "human" | "human_ai" | "agent" | "unknown";
type Basis = "verified" | "declared" | "inferred" | "unknown";
type Action = "allow" | "adapt" | "challenge" | "review" | "limit";
type Mode = "observe" | "preview" | "enforce";

interface Rule {
  actor: ActorClass | "*";
  basis?: Basis[];
  action: Action;
}

interface RoutePolicy {
  route: string;
  mode: Mode;
  enforcePercent: number;
  rules: Rule[];
  fallback: Action;
}

export const policies: RoutePolicy[] = [
  {
    route: "GET /api/catalog",
    mode: "preview",
    enforcePercent: 0,
    rules: [
      { actor: "agent", basis: ["verified"], action: "allow" },
      { actor: "agent", basis: ["declared", "inferred"], action: "limit" },
    ],
    fallback: "allow",
  },
];

Her politikanın açık bir fallback vardır. Bu, Unknown sonuçlar, timeout'lar ve hiçbir kuralın kapsamadığı durumlar için kullanılan işlemdir. Bunu bilinçli seçmek, tüm süreçteki en önemli güvenlik kararıdır.

3. Adım: Tek bir yerde değerlendirin

Tek bir değerlendirme işlevi, modlar arasında davranışı tutarlı tutar.

export function decide(policy: RoutePolicy, actor: ActorClass, basis: Basis): Action {
  for (const rule of policy.rules) {
    const actorMatch = rule.actor === "*" || rule.actor === actor;
    const basisMatch = !rule.basis || rule.basis.includes(basis);
    if (actorMatch && basisMatch) return rule.action;
  }
  return policy.fallback;
}

Ardından modu uygulayın:

export function applyPolicy(policy: RoutePolicy, actor: ActorClass, basis: Basis, requestKey: string) {
  const decision = decide(policy, actor, basis);
  const inSlice = bucket(requestKey) < policy.enforcePercent;
  const enforced = policy.mode === "enforce" && inSlice;
  record({ route: policy.route, mode: policy.mode, actor, basis, decision, enforced });
  return enforced ? decision : "allow";
}

function bucket(key: string): number {
  let h = 0;
  for (const c of key) h = (h * 31 + c.charCodeAt(0)) >>> 0;
  return h % 100;
}

Stabil bucket, aynı session veya client'ın uygulanan dilimin içinde ya da dışında kalmasını sağlar, böylece insanlar istekler arasında davranışın değiştiğini görmez.

4. Adım: Uygulamadan önce yanlış pozitifleri nasıl ölçersiniz?

Bir route'u önizleme moduna alın. Artık her istek, alacağı kararı kaydeder. Politikanın doğru olup olmadığını burada öğrenirsiniz.

Yanlış pozitif, politikanın kısıtlayacağı ama aslında izin verilmesi gereken istektir. Bunu yalnızca sınıflandırmalardan ölçemezsiniz, çünkü test ettiğiniz şey zaten sınıflandırmanın kendisidir. Bunu, meşru kullanımın bağımsız sinyalleriyle ölçün:

• istek, oturum açmış bir kullanıcının işini kaydetmesi gibi normal ve başarılı bir akışı tamamladı,
• client bilinen bir partner entegrasyonu veya hizmet vermeyi kabul ettiğiniz doğrulanmış bir operatördür,
• destek talepleri veya kullanıcı raporları etkilenen route'a atıfta bulunur,
• kısıtlanacakmış gibi görünen isteklerin bir örnekleminin elle incelenmesi.

Bir örneklemi elle inceleyin. Politikanın itiraz edeceği yirmi gerçek isteği okumak, fazla geniş bir kuralı bulmanın en hızlı yoludur.

Çıkış ölçütü: Kısıtlanacak gibi görünen trafik, gerçekten kısıtlamak istediğiniz trafik tarafından baskın şekilde oluşturuluyordur ve bulduğunuz her yanlış pozitif kategorisi için bir açıklamanız vardır.

5. Adım: Bir dilim için uygulayın

Route'u küçük bir enforcePercent ile uygulama moduna alın. Dilimi, bir hatanın az sayıda isteği etkileyeceği kadar küçük, bir veya iki gün içinde ölçülebilir bir sinyal üretecek kadar büyük tutun.

Temel değer olarak belirlediğiniz aynı metrikleri izleyin:

• route'ta sınıf başına sonuç oranı,
• hata ve itiraz tamamlama oranları,
• route'tan bahseden destek hacmi,
• gecikme, çünkü değerlendirme isteğin yolunda yer alır.

Uygulanan dilimde Human trafiği için sonuçlar geri kalan kısma göre düşerse, genişletmeden önce durun ve inceleyin.

6. Adım: Kademeli olarak genişletin

Dilim oranını adım adım artırın, örneğin küçük bir paydan çeyreğe, sonra yarıya, sonra tüm trafiğe geçin; her adımda normal bir döngü görecek kadar bekleyin. Önceki aşamalar iyi yapıldıysa genişleme sıkıcıdır. Zaten amaç da budur.

Fallback'leri ve hata davranışını seçme

Kanıt eksik olduğunda veya değerlendirme çalışamadığında ne olacağını önceden belirleyin.

• Fail open, isteğin actor bağlamı yokmuş gibi devam etmesi demektir. Bunu public sayfalar, dokümantasyon ve yalnızca okuma yapan katalog endpoint'leri gibi düşük riskli route'larda kullanın.
• Fail closed, mevcut daha güçlü kontrolünüzün uygulanması demektir; örneğin yeniden kimlik doğrulama veya bir inceleme kuyruğu. Bunu zaten böyle bir kontrole sahip olduğunuz yüksek etkili işlemlerde kullanın.

Bir timeout veya hata, hiçbir zaman Human sonucu üretmemelidir. Eksik kanıt Unknown'dur ve Unknown route'un fallback'ini alır. AI trafiğini sınıflandırırken Unknown'un neden geçerli bir sonuç olduğunu anlatan yazımız bu kuralın neden önemli olduğunu açıklar.

async function actorWithTimeout(evaluate: () => Promise<{ actor: ActorClass; basis: Basis }>) {
  const timeout = new Promise<{ actor: ActorClass; basis: Basis }>((resolve) =>
    setTimeout(() => resolve({ actor: "unknown", basis: "unknown" }), 150),
  );
  return Promise.race([evaluate(), timeout]);
}

Bir politikayı hızlı şekilde nasıl geri alırsınız?

Geri alma bir deploy değil, bir yapılandırma değişikliği olmalıdır. Politikaları ekibinizin hızlıca düzenleyebileceği bir depoda tutun ve şu işlemleri anında yapılabilir hale getirin:

1. Bir route'u yeniden önizleme moduna alın, bu da ölçümü korurken uygulamayı durdurur.
2. enforcePercent değerini sıfıra alın.
3. Diğerlerine dokunmadan tek bir kuralı devre dışı bırakın.

Her politika değişikliğini, kimin yaptığını ve ne zaman yaptığını kaydedin. Sonuçlar değiştiğinde ilk soru her zaman neyin değiştiğidir.

İnsanlar hakkında sonuç doğuran kararlar vermekten kaçının

Actor sınıflandırmaları, bir etkileşim hakkındaki kanıtı açıklar. Bir kişi hakkında hüküm değildir. Çıkarıma dayalı bir sınıfı, birinin istihdamını, kredisini, eğitimini, barınmasını veya temel hizmetlere erişimini etkileyen kararların tek temeli olarak kullanmayın. Bu akışlarda, sonucu belirlemek için değil, örneğin insan incelemesine yönlendirmek için actor bağlamını bir süreç seçmekte kullanın.

Uygulamadan önce iletişim kurun

Otomatik client'ları etkileyen politikalar, bunları işleten kişi ve şirketleri de etkiler. Biraz iletişim çok fazla destek işini önler:

1. Otomatik erişim kurallarınızı yayımlayın. Hangi route'ların açık olduğunu, hangi limitlerin geçerli olduğunu ve client'ların HTTP Message Signatures (RFC 9421) ve IETF Web Bot Auth protokol taslağı kullanarak imzalı isteklerle kendilerini nasıl tanıtabileceklerini belirtin.
2. Partnerleri ve entegratörleri önceden bilgilendirin. Bilinen bir entegrasyon önizleme sırasında kısıtlanmış bir dilime düşerse, uygulamadan önce sahibine ulaşın.
3. Faydalı yanıtlar verin. Bir politika isteği kısıtladığında veya itiraz ettiğinde, 429 Too Many Requests ve Retry-After gibi net bir status code ve dokümantasyonunuza bir bağlantı ile yanıt verin. Problem Details formatındaki makine tarafından okunabilir bir body, otomatik client'lara yapılandırılmış bir gerekçe sağlar. İyi kurulmuş agent'ler, nedenini anladıklarında uyum sağlar.
4. Destek ekibinize kanıtı verin. Engellenen bir istek hakkında bir talep geldiğinde, destek ekibi engineering'e sormadan route'u, sınıfı, dayanağı ve politika kararını bulabilmelidir.

Değişiklikleri duyuran ve açıklayan ekipler, kuralları sessizce değiştiren ekiplere göre çok daha az sürprizle karşılaşır ve uyum sağlayan client'lar zamanla daha kolay tanınır.

Her route için bir kontrol listesi

• Sınıf karışımı, Unknown oranı ve sonuçlar için temel değer kaydedildi.
• Politika, açık bir fallback ile veri olarak yazıldı.
• Önizleme çalıştırıldı, örneklem incelendi, yanlış pozitif kategorileri açıklandı.
• Uygulama küçük bir dilimde başlatıldı ve metrikler izlendi.
• Hata davranışı seçildi: fail open veya fail closed.
• Genişletmeden önce geri alma test edildi.

Proof of Actor burada nereye oturur?

Proof of Actor, bu süreç etrafında tasarlanmıştır. Varsayılan davranış gözlemdir, her sonuç kendi dayanağını taşır ve Route politikaları route route sizin kodunuzda tanımlayıp uygulamanız içindir. Detect, Understand, Route: bu sırayla.

Kendi uygulamanızda ekibimizle bir devreye alma sürecini birlikte yürütmek için erken erişim için başvurun. Karar akışının uçtan uca anlatımı için Proof of Actor nasıl çalışır yazısını okuyun.

Kaynaklar

• RFC 6585: Additional HTTP Status Codes, Section 4: 429 Too Many Requests status code
• RFC 9110: HTTP Semantics, Retry-After: client'lara ne zaman yeniden deneyeceklerini söylemek
• RFC 9457: Problem Details for HTTP APIs: makine tarafından okunabilir hata body'leri
• RFC 9421: HTTP Message Signatures: otomatik client'ların istekleri nasıl imzaladığı
• draft-ietf-webbotauth-httpsig-protocol: imzalı otomatik trafik için IETF Web Bot Auth taslağı (November 2026 itibarıyla çalışma aşamasında)