Wie man actor-bewusste Richtlinien sicher einführt

Was kann schiefgehen, wenn Sie actor-bewusste Richtlinien einführen?

Eine actor-bewusste Richtlinie ändert, wie Ihre Anwendung reagiert, je nachdem, wer oder was handelt. Gut umgesetzt sorgt sie für eine reibungslose Erfahrung für Menschen, gibt legitimen Agenten einen strukturierten Weg und fügt nur dort Reibung hinzu, wo sie nötig ist. Schlecht umgesetzt sperrt sie echte Nutzer aus, bricht Integrationen, auf die Ihre Kunden angewiesen sind, und erzeugt Support-Tickets, die niemand erklären kann.

Der Unterschied liegt selten in der Richtlinienlogik. Er liegt im Rollout. (Zum eigentlichen Richtlinienmodell siehe Richtlinien auf Anwendungsebene für Menschen und AI agents entwerfen.) Dieser Leitfaden beschreibt einen gestuften Prozess, dem Teams für jede Route folgen können: beobachten, prüfen, für einen Teil erzwingen, dann ausweiten. Jede Phase hat ein klares Austrittskriterium und einen schnellen Rückweg.

Die drei Modi

Betrachten Sie jede Richtlinie so, als würde sie pro Route in einem von drei Modi laufen:

• Beobachten. Klassifikationen werden aufgezeichnet. Die Anwendung reagiert genau so, als gäbe es sie nicht.
• Vorschau. Die Richtlinie wird ausgewertet und ihre Entscheidung wird aufgezeichnet, aber nicht angewendet. Sie können sehen, was passiert wäre.
• Erzwingen. Die Entscheidung wird auf echte Requests angewendet.

Der Modus gehört zur Kombination aus Route und Richtlinie, nicht zur gesamten Anwendung. Ihre Dokumentationsseiten können bereits im Erzwingen sein, während Ihr Checkout noch beobachtet wird.

Schritt 1: Beobachten, bis Sie Ihre Basislinie kennen

Starten Sie mit jeder Route im Beobachtungsmodus. Erfassen Sie mindestens:

• die Route und die Methode,
• die Actor-Klasse (Human, Human + AI, Agent oder Unknown) und ihre Grundlage (verified, declared, inferred oder unknown), wie in unserer Taxonomie für Anwendungstraffic definiert,
• den Antwortstatus und einen einfachen Ergebnisindikator für die Route, zum Beispiel "account created" oder "search returned results".

Lassen Sie die Erfassung lange genug laufen, um normale Wochenzyklen und jede Bereitstellung abzudecken, die Sie in diesem Zeitraum ausliefern. Schreiben Sie dann Ihre Basislinie für jede Route auf, die Ihnen wichtig ist: die Klassenverteilung, die Unknown-Rate und die Erfolgsrate pro Klasse. Alles Weitere vergleichen Sie mit diesen Zahlen.

Austrittskriterium: Sie können für jede Kandidatenroute beschreiben, wer sie nutzt und wie sich die Ergebnisse je nach Klasse unterscheiden.

Schritt 2: Schreiben Sie die Richtlinie als Daten

Richtlinien lassen sich leichter prüfen, testen und zurückrollen, wenn sie als Daten vorliegen statt als verstreute if-Anweisungen.

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",
  },
];

Jede Richtlinie hat einen expliziten fallback. Das ist die Aktion für Unknown-Ergebnisse, für Timeouts und für jeden Fall, den keine Regel abdeckt. Ihn bewusst festzulegen ist die wichtigste Sicherheitsentscheidung im gesamten Prozess.

Schritt 3: An einem Ort auswerten

Eine einzige Auswertungsfunktion hält das Verhalten über alle Modi hinweg konsistent.

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

Dann wenden Sie den Modus an:

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

Der stabile Bucket bedeutet, dass dieselbe Sitzung oder derselbe Client im erzwungenen Teil bleibt oder draußen bleibt, sodass Menschen nicht von Request zu Request wechselndes Verhalten sehen.

Schritt 4: Wie messen Sie False Positives vor dem Erzwingen?

Verschieben Sie eine Route in die Vorschau. Jetzt protokolliert jeder Request die Entscheidung, die er erhalten hätte. Hier lernen Sie, ob die Richtlinie richtig ist.

Ein False Positive ist ein Request, den die Richtlinie einschränken würde, der aber hätte zugelassen werden sollen. Das lässt sich nicht allein aus Klassifikationen messen, weil die Klassifikation genau das ist, was Sie testen. Messen Sie gegen unabhängige Signale für legitime Nutzung:

• der Request hat einen normalen erfolgreichen Flow abgeschlossen, zum Beispiel wenn ein angemeldeter Nutzer Arbeit gespeichert hat,
• der Client ist eine bekannte Partner-Integration oder ein verifizierter Operator, den Sie vereinbart haben zu bedienen,
• Support-Tickets oder Nutzerberichte beziehen sich auf die betroffene Route,
• eine manuelle Prüfung einer Stichprobe von Requests, die ansonsten eingeschränkt worden wären.

Prüfen Sie eine Stichprobe von Hand. Zwanzig echte Requests zu lesen, die die Richtlinie herausgefordert hätte, ist der schnellste Weg, eine Regel zu finden, die zu breit ist.

Austrittskriterium: Die Menge der Requests, die ansonsten eingeschränkt worden wären, wird überwiegend von Traffic bestimmt, den Sie tatsächlich einschränken wollen, und Sie haben für jede Kategorie von False Positive, die Sie gefunden haben, eine Erklärung.

Schritt 5: Für einen Teil erzwingen

Stellen Sie die Route mit einem kleinen enforcePercent auf Erzwingen um. Halten Sie den Anteil klein genug, damit ein Fehler nur wenige Requests betrifft, und groß genug, um innerhalb von ein oder zwei Tagen ein messbares Signal zu erzeugen.

Beobachten Sie dieselben Metriken, die Sie als Basislinie festgelegt haben:

• Erfolgsrate pro Klasse auf der Route,
• Fehlerrate und Challenge-Abschlussrate,
• Support-Volumen mit Bezug auf die Route,
• Latenz, da die Auswertung auf dem Request-Pfad liegt.

Wenn die Ergebnisse für Human-Traffic im erzwungenen Teil im Vergleich zum Rest sinken, stoppen Sie und untersuchen Sie die Ursache, bevor Sie ausweiten.

Schritt 6: Schrittweise ausweiten

Erhöhen Sie den Anteil in Stufen, zum Beispiel von einem kleinen Anteil auf ein Viertel, dann auf die Hälfte, dann auf den gesamten Traffic, und halten Sie auf jeder Stufe lange genug an, um einen normalen Zyklus zu sehen. Ausweitung ist langweilig, wenn die vorherigen Phasen gut gelaufen sind. Genau das ist das Ziel.

Fallbacks und Fehlerverhalten festlegen

Entscheiden Sie im Voraus, was passiert, wenn die Evidenz fehlt oder die Auswertung nicht laufen kann.

• Fail open bedeutet, dass der Request so weiterläuft, als gäbe es keinen Actor-Kontext. Verwenden Sie das für risikoarme Routen wie öffentliche Seiten, Dokumentation und schreibgeschützte Katalog-Endpunkte.
• Fail closed bedeutet, dass Ihre bestehende stärkere Prüfung greift, zum Beispiel eine erneute Authentifizierung oder eine Review-Queue. Verwenden Sie das für Aktionen mit hoher Wirkung, bei denen Sie bereits eine solche Prüfung haben.

Lassen Sie niemals zu, dass ein Timeout oder ein Fehler ein Human-Ergebnis erzeugt. Fehlende Evidenz ist Unknown, und Unknown verwendet den Fallback der Route. Unser Beitrag warum Unknown ein gültiges Ergebnis bei der Klassifizierung von AI traffic ist erklärt, warum diese Regel wichtig ist.

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

Wie rollen Sie eine Richtlinie schnell zurück?

Rollback sollte eine Konfigurationsänderung sein, kein Deploy. Halten Sie Richtlinien in einem Speicher, den Ihr Team schnell bearbeiten kann, und machen Sie diese Aktionen sofort wirksam:

1. Setzen Sie eine Route wieder auf Vorschau, wodurch das Erzwingen stoppt, die Messung aber erhalten bleibt.
2. Setzen Sie enforcePercent auf null.
3. Deaktivieren Sie eine einzelne Regel, ohne die anderen anzutasten.

Protokollieren Sie jede Richtlinienänderung mit der Person, die sie vorgenommen hat, und dem Zeitpunkt. Wenn sich Ergebnisse verändern, lautet die erste Frage immer: Was hat sich geändert?

Vermeiden Sie folgenschwere Entscheidungen über Menschen

Actor-Klassifikationen beschreiben Evidenz über eine Interaktion. Sie sind kein Urteil über eine Person. Verwenden Sie eine inferierte Klasse nicht als alleinige Grundlage für Entscheidungen, die Beschäftigung, Kredit, Bildung, Wohnraum oder den Zugang zu wesentlichen Diensten betreffen. Nutzen Sie für solche Abläufe den Actor-Kontext, um einen Prozess zu wählen, etwa die Weiterleitung an eine menschliche Prüfung, statt ein Ergebnis zu bestimmen.

Kommunizieren Sie, bevor Sie erzwingen

Richtlinien, die automatisierte Clients betreffen, betreffen auch die Menschen und Unternehmen, die sie betreiben. Ein wenig Kommunikation spart viel Support-Arbeit:

1. Veröffentlichen Sie Ihre Regeln für automatisierten Zugriff. Legen Sie fest, welche Routen offen sind, welche Grenzen gelten und wie sich Clients mit signierten Requests mithilfe von HTTP Message Signatures (RFC 9421) und dem IETF-Entwurf Web Bot Auth protocol ausweisen können.
2. Informieren Sie Partner und Integratoren im Voraus. Wenn eine bekannte Integration während der Vorschau in einen eingeschränkten Teil fällt, kontaktieren Sie den Eigentümer, bevor Sie erzwingen.
3. Geben Sie hilfreiche Antworten zurück. Wenn eine Richtlinie einen Request einschränkt oder herausfordert, antworten Sie mit einem klaren Statuscode, zum Beispiel 429 Too Many Requests mit Retry-After, und einem Link zu Ihrer Dokumentation. Ein maschinenlesbarer Body im Format Problem Details gibt automatisierten Clients einen strukturierten Grund. Gut gebaute Agenten passen sich an, wenn sie verstehen, warum.
4. Geben Sie Ihrem Support-Team die Evidenz. Wenn ein Ticket zu einem blockierten Request eingeht, sollte der Support Route, Klasse, Grundlage und Richtlinienentscheidung nachschlagen können, ohne Engineering einzubeziehen.

Teams, die Änderungen ankündigen und erklären, erleben deutlich weniger Überraschungen als Teams, die Regeln stillschweigend umschalten, und die Clients, die sich anpassen, werden mit der Zeit leichter erkennbar.

Eine Checkliste für jede Route

• Basislinie für Klassenmix, Unknown-Rate und Ergebnisse erfasst.
• Richtlinie als Daten mit explizitem Fallback geschrieben.
• Vorschau ausgeführt, Stichprobe geprüft, Kategorien von False Positives erklärt.
• Erzwingen auf kleinem Anteil gestartet und Metriken beobachtet.
• Fehlerverhalten gewählt: fail open oder fail closed.
• Rollback vor der Ausweitung getestet.

Wo Proof of Actor hineinpasst

Proof of Actor ist um diesen Prozess herum konzipiert. Beobachtung ist der Standard, jedes Ergebnis trägt seine Grundlage, und Route-Richtlinien definieren und erzwingen Sie in Ihrem eigenen Code, Route für Route. Detect, Understand, Route: in genau dieser Reihenfolge.

Wenn Sie den Rollout in Ihrer eigenen Anwendung gemeinsam mit unserem Team durchgehen möchten, bewerben Sie sich für frühen Zugang. Den End-to-End-Entscheidungsfluss lesen Sie in How Proof of Actor works.

Quellen

• RFC 6585: Additional HTTP Status Codes, Section 4: der Statuscode 429 Too Many Requests
• RFC 9110: HTTP Semantics, Retry-After: Clients mitteilen, wann sie es erneut versuchen sollen
• RFC 9457: Problem Details for HTTP APIs: maschinenlesbare Fehlerkörper
• RFC 9421: HTTP Message Signatures: wie automatisierte Clients Requests signieren
• draft-ietf-webbotauth-httpsig-protocol: IETF-Web-Bot-Auth-Entwurf für signierten automatisierten Traffic (Stand November 2026 in Arbeit)