Du schreibst ein Kochrezept – für einen Menschen. Du würdest schreiben: „Nimm eine Prise Salz, rühre unter, bis die Masse geschmeidig ist.“ Der Mensch weiß, was eine Prise ist, er hat ein Gefühl für Konsistenz. Jetzt schreib dasselbe Rezept für einen perfekten Kochroboter, der jede Zutat exakt dosieren kann und jede Anweisung buchstäblich nimmt. Würdest du immer noch „eine Prise“ sagen? Wohl kaum. Du würdest schreiben: „3,2 Gramm feines Meersalz, mit einem Schneebesen bei 60 U/min für 45 Sekunden einarbeiten.“ Genau diesen grundlegenden Wandel beschreibt Mika Sagindyk, Mitgründer des Entwicklerteams von 2027.dev, in einem Essay über das Design von APIs für KI-Agenten. Seine Kernbotschaft: Die meisten heutigen APIs sind für Menschen optimiert – und damit für Agenten, die Code für uns schreiben, zunehmend ungeeignet.
Die meisten Nutzer einer API greifen heute nicht mehr direkt über eine Benutzeroberfläche darauf zu, sondern über Code, den ein Agent generiert hat. Noch vor zwei Jahren war das anders. Heute, so Sagindyk, haben sich seine eigenen Überzeugungen zum API-Design grundlegend umgekehrt. Er glaubt nicht mehr an komplexe Pakete, lehnt automatische Umwandlungen ab und plädiert für extrem lange, sprechende Variablennamen. Das klingt radikal. Die Argumente sind jedoch nachvollziehbar – vor allem für Entwickler, die mit KI-generiertem Code arbeiten.
Gutes API-Design für Menschen: Ein Rückblick
Traditionelles API-Design, wie man es von Stripe oder Twilio kennt, folgt klaren Prinzipien. Der Entwickler skizziert die minimalen Nutzungsmuster, den Onboarding-Prozess und die zehn häufigsten Anwendungsfälle. Daraus destilliert er einen idealen Code, den der Nutzer schreiben soll – möglichst kurz, meist unter fünfzig Zeilen. Die API ist so gestaltet, dass Erweiterungen intuitiv sind: Wer nur ein Feld von zwanzig braucht, soll die anderen neunzehn erst dann bemerken, wenn die Autovervollständigung sie vorschlägt. Ein hervorragendes SDK erklärt sich selbst, man muss kaum in die Dokumentation schauen. Sagindyk implementierte mit 14 Stripe und Twilio, ohne von Steueroptionen oder ACH zu wissen. Genau das war der Punkt: Die APIs verbargen die Komplexität so gut, dass ein junger Nutzer trotzdem produktiv wurde. Dieses menschenzentrierte Design ist das Gegenteil von dem, was heute für KI-Agenten nötig ist.
Warum Agenten alles anders machen
Der entscheidende Unterschied: Ein KI-Agent wie Claude Code kann in einem einzigen Prompt mehr als 10.000 Tokens verarbeiten. Das bedeutet, er kann die gesamte API-Dokumentation auf einmal lesen – und in Sekunden Tausende Zeilen Code generieren. Für Menschen war die Herausforderung, wenig lesen und trotzdem schnell loslegen zu können. Für Agenten ist die Herausforderung, aus der Überfülle an Informationen exakt das Richtige zu extrahieren. Fehler entstehen, weil Code mehrdeutig ist oder Annahmen über Konventionen gemacht werden. Die Lösung: absolute Klarheit. Jede Codezeile muss genau sagen, was sie tut. Das erreicht man, indem man die vier Prinzipien befolgt, die Sagindyk aufstellt.
1. Defaults sind schädlich
In menschlichen APIs sind Standardwerte ein Segen. Sie erlauben es, schnell etwas zum Laufen zu bringen, ohne jedes Detail zu kennen. Ein Agent dagegen kann die Dokumentation lesen, verstehen, was gute Startwerte sind, und sie explizit setzen. Explicitness ist billig geworden – ein paar zusätzliche Parameter kosten kaum Tokens. Dafür steigt die Lesbarkeit. Wenn ein Agent alle Felder ausfüllt, weiß der menschliche Reviewer später genau, welche Werte verwendet wurden. Andernfalls entstehen Inkonsistenzen: Ein Agent nutzt vielleicht den Default für „timeout“, ein späterer Code ändert ihn, und niemand versteht, warum das Verhalten umspringt. Sagindyk empfiehlt daher, gerade bei wichtigen Feldern keine Defaults zu setzen. Kommentare können helfen, die Priorität zu ordnen, aber die Wahl soll explizit getroffen werden. Wie er sagt: „Die Steuer für das Ausfüllen scheinbar unwichtiger Felder ist verschwunden, aber die Steuer für das Verstehen, was Code tut, ist enorm gestiegen.“
2. Fehler sind willkommen
Viele großartige APIs gleichen menschliche Fehler aus: Sie akzeptieren „true“ und „1“ gleichermaßen, sie wandeln Großbuchstaben in Kleinbuchstaben um. Menschen finden das komfortabel. Für einen Agenten ist es eine Falle. Denn wenn verschiedene Funktionen unterschiedliche Schreibweisen verwenden – mal „True“, mal „on“ – wird der Code undurchschaubar. Stattdessen sollte der Fehlerfall präzise sein. Ein guter Fehlerhinweis teilt dem Agenten genau mit, welchen Wert er erwartet. Das ist eine Chance zur Klärung. In den Daten von Sagindyks Team verursachen Fehler 27 % der Reibung, die Agenten erleben. Ein vager Fehler verwirrt sie; ein präziser Fehler zeigt den korrekten Weg. Natürlich sind leere interne Fehler ohne Hinweis schlecht – aber das spricht gegen schlechte Fehler, nicht gegen Fehler an sich.
3. Explizite Namen statt allgemeiner Bezeichner
Das Feld „name“ ist eine der größten Quellen von Fehlinterpretationen. Sagindyk beobachtet, dass Agenten bei einem Feld namens „name“ je nach Kontext fünf verschiedene Bedeutungen annehmen: Anzeigename, ID, Slug, Titel, Kürzel. Ein menschlicher Reviewer später interpretiert es wieder anders. Die Lösung: Verwende sofort erklärende Namen wie „displayName“, „slug“, „externalId“. Tagebuchkommentare helfen zusätzlich, die genaue Bedeutung zu zementieren. Agenten verstehen solche Namen wirklich – sie stoßen nicht auf Ambiguität, sondern auf eine eindeutige Aufforderung. Das ist der Unterschied zwischen „eine Farbe nehmen“ und „RGB-Hex-Code #A0B1C2 verwenden“.
4. Fakten liefern, nicht Gefühle
Der Wert einer API in der Agenten-Ära liegt darin, dass sie eine Tatsache bereitstellt, die der Agent oder sein menschliches Team nicht selbst replizieren können: eine bezahlte Rechnung, eine gesendete Nachricht, eine provisionierte virtuelle Maschine. Alles andere – Utilities, syntaktischer Zucker – ist weitgehend irrelevant. Es kann durch Dokumentationen und Anleitungen ersetzt werden, die dem Agenten zeigen, wie er die gewünschte Funktionalität selbst baut. Sagindyk ist skeptisch gegenüber SDKs, die mehr tun, als API-Normen in sprachspezifische Muster zu übersetzen – etwa Fehler in stark typisierte TypeScript-Fehler zu verwandeln. Alles darüber hinaus sei überflüssig.
Praktische Umsetzung: Das Beispiel Freestyle
Das Team von 2027.dev betreibt Freestyle, eine Plattform für virtuelle Maschinen, die in 400 Millisekunden provisioniert werden und selbst Docker-in-Docker, verschachtelte Virtualisierung und Full-Memory-Snapshots ermöglichen. Anfangs folgte man dem klassischen menschenzentrierten Ansatz: Man baute ein deklaratives Build-System mit SDK-Utilities, das etwa ein „Bun-Paket“ mitbrachte, das einfach funktionieren sollte. Die Idee: Der Nutzer bekommt Bun, ohne sich um Interna kümmern zu müssen. In der Praxis wurde das System nie konfigurierbar genug, es gab immer mehr Fragen als Antworten, und Agenten missbrauchten die Abstraktionen auf vielfältige Weise. Die Komplexität dieser Abstraktionsschichten wurde zum größten Hindernis beim Onboarding. Man zeigte einen schönen, aber undurchsichtigen Code-Snippet – und die Entwickler verstanden nicht, was wirklich passierte. Also kehrte man alles um. Man entfernte die komplexen SDK-Pakete und Indirektionen und ersetzte sie durch eine einfache Anleitung. Heute sagt der Agent: „Lies die Anleitung, nimm den relevanten Code, passe ihn an deine Projektnormen an, verhalte dich wie gewünscht.“ Das Ergebnis: ein viel saubereres Onboarding und klar verständlicher Code.
Bewertung aktueller Frameworks
Sagindyk ordnet auch populäre Agent-Frameworks und Sandbox-APIs nach ihrer Agentenfreundlichkeit ein. Bei den Agent-Frameworks hebt er Flue Framework als exzellent hervor: Es bietet nur minimale Semantik für das Nötigste, alles ist eine steckbare Funktion, und es tut wenig – aber das klar. Den Vercel AI SDK bewertet er als gut, weil er mit „generateText“ und „streamText“ klare, faktische Funktionen bereitstellt. Mittelmaß bescheinigt er Mastra: Die Workflows und Scheduling seien brauchbar, aber die Sandbox-Semantik sei datenzerstörerisch, weil sie Implementierungen einschränkt. Schlecht schneidet Eve ab: ein monolithisches Skillsystem ohne Programmierbarkeit, das an Next.js aus dem Jahr 2016 erinnert. Bei den Sandbox-APIs sieht er Freestyle als Spitzenreiter – die APIs tun genau, was sie sagen, und verhindern Blähung. E2B zeigt teilweise Zurückhaltung, aber die „sbx.runCode“-Funktion ist mit optionalen Konfigurationen typisch menschzentriert. Daytona baut zu viele nicht konfigurierbare Funktionen wie VNC, Git und Docker direkt ins SDK – das erschwert Agenten die Anpassung.
Was das für die Zukunft bedeutet
Das Design von APIs für KI-Agenten beginnt sich vom Design für menschliche Ingenieure zu trennen. Grundlegende Tugenden wie gute Dokumentation, klare Fehlermeldungen und das Verstehen von Nutzungsmustern bleiben wichtig. Aber vieles, was früher entscheidend war, verliert an Bedeutung: die Anzahl der Codezeilen, Fehler im Onboarding, die zum Lesen benötigte Dokumentation – selbst die Tokens, die ein Agent braucht, um produktiv zu werden, sind nicht mehr der Maßstab. Stattdessen zählt absolute Eindeutigkeit, die Bereitschaft, Fehler als Lerninstrumente zu nutzen, und die Konzentration auf das Wesentliche: die Fakten, die nur diese API liefern kann. APIS für Menschen zu optimieren, wird im Zeitalter der Agenten an Relevanz verlieren. Wer auf Klarheit statt Bequemlichkeit setzt, schafft die Grundlage für die nächste Generation von Software – geschrieben von Maschinen, aber verstanden von Menschen.
Quelle: freestyle.sh
