Die fünfte von PostHogs Agenten-Regeln hat mich einen Rate Limiter gekostet

PostHog hat im April fünf goldene Regeln für agentenfreundliche Produktentwicklung veröffentlicht. Ich habe sie eine Woche nach dem Start eines Produkts gelesen, das für Agenten gebaut ist. Das ist der denkbar schlechteste Zeitpunkt, um sie als Checkliste zu benutzen, und genau der richtige, um sie als Audit zu benutzen.

Vier davon hatte ich befolgt, ohne zu wissen, dass sie Namen haben. Die fünfte hatte ich so gründlich gebrochen, dass die Dokumentation es laut aussprach, und ich hatte es nicht bemerkt.

Die vier, die hielten

Das Produkt ist ein Preisindex für GPU-Miete, LLM-Token und Strom im Großhandel. Es hat kein Konto und keine Anmeldeschranke, und das ist keine Großzügigkeit: ein Index, den niemand in eine Tabelle ziehen kann, ist ein Screenshot.

Agenten dürfen alles, was Nutzer dürfen. Jede Zahl auf der Seite kommt aus einem öffentlichen JSON-Endpunkt, und jede Tabelle hat einen CSV-Export. Es liegt keine Fähigkeit hinter einer Tür nur für Menschen, weil es nie eine Tür gab.

Agenten auf ihrer Abstraktionsebene abholen. PostHogs Antwort darauf ist SQL, und für ein Analyseprodukt stimmt das: der Fragenraum ist offen, also muss die Schnittstelle eine Abfragesprache sein. Ein Preisindex ist das nicht. Sein gesamter Fragenraum sind drei Substantive, Markt, Wert und Zeitraum, und eine Zeile je Wert und Tag. Einem Agenten SQL zu geben wäre mehr Macht, als die Domäne hergibt, und jeder zusätzliche Freiheitsgrad ist eine weitere Art, etwas zu fragen, das die Daten nicht beantworten können.

Allgemeinen Kontext nach vorn ziehen. Dafür sind llms.txt und llms-full.txt da. Sie nennen die Einheiten, den Aktualisierungstakt und das, was die meisten Seiten weglassen: was die Zahlen nicht sagen. Strom sind gemeldete Abschlüsse, wöchentlich veröffentlicht, acht Tage im Rückstand. Fehlende Tage bleiben fehlend.

Vorgezogener Kontext verrottet außerdem schneller als alles andere auf einer Seite, weil nichts darauf zeigt. Im API-Abschnitt stand „all prices are USD per 1M tokens", und das blieb wahr bis zu dem Tag, an dem die GPU-Miete dazukam. Ab da war es eine selbstbewusste, prominente, maschinenlesbare Lüge.

Skills zu schreiben ist Menschenarbeit. Die Fassung davon, die überlebt, ist eine NOTICE-Datei und eine Doku-Seite mit dem, was ein Agent nicht herleiten kann: dass eine Quelle je Instanz statt je GPU angibt, dass ein historischer Datensatz 38.620 von 46.589 Zeilen als reine CPU-Angebote markiert, und dass der Median ohne diesen Filter null ist.

Die fünfte, und die ist die teure

Agenten wie echte Nutzer behandeln.

Ich hatte sie in der Dokumentation wie echte Nutzer behandelt und in der Infrastruktur wie überhaupt niemanden. Die Doku lud Agenten ein, die Endpunkte ohne Schlüssel abzufragen, und sagte mit klaren Worten, es gebe kein nennenswertes Rate Limit.

Es gab überhaupt keins.

Von einem Laptop aus gemessen:

120 Anfragen in 5 Sekunden
120 Antworten mit Status 200
0 abgewiesen

Jede davon öffnete ihre eigene Postgres-Verbindung, auf einem geteilten Server mit max_connections = 100, der außerdem zwei andere Projekte trägt. Kaputt ging nichts, und genau dabei lohnt es sich zu verweilen. Der Fehlerfall von Regel fünf ist kein Ausfall, den man bemerkt. Er ist eine Einladung, die man veröffentlicht hat, eine Rechnung, die noch nicht gekommen ist, und zwei Nachbarn, die mit untergegangen wären.

Die Reparatur hat zwei Schichten, und der Cache ist die wichtigere.

Die Antworten trugen bereits s-maxage=300, und das bewirkte nichts, weil Cloudflare die eigene Antwort eines Workers auf dem Rückweg nicht durch den Cache schickt. Dieselbe URL zweimal abzufragen lieferte beide Male kein cf-cache-status. Sie ausdrücklich abzulegen heißt, dass eine Flut jetzt Worker-Aufrufe zu 0,30 $ pro Million kostet und die Datenbank überhaupt nicht mehr erreicht.

Das Limit liegt bei 600 pro Minute und Client, und bei 60 für den CSV-Export, der die eine große Antwort und die eine unbegrenzte Abfrage ist. Darüber ein 429 mit Retry-After, damit ein Client, der Header liest, zurückweicht statt gegen die Wand zu laufen. Gezählt wird über CF-Connecting-IP, das Cloudflare setzt und der Aufrufer nicht, statt über X-Forwarded-For, mit dem sich eine Flut beliebig viele Zähleimer erfinden könnte.

Zwei Dinge, die keine Regel mir gesagt hätte

Beide tauchten zwischen dem Schreiben der Reparatur und dem Vertrauen darauf auf.

Honos cors() setzt seine Header, bevor es die nächste Middleware aufruft, nicht beim Zurücklaufen. Also trägt die Kopie, die in den Cache geht, die erlaubte Origin, und die frische Response, die bei einem Treffer gebaut wird, verwirft sie. Jeder Cache-Treffer wäre im Browser gescheitert, während curl tadellos weiterlief. Das ist die Sorte Fehler, die einen ganzen Nachmittag Prüfen mit der falschen Methode überlebt.

Und ohne eigenes max-age füllte Cloudflare die Lücke mit der Zonen-Voreinstellung und lieferte max-age=14400 aus. Vier Stunden Browser-Cache auf einem Preis, den die Anwendung nach sechzig Sekunden als veraltet behandelt, und es erschien in genau dem Moment, in dem diese Antworten überhaupt erst zwischengespeichert wurden. Zeigen konnte das nur die Produktion, weil es eine Eigenschaft der Zone ist und nicht des Codes.

Wonach die Regel wirklich fragt

Als Losung gelesen klingt „Agenten wie echte Nutzer behandeln" nach Einfühlung. Als Betriebsanweisung gelesen ist es viel enger und viel nützlicher:

• Echte Nutzer haben ein Limit. Agenten fragen ab, und zwar in Maschinengeschwindigkeit, sobald man ihnen sagt, dass sie dürfen.
• Echte Nutzer bekommen einen Statuscode, mit dem sie etwas anfangen können. 429 mit Retry-After ist der Unterschied zwischen einem Client, der zurückweicht, und einem, der hämmert.
• Echte Nutzer treffen auf einen Cache. Wenn die Plattform eine Antwort nicht für dich ablegt, ist das eigene Ablegen der Unterschied zwischen einer Flut, die Cent kostet, und einer, die deine Datenbank erreicht.
• Echte Nutzer werden über eine Kennung gezählt, die du kontrollierst. Zähle über etwas, das der Aufrufer nicht setzen kann, sonst ist dein Limiter Dekoration.

Nichts davon ist agentenspezifisch. Es ist die gewöhnliche Hygiene einer öffentlichen API, und das ist der Punkt: in dem Moment, in dem deine Dokumentation sagt, ein Agent dürfe dich ohne Schlüssel abfragen, hast du eine öffentliche API, ob du dich dafür entschieden hast oder nicht.

Next

Die vier Regeln, die hielten, haben nichts gekostet, weil das Produkt ohnehin so geschnitten war. Die eine, die brach, kostete einen Limiter, einen Edge-Cache, zwei subtile Fehler und einen Nachmittag. Dieses Verhältnis lohnt sich zu merken, wenn eine Sammlung von Prinzipien sich liest, als wögen alle ihre Punkte gleich viel.

Der nächste Text dieser Reihe nimmt Datadogs Golden Paths für Agenten, die verlangen, dass jeder Lauf Nachweise erzeugt, und hält sie gegen eine Testsuite von mir, die Nachweise erzeugte, während sie nichts ausführte. Über diese Suite habe ich in dem Text über den Bau aus einem Prompt geschrieben.

Wenn du eine Sache mitnimmst: öffne deine eigene Dokumentation und suche einen Satz, der Zugriff gewährt. Dann prüfe, ob das, worauf er Zugriff gewährt, einen Limiter, einen Cache und einen lesenswerten Statuscode hat. Meins hatte den Satz und nichts von den dreien, und es brauchte den Blogpost von jemand anderem, damit ich hinsehe.