Wie Sie KI-Agenten einen strukturierten Pfad durch Ihre App geben

Warum brauchen KI-Agenten einen anderen Pfad durch Ihre App?

Ein wachsender Anteil der Anfragen an Ihre Anwendung kommt von KI-Agenten: Assistenten, die Dokumentation für einen Nutzer abrufen, Recherche-Tools, die Produktseiten lesen, autonome Workflows, die Ihre API aufrufen. Die meisten von ihnen arbeiten über Schnittstellen, die für Menschen entworfen wurden. Sie laden vollständige HTML-Seiten herunter, parsen Layouts, folgen einer für die Maus gedachten Navigation und wiederholen Anfragen, wenn eine stark skriptlastige Seite nicht so gerendert wird, wie sie es erwarten.

Das ist für alle ineffizient. Agenten erhalten verrauschte Inhalte und machen Fehler. Ihre Server verbrauchen Ressourcen für das Rendern von Seiten, die niemand anschaut. Und der Verkehr ist schwer einzuordnen, weil er wie ein Browser aussieht, der sich seltsam verhält. Wenn Sie noch nicht sicher sind, wie viel Ihres Traffics das ist, beginnen Sie mit wie man erkennt, ob Website-Traffic von KI-Agenten stammt.

Ein besserer Ansatz ist, Agenten einen strukturierten Pfad zu geben: Inhalte und Aktionen in programmgerechten Formaten, auffindbar an Standardorten, mit Limits, die Clients belohnen, die sich korrekt ausweisen. Dieser Leitfaden zeigt, wie Sie das tun, ohne eine zweite Anwendung zu bauen.

Schritt 1: Entscheiden Sie, was Agenten tun dürfen sollen

Beginnen Sie mit dem Zweck, nicht mit der Technologie. Schauen Sie sich die Routen an, auf denen Sie bereits Agentenverkehr sehen, und gruppieren Sie sie:

• Inhalte lesen: Dokumentation, Produktinformationen, Preisseiten, Hilfeartikel, öffentliche Profile.
• Daten abfragen: Suche, Katalogabfragen, Verfügbarkeit, Status.
• Aktionen ausführen: Etwas im Namen eines Nutzers erstellen, aktualisieren oder löschen.

Lesen und Abfragen sind gute Kandidaten für einen strukturierten Pfad, der für jeden wohlerzogenen Client offen ist. Aktionen brauchen unabhängig davon, wie sich der Client ausweist, Authentifizierung und Autorisierung, und sie werden im Leitfaden zum Schutz sensibler Aktionen behandelt.

Schritt 2: Bieten Sie maschinenfreundliche Formate an

Für Inhaltsrouten bieten Sie dieselben Informationen ohne die Seitenhülle an. Zwei Formate decken die meisten Anforderungen ab:

• Markdown für Prosa wie Dokumentation und Artikel, ausgeliefert mit dem in RFC 7763 registrierten text/markdown Media Type. Es behält Überschriften, Listen, Links und Codeblöcke bei und ist kompakt.
• JSON für strukturierte Datensätze wie Produkte, Pläne oder Status.

Verwenden Sie Content Negotiation, damit die URL gleich bleibt und der Client das gewünschte Format anfordert:

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

Senden Sie einen Vary: Accept Header (RFC 9110 on Vary), damit Caches jede Darstellung getrennt speichern. Viele Teams stellen auch eine explizite Alternativ-URL bereit, zum Beispiel durch Anhängen von .md an einen Dokumentationspfad, weil einige Clients das einfacher finden als Negotiation. Verlinken Sie sie von der HTML-Seite mit <link rel="alternate" type="text/markdown" href="...">, damit sie auffindbar ist. Solche typisierten Links folgen dem Web Linking Modell.

Schritt 3: Wie entdecken Agenten Ihren strukturierten Pfad?

Agenten können nichts nutzen, was sie nicht finden. Veröffentlichen Sie Einstiegspunkte an Orten, die automatisierte Clients ohnehin prüfen:

1. /llms.txt im Wurzelverzeichnis der Website: eine kurze Markdown-Zusammenfassung dessen, was Ihre Seite bietet, mit Links zu den wichtigsten Seiten und ihren strukturierten Versionen, nach dem llms.txt-Vorschlag.
2. Eine API-Beschreibung wie ein OpenAPI Dokument, verlinkt aus Ihrer Entwicklerdokumentation und aus /llms.txt.
3. Alternative Links in HTML-Seiten, die auf Markdown- oder JSON-Versionen verweisen.
4. Eine Sitemap, die Ihre kanonischen Inhalts-URLs auflistet, im vom Sitemaps protocol definierten Format.

Ein minimales 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

Pflegen Sie eine Seite, die Ihre Regeln für automatisierte Clients erklärt: welche Routen offen sind, welche Limits gelten und wie sich ein Client mit signierten Anfragen ausweisen kann, um bevorzugte Behandlung zu erhalten. Klare Regeln verwandeln Rätselraten in Zusammenarbeit.

Schritt 4: Routen Sie nach Akteurklasse, nicht nach User-Agent-String

Sobald Sie strukturierte Antworten haben, entscheiden Sie, wer sie standardmäßig erhält. Verwenden Sie die Akteurklasse und ihre Basis statt User-Agent-Strings ad hoc zu parsen. Betreiber von KI publizieren ihre User-Agents, wie OpenAI und Anthropic es für ihre Crawler und Fetcher tun, aber ein String-Abgleich bleibt nur eine Erklärung.

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

Zwei Prinzipien halten das sicher:

• Explizite Anfragen gewinnen immer. Wenn ein Client Markdown oder JSON anfordert, liefern Sie es aus, unabhängig von der Klasse.
• Standardeinstellungen nehmen nie etwas weg. Ein Human- oder Unknown-Besucher erhält immer die vollständige Seite. Ein strukturierter Standard für Agenten ändert das Format, nicht das, was sie sehen dürfen.

Schritt 5: Welche Ratenlimits sollten KI-Agenten bekommen?

Ratenlimits sind der Punkt, an dem der Akteurkontext am sichtbarsten Wirkung zeigt. Statt eines Limits für alle geben Sie jeder Kombination aus Klasse und Basis ein sinnvolles Budget:

Koppeln Sie das Limit an den stabilsten verfügbaren Bezeichner. Für verifizierte Agenten ist das die Herkunft des Betreibers und der Schlüsselbezeichner. Für andere verwenden Sie die Anmeldeinformation oder einen Schlüssel auf Netzwerkebene.

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

Die Zahlen sind Platzhalter. Legen Sie Ihre auf Grundlage Ihrer beobachteten Basis fest. Wenn ein Client ein Limit überschreitet, geben Sie 429 Too Many Requests mit einem Retry-After Header und einem Link zu Ihrer Seite für automatisierten Zugriff zurück. Gut gebaute Agenten bremsen dann und lesen sie.

Schritt 6: Halten Sie Aktionen hinter Autorisierung

Ein strukturierter Pfad zum Lesen ist kein Umweg um Ihr Sicherheitsmodell. Jede Aktion, die Daten verändert, erfordert weiterhin:

1. Authentifizierung mit einer von Ihrer Anwendung ausgestellten Anmeldeinformation,
2. Autorisierung für genau diese Aktion und
3. alle zusätzlichen Prüfungen, die die Risikoklasse der Route verlangt.

Eine verifizierte Signatur sagt Ihnen, welcher Client aufruft. Sie sagt Ihnen nicht, dass der Client für einen bestimmten Nutzer handeln darf. Trennen Sie diese Fragen. Unser Beitrag zu was signierte Anfragen von KI-Agenten beweisen erklärt den Unterschied.

Schritt 7: Messen Sie die Wirkung

Führen Sie den strukturierten Pfad zuerst im Beobachtungsmodus aus und vergleichen Sie dann:

• den Anteil der Agentenanfragen, die strukturierte Formate nutzen,
• Serverkosten und Latenz für Agentenverkehr vor und nach der Umstellung,
• Fehler- und Wiederholungsraten bei Agenten-Clients,
• wie viele automatisierte Clients von Declared zu Verified wechseln, sobald Sie Ihre Hinweise zum Signieren veröffentlichen.

Diese Zahlen zeigen, ob der strukturierte Pfad seine Aufgabe erfüllt und wo Sie ihn als Nächstes erweitern sollten.

Schritt 8: Versionieren und dokumentieren Sie den strukturierten Pfad

Behandeln Sie den strukturierten Pfad als öffentliche Schnittstelle, denn Agenten werden darauf aufbauen. Einige Gewohnheiten halten ihn zuverlässig:

1. URLs stabil halten. Wenn ein Agent gelernt hat, dass /docs/getting-started.md existiert, sollte es weiter funktionieren. Wenn Inhalte umziehen, geben Sie einen 301 zur neuen Adresse zurück statt eines 404.
2. Aktualisierungszeitpunkte angeben. Setzen Sie ein updatedAt Feld in JSON-Antworten und einen Last-Modified Header bei Markdown, damit Agenten vernünftig cachen und nur aktualisieren, wenn sich etwas geändert hat.
3. Bedingte Anfragen unterstützen. Antworten Sie auf If-None-Match und If-Modified-Since mit 304 Not Modified. Agenten, die Ihre Inhalte pollen, verursachen deutlich geringere Kosten, wenn sie erneut validieren können, statt alles noch einmal herunterzuladen.
4. Breaking Changes versionieren. Wenn sich eine JSON-Struktur ändern muss, fügen Sie einen neuen Versionspfad oder Medientyp hinzu und behalten Sie die alte Version für einen veröffentlichten Zeitraum bei.
5. Einen Changelog für die Seite für automatisierten Zugriff veröffentlichen. Betreiber wohlerzogener Agenten lesen ihn, und er gibt Ihnen einen Ort, um neue strukturierte Routen anzukündigen.

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

Diese Praktiken kommen auch Ihrem eigenen Frontend und Ihren Partner-Integrationen zugute. Ein strukturierter Pfad, der stabil, cachebar und dokumentiert ist, wird schnell zum einfachsten Weg für jedes Programm, mit Ihrer Anwendung zu arbeiten.

Häufige Fehler

• Verschiedene Fakten für Agenten und Menschen ausliefern. Die strukturierte Version sollte dieselben Informationen enthalten wie die Seite. Abweichende Inhalte verwirren Nutzer, die einen Assistenten zu Ihrem Produkt befragen.
• Den strukturierten Pfad verstecken. Wenn er nicht aus /llms.txt, Ihrer API-Dokumentation oder den Seiten selbst verlinkt ist, werden Agenten weiter HTML scrapen.
• Behauptungen belohnen. Höhere Limits gehören verifizierten Clients. Ein kopierter User-Agent-String sollte kein größeres Budget erhalten.
• Caches vergessen. Ohne Vary: Accept kann ein Cache Markdown an einen Browser ausliefern.

Wo Proof of Actor passt

Proof of Actor liefert Ihnen die Akteurklasse und Basis, die Sie brauchen, um Agenten auf strukturierte Inhalte zu routen und faire Limits zu setzen. Es erkennt signierte, deklarierte und inferierte Agenten, hilft Ihnen zu verstehen, wie sie Ihre Routen nutzen, und belässt die Routing-Entscheidung in Ihrem Code.

Um mit unserem Team einen strukturierten Pfad für Ihre eigene Anwendung zu entwerfen, bewerben Sie sich für Early Access. Für API- und MCP-Szenarien siehe APIs und MCP Servers, und lesen Sie wer ruft Ihren MCP server auf? dazu, wie der Akteurkontext bei Tool-Aufrufen des Model Context Protocol wirkt.

Quellen

• RFC 9110: HTTP Semantics: Content Negotiation (Section 12), Vary (Section 12.5.5), Conditional Requests (Section 13) und Retry-After (Section 10.2.3)
• RFC 7763: The text/markdown Media Type: Markdown-Darstellungen ausliefern
• RFC 8288: Web Linking: typisierte alternate Links
• RFC 6585: Additional HTTP Status Codes, Section 4: 429 Too Many Requests
• llms.txt proposal: das /llms.txt Datei-Format
• OpenAPI Specification: maschinenlesbare API-Beschreibungen
• Sitemaps protocol: Sitemap-Dateiformat
• OpenAI: Overview of OpenAI Crawlers: von OpenAI veröffentlichte User-Agents und IP-Bereiche
• Anthropic: crawler and fetcher documentation: ClaudeBot, Claude-User und Claude-SearchBot
• Model Context Protocol specification (2026-07-28): die aktuelle MCP-Revision mit Stand November 2026