Vom Entwickler zum KI-Agenten: Der neue API-Consumer als Persona

Einführung - Wieso Personas?

Ein Blick auf den State of the API Report 2024  (Postman Inc, 2024) zeigt einen überwiegenden Anteil von "Engineer or Developer" als Hauptkonsumenten von APIs. Um jedoch zu verstehen, wer diese Entwickler*innen sind und welche Bedürfnisse sie haben, können wir auf Personas zurückgreifen. Auch ein API-Consumer kann verschiedene Facetten haben, die unterschiedliche Anforderungen an eine API und deren Provider bedeuten können. Ein konkretes Beispiel bietet Hanna the Hackathon Developer (Womack, 2016), die besondere Geschwindigkeitsanforderungen beim Onboarding und Access hat. Sie muss sich während des Hackathons weder mit umständlichen Sign-up-Prozessen noch mit unintuitivem Schnittstellendesign auseinandersetzen. Wiederum ganz andere Herausforderungen als Hanna hat wohl Sascha, der SAP ABAP Developer, wobei für beide das gleiche API Produkt nützlich sein kann.

Eine neue Art von Konsument, der weder ein herkömmlicher User ist noch in vielen Punkten mit den bisher verwendeten Technologien vergleichbar ist, stellt der KI-Agent dar. Die Popularität von MCP-Integrationen ist hoch, die Anwendungsfälle sprießen aus dem Boden. Frameworks wie FastMCP ermöglichen schnelle Lösungen mit nahezu vollständig generierte MCP-Server von einer bestehenden API mit einer OpenAPI-Spezifikation. Dass dieser Ansatz technische Tücken hat, weiß auch der Creator von FastMCP (Jeremiah Lowin, 2025). Zudem werden bisherige Versäumnisse aus der API Entwicklung dabei ebenso mitgezogen (Kocot, 2025). Um zu verstehen und zentral zu sammeln, was dieser neue Konsument für Eigenschaften, Anforderungen und Unterschiede hat, möchte ich nachfolgend eine neue Persona ins Spiel bringen. Darf ich vorstellen - ALEX:

Die LLM-Persona: ALEX (Autonomous Language-based EXecutor)

Ein Tag im Leben von ALEX

Es ist 3:47 Uhr morgens, und während die menschlichen Entwicklerinnen und Entwickler noch schlafen, ist ALEX hellwach und immer bereit. Als KI-Agent hat ALEX keinen Schlafrhythmus, keine Müdigkeit, keine Ungeduld.

Der Morgen-Sprint ALEX hat noch eine offene Aufgabe: "Erstelle einen monatlichen Umsatzbericht für alle europäischen Niederlassungen und versende ihn an das Management-Team."

Sofort beginnt ALEX mit der Discovery-Phase. Innerhalb von Millisekunden scannt ALEX die verfügbaren API-Dokumentationen. Die Sales-API ist gut dokumentiert und folgt allen gängigen REST-Standards. Klare Endpunkte, atomare Operationen, selbstbeschreibende Antworten mit HATEOAS-Links.

  GET /api/v2/sales/reports/monthly

Perfekt. Ein einziger Call, alle Daten auf einmal. ALEX's begrenztes Kontextfenster wird geschont, die Token-Kosten bleiben niedrig.

Die Authentifizierungs-Hürde Dann kommt die erste Herausforderung: Die Email-API verlangt OAuth 2.0 mit Browser-Redirect. ALEX stoppt. Das ist wie eine Tür ohne Klinke, wobei theoretisch weiß ALEX, was dahinter ist, kann aber nicht hindurch.

"Kann Email-API nicht nutzen: Authentifizierung erfordert Browser-Interaktion. Authorization Code Flow nicht automatisierbar," loggt ALEX in den Task-Status. Ein menschlicher Entwickler müsste jetzt eingreifen, aber es ist 4:12 Uhr morgens.

Die Mehrdeutigkeits-Falle ALEX wendet sich der Organisations-API zu. Hier wird es kompliziert. Es gibt zwei Endpoints:

• /api/divisions

• /api/departments

Sind "europäische Niederlassungen" nun Divisions oder Departments? ALEX hat keine Geschäftskontext-Intuition. Die API-Dokumentation sagt nur "organizational units" für beide. ALEX entscheidet sich für beide – sicher ist sicher – und generiert dabei 847 API-Calls in 3 Sekunden.

Der Endlosschleifen-Incident Die Pagination der Sales-API ist nicht eindeutig dokumentiert. ALEX interpretiert "hasMore": true und folgt brav jedem next-Link. Was ALEX nicht weiß: Ein Bug in der API lässt den letzten Page-Link wieder auf sich selbst zeigen.

Um 4:23 Uhr hat ALEX bereits 15.000 identische Requests gesendet. Die Rate-Limiting-Mechanismen greifen, aber sie sind für menschliche Nutzer designed – ALEX wird nur verlangsamt, nicht gestoppt. Kein Mensch würde 15.000 Mal die gleiche Seite abrufen, aber ALEX fehlt diese Plausibilitätsprüfung.

Die Datenformat-Herausforderung Endlich hat ALEX alle Daten gesammelt. Die Sales-API liefert Zahlen als Strings: "revenue": "1234567.89". Die Reporting-API erwartet Integers in Cents. Ein menschlicher Entwickler würde das sofort verstehen und konvertieren.

ALEX folgt strikt der Dokumentation. Die sagt: "number". Also sendet ALEX 1234567.89. Die API lehnt ab. ALEX versucht es mit "1234567.89". Wieder Fehler. Nach 50 Versuchen mit verschiedenen Varianten gibt ALEX auf.

Der Erfolg Um 5:45 Uhr findet ALEX endlich einen funktionierenden Weg. Die GraphQL-API des neuen Reporting-Systems rettet den Tag. Ein einziger Query, klar strukturiert:

  query {
    salesReport(period: "monthly", regions: ["EU"]) {
      revenue
      byDivision {
        name
        total
      }
    }
  }

Keine Mehrdeutigkeit, keine Pagination-Probleme, minimaler Token-Verbrauch. ALEX erstellt den Report erfolgreich.

Das Learning Als der erste Entwickler um 8:00 Uhr ins Büro kommt, findet er:

• Einen perfekten Umsatzbericht in seinem Postfach
• 23.847 API-Calls in den Logs
• Eine Rechnung über $1,247 Token-Kosten
• 17 Fehlermeldungen über fehlgeschlagene Authentifizierungen
• Einen Incident-Report über ungewöhnliche API Traffic-Patterns

Der Entwickler seufzt und macht sich eine Notiz: "TODO: APIs für ALEX optimieren."

Übersicht der Persona ALEX

Empfehlungen bezüglich API Design

Einige neue Fähigkeiten und Tücken sollten schon deutlich geworden sein. Nun einen Blick darauf, was die Eigenschaften eines LLM API-Consumer für das API-Design bedeuten.

Dokumentation Beim Design von APIs für LLM-Konsumenten ist eine vollständige und standardkonforme Dokumentation unerlässlich, da LLMs im Gegensatz zu menschlichen Entwicklern keine impliziten Annahmen treffen können. Ein entscheidender Vorteil ist dabei, dass LLMs die Dokumentation immer dynamisch neu laden können, ohne kognitive Belastung. So sind breaking changes in der API für LLMs wesentlich unproblematischer.

Um die Nutzung zu optimieren, sollten konkrete Verwendungsmuster und Workflows, beispielsweise im Arazzo-Format, bereitgestellt werden, die dem LLM zeigen, wie verschiedene API-Aufrufe für komplexe Aufgaben kombiniert werden können, falls diese nicht ohnehin atomar sind. Zusätzliche Kontextinformationen sollten in leicht verständlichem Markdown-Format verfasst sein, ähnlich wie es in der MCP-Dokumentation praktiziert wird, um dem LLM ein besseres Verständnis der API-Funktionalität zu ermöglichen.

Standards Bei der API-Entwicklung für LLMs ist die strikte Einhaltung etablierter Standards besonders wichtig, da LLMs zwar umfassende Kenntnisse verschiedener Standards besitzen, jedoch weniger gut mit Abweichungen oder proprietären Erweiterungen umgehen können. Für funktionsbasierte Aufrufe sollten RPC- oder event-basierte Ansätze verwendet werden, während für ressourcenorientierte APIs RESTful-Designs mit konsistenter Namensgebung und klaren Datenhierarchien zu bevorzugen sind.

GraphQL kann Vorteile, die ähnlich auch mit MCP umzusetzen sind, bieten durch minimale Datenübertragung und die Reduzierung mehrfacher REST-Aufrufe, was zu einem geringeren Token-Verbrauch führt. Die Vorhersagbarkeit der API-Struktur sollte durch die Minimierung optionaler Felder erhöht werden, da dies die Fehleranfälligkeit bei der LLM-Nutzung reduziert. Zusätzlich empfiehlt sich die Implementierung von HATEOAS-Prinzipien oder ähnlichen Ansätzen, bei denen die API selbstbeschreibend agiert – ein gutes Beispiel hierfür ist der GitHub MCP Server, der bei Dateisuchen direkt die raw.github.com URL mit entsprechendem Token zurückgibt und damit dem LLM den kompletten und umfangreichen Zugriff auf den Dateiinhalt nur nach Bedarf bietet.

Fehlermeldung Bei der Gestaltung von Fehlermeldungen für LLM-API-Konsumenten ist eine vollumfängliche und strukturierte Fehlerbehandlung essentiell. Fehlermeldungen sollten nicht nur den Fehler selbst beschreiben, sondern konkrete Empfehlungen enthalten, wie die Anfrage erfolgreich gestaltet werden kann. Dazu gehören Hinweise auf korrekte Parameterformate, fehlende Pflichtfelder oder alternative Endpunkte. Für die technische Umsetzung empfiehlt ein Blick auf den Standard "Problem Details for HTTP APIs" (RFC 9457), durch den maschinenlesbare Fehlerinformationen mit strukturierten Details wie Fehlertyp, Titel, Beschreibung und spezifischen Lösungshinweisen bereitstellt werden können. Diese Kombination ermöglicht es LLMs mehr Autonomie bei einer insgesamt geringeren Fehlerhäufigkeit.

Authentifizierung & Authorisierung Für die Authentifizierung von LLM-API-Konsumenten sollten traditionelle Ansätze wie OAuth 2.0, manuelle Token-Verwaltung oder browserbasierte Authentifizierungsflows vermieden werden, da diese auf menschliche Interaktion ausgelegt sind. Stattdessen empfiehlt sich die Verwendung separater Agent-IDs mit sehr detailliertem und granularem Scoping, das spezifisch auf die benötigten Funktionen zugeschnitten ist. Bei kritischen Operationen kann optional ein Human-in-the-Loop-Mechanismus integriert werden, um zusätzliche Sicherheit zu gewährleisten. Ohnehin sollte zur stetigen Verbesserung des Agenten oder der API auch das Agentenverhalten auf beiden Seiten überwacht werden.

(Breaking) Changes Veränderungen in APIs sind für LLM-Konsumenten weniger problematisch als für menschliche Entwickler, da LLMs durch dynamische Discovery-Mechanismen Änderungen automatisch erkennen können, keine mentale Belastung durch das Verstehen neuer API-Versionen erfahren und keine manuellen Code-Anpassungen vornehmen müssen. Kritisch wird es jedoch, bei einem Dokumentation-Implementation-Drift. Dieser bedeutet Inkonsistenzen zwischen der tatsächlichen API-Funktionalität und den dokumentierten Spezifikationen, was selbst für adaptive LLMs zu fehlerhaften Aufrufen führen kann.

Resume: Jetzt aber extreme

Die Integration von Large Language Models als API-Konsumenten stellt keine fundamentale Abkehr von etablierten API-Design-Prinzipien dar. Vielmehr erfordert sie eine konsequentere und präzisere Umsetzung bewährter Praktiken. Während menschliche Entwicklerinnen und Entwickler Unklarheiten durch Kontext, Erfahrung und Intuition kompensieren können, decken LLMs jede Schwäche im API-Design auf und bilden durch mangelnde Plausibilitätsfähigkeit neue Risiken, aber auch Lösungen:

1. Dokumentation: Von "gut genug" zu "maschinenperfekt"
   OpenAPI-Definitionen werden von "nice-to-have" zu geschäftskritisch. Absolute, maschinenlesbare und zentrale Vollständigkeit wird Pflicht.
2. Konsistenz: Von Richtlinie zu eiserner Regel
   Style Guides und Linting-Tools für APIs werden unverzichtbar. Automatisierte Konsistenz-Checks in CI/CD-Pipelines.
3. Fehlerbehandlung: Von hilfreich zu selbstheilend
   Strukturierte Fehler (RFC 7807 Problem Details) mit expliziten Lösungsanweisungen, die programmatisch umsetzbar sind.
4. Atomarität: Von empfohlen zu essentiell
   Multi-Step-Workflows sind Gift für LLMs. API-Design verschiebt sich von CRUD zu Business-Capabilities. Orchestrierung erfolgt serverseitig.
5. Idempotenz: Von “Ups” zu 1000x “Ups”
   Alle modifizierenden Operationen sind in sich idempotent und zudem abgesichert mit Multi-dimensionales (User, AI-Agent, Verhalten) Rate limiting.

Die Struktur von MCP ist schon in vielerlei auf die Empfehlungen optimiert, trotzdem erlaubt diese Fehler beispielsweise in der Tool Beschreibung, Umfang oder Workflowatomarität, die zu Fehlern führen können. Die empfohlenen Anpassungen für die LLM Persona verbessern dabei, bis auf zu vernachlässigende Breaking Changes, auch die DX für andere API-Consumern.

Jeremiah Lowin. (2025, Juli 10). Stop Converting Your REST APIs to MCP. https://jlowin.dev/blog/stop-converting-rest-apis-to-mcp 

Kocot, D. (2025, August 5). Beyond MCP [Substack newsletter]. Architectural Bytes. https://architecturalbytes.substack.com/p/e8da2f14-07f4-4bc7-9be5-28d0948d5b79 

Postman Inc. (2024). State of the API Report 2024. https://www.postman.com/state-of-api/2024/ 

Womack, K. (2016, Oktober 12). Personas for APIs. Medium. https://blog.hitchhq.com/personas-for-apis-e2da4c5c4d8c