KI-Agenten sollen unsere APIs nutzen – aber warum scheinen sie dabei so oft zu scheitern oder ineffizient zu arbeiten? Die Antwort liegt nicht in der Intelligenz der Modelle, sondern in einem fundamentalen Mismatch: APIs werden zwar für Maschinen und Systeme entworfen, jedoch so, dass Menschen sie verstehen und integrieren können – nicht jedoch unbedingt auch Maschinen mit begrenztem Context Window (oder „Auffassungsgabe“). In diesem Artikel zeige ich dir, warum das ein Problem ist.
Zwei Perspektiven, ein Problem
In Diskussionen über KI-Integration tauchen immer wieder zwei scheinbar widersprüchliche Standpunkte auf. Um sie aber zu verstehen, müssen wir zunächst näher betrachten, worum es überhaupt geht:
Der Kontext: API-Operationen und Tools für KI-Systeme
Du hast eine REST-API mit ihren Operationen – einzelne Endpunkte wie GET /stations, POST /bookings oder DELETE /bookings/{id} wie in der Train Travel API. Jede Operation macht etwas Spezifisches: eine Ressource lesen, erstellen, aktualisieren oder löschen.
Auf der anderen Seite hast du KI-Systeme oder Agenten, die Aufgaben für dich erledigen sollen. Damit sie mit deiner API interagieren können, brauchen sie Tools – Funktionen, die sie aufrufen können. Im Model Context Protocol (MCP) heißen diese „Tools“, in anderen Frameworks auch „Functions" oder „Actions". Vereinfacht gesagt: Ein Tool ist das, was einer KI ermöglicht, etwas zu tun.
Die zentrale Frage lautet also: Wie verbindest du diese beiden Welten? Wie machst du aus API-Operationen KI-Tools? Und genau bei dieser Frage treten die beiden scheinbar widersprüchlichen Sichtweisen in Erscheinung.
Perspektive 1: „1:1-Mapping funktioniert nicht“
Es wird betont, wie wichtig es ist, API-Operationen nicht einfach 1:1 als MCP-Tools zu exponieren. Wenn du für jede API-Operation ein separates Tool erstellst, führt das zu schlechterer Performance und verwirrt die Agenten. Ein Agent bekommt dann 50 Tools präsentiert und müsste selbst herausfinden, wie er sie kombiniert, um etwas Sinnvolles (Wertstiftendes) zu erreichen.
In jedem Fall sind aussagekräftige API-Beschreibungen die Grundlage für abgeleitete Tools. In genau diesem Zusammenhang kommt die Frage hinter der zweiten Sichtweise ins Spiel.
Perspektive 2: „Warum nicht einfach die API direkt nutzen?“
Warum benötigt man denn überhaupt dedizierte MCP-Server und Tool-Abstraktionen, wenn man doch bereits eine gut dokumentierte API-Spezifikation hat? Könnte die KI nicht einfach direkt die vorhandenen API-Operationen nutzen? Oder man generiert die Tools automatisch aus der OpenAPI-Definition?
Diese Perspektive zielt also genau darauf ab, API-Operationen direkt und 1:1 auf KI-Tools zu mappen und damit eben jenen Ansatz zu verfolgen, den die andere Perspektive als nachteilig ansieht.
Der scheinbare Widerspruch
Die beiden Perspektiven scheinen sich also zu widersprechen – tun sie aber nicht. Sie beleuchten nur unterschiedliche Aspekte desselben zugrunde liegenden Problems.
Der Knackpunkt liegt tiefer: Cognitive Load bei KI-Agenten. Klassische REST-APIs sind für menschliche Entwickler*innen designt – sie sind ressourcenorientiert (/stations, /trips, /bookings) und bieten flexible, wiederverwendbare CRUD-Operationen.
Das ist für Menschen perfekt: Wir lesen Dokumentation, bauen mentale Modelle auf und verstehen intuitiv, dass „Zugfahrt buchen“ in der Train Travel API bedeutet: erst Bahnhöfe suchen (GET /stations), dann Verbindungen finden (GET /trips), dann buchen (POST /bookings).
Für KI-Agenten ist das eine massive kognitive Belastung. Sie haben kein persistentes mentales Modell, kein „Verständnis“ der Domäne und ein stark begrenztes Context Window. Jede API-Operation kostet wertvolle Tokens. Jede Entscheidung, welche Operation als Nächstes auszuführen ist, ist eine potenzielle Fehlerquelle.
Was ist Cognitive Load bei KI-Agenten?
Large Language Models (LLMs) haben ein fundamentales Problem: ein begrenztes Context Window. Jede Information, die du einem LLM gibst, kostet Tokens. Und je mehr Tokens, desto schlechter wird die Performance.
Das ist nicht nur eine theoretische Grenze. Forschung von Liu et al. (2024) zeigt das „Lost in the Middle“-Problem: LLMs können Informationen am Anfang und Ende eines langen Kontexts zuverlässig abrufen, aber die Performance degradiert signifikant, wenn relevante Informationen in der Mitte liegen müssen. Das ist wie bei uns Menschen – wir erinnern uns an den Anfang und das Ende einer langen Liste besser als an die Mitte (Primacy-Recency-Effekt).
Noch problematischer: Je mehr Informationen im Context Window, desto größer das Risiko von Context Rot – die Fähigkeit des Modells, Informationen korrekt abzurufen, nimmt ab.
Praktische Auswirkungen für Tool Calling:
- Jede Tool-Beschreibung kostet wertvolle Tokens.
- Zu viele Tools = schlechtere Entscheidungen des Agents
- Zu wenig Beschreibung = falsche Tool-Nutzung
- Den Sweet Spot zu finden, ist schwierig.
Das Problem mit REST-APIs: Train Travel API als Beispiel
Schauen wir uns die Train Travel API an – eine bewusst als Best-Practice-Beispiel entwickelte OpenAPI-Definition, die den klassischen Pet Store ablösen soll:
1paths:
2 /stations:
3 get:
4 summary: Get a list of train stations
5 operationId: get-stations
6 parameters:
7 - name: search
8 in: query
9 description: Search term to filter stations
10 schema:
11 type: string
12 - name: country
13 in: query
14 description: Filter stations by country code
15 schema:
16 type: string
17 /trips:
18 get:
19 summary: Get available train trips
20 operationId: get-trips
21 parameters:
22 - name: origin
23 in: query
24 required: true
25 description: The ID of the origin station
26 schema:
27 type: string
28 format: uuid
29 - name: destination
30 in: query
31 required: true
32 description: The ID of the destination station
33 schema:
34 type: string
35 format: uuid
36 - name: date
37 in: query
38 required: true
39 description: The date and time of the trip
40 schema:
41 type: string
42 format: date-time
43 /bookings:
44 get:
45 summary: List existing bookings
46 operationId: get-bookings
47 post:
48 summary: Create a booking
49 operationId: create-booking
50 /bookings/{bookingId}:
51 get:
52 summary: Get a booking
53 operationId: get-booking
54 delete:
55 summary: Delete a booking
56 operationId: delete-booking
57 /bookings/{bookingId}/payment:
58 post:
59 summary: Pay for a Booking
60 operationId: create-booking-paymentWas ist das Problem?
Die API ist ressourcenorientiert: /stations, /trips, /bookings, /payments.
Für menschliche Entwickler*innen, die Dokumentationen lesen und mentale Modelle von Entitäten aufbauen können, ist das völlig okay. Aber ein KI-Agent sieht nur isolierte Operationen ohne Business-Kontext.
Das führt zur häufigen Frage:
„Warum nicht einfach alle Operationen als Tools exponieren?“
Die Antwort liegt in den unterschiedlichen Design-Prinzipien:
Klassische APIs (Resource-First) sind für Menschen designed:
- Orientierung an Entitäten:
/stations,/trips,/bookings - CRUD-Operationen ohne expliziten Business-Kontext
- Annahme: Entwickelnde lesen Dokumentationen und verstehen Zusammenhänge
- Flexibel und wiederverwendbar
- Menschen haben unbegrenztes „Context Window" (Gehirn + Notizen + IDE + Erfahrung)
KI-Agenten brauchen Use-Case-First:
- Orientierung an konkreten Problemen:
book_train_trip,cancel_booking - Business Value ist explizit in der Beschreibung.
- Annahme: Agent muss aus Beschreibung allein verstehen, wann er das Tool nutzen soll.
- Fokussiert auf spezifische Workflows
- KI-Agenten haben begrenztes Context Window und keine persistenten mentalen Modelle.
Die konkrete Herausforderung
Wenn ein User sagt „Ich möchte einen Zug von Chemnitz nach Paris buchen“, muss der Agent:
- Verstehen, dass er mehrere API-Calls orchestrieren muss
- Die richtige Reihenfolge und Abhängigkeiten zwischen den Calls ableiten:
- Erst Bahnhöfe in Chemnitz finden (
GET /stations?search=Chemnitz) - Dann Bahnhöfe in Paris finden (
GET /stations?search=Paris) - Die IDs aus beiden Responses extrahieren
- Verfügbare Verbindungen suchen (
GET /trips?origin={chemnitz_id}&destination={paris_id}&date=2024-02-01) - Eine Buchung für den gewählten Trip erstellen (
POST /bookings) - Die Zahlung für die Buchung durchführen (
POST /bookings/{booking_id}/payment)
- Erst Bahnhöfe in Chemnitz finden (
- Aus technischen Operationen den Business-Intent rekonstruieren
Das ist massive kognitive Arbeit – und genau hier liegt der Knackpunkt.
Das Missverständnis: Ist Flexibilität nicht gut?
An dieser Stelle kann jetzt diese Frage aufkommen:
„Aber wenn ich dem LLM viele einzelne Operationen gebe, hat es doch mehr Flexibilität und kann sich an verschiedene Situationen anpassen. Ist das nicht besser als starre, vordefinierte Tools?“
Die kurze Antwort: „Nein.“
Hier liegt ein fundamentales Missverständnis darüber vor, wie LLMs arbeiten und was sie leisten können. Lass uns das näher betrachten:
Szenario 1: Viele einzelne API-Operationen als Tools
Der Agent bekommt 50 Tools für einzelne API-Operationen. Bei der Anfrage „Buche eine Zugfahrt von Chemnitz nach Paris“ muss das LLM:
- Aus vielen Optionen die richtigen Operationen identifizieren
- Die korrekte Reihenfolge ableiten
- Dependencies zwischen den Calls verstehen
- Fehlerbehandlung selbst implementieren
- Bei jedem Schritt neu entscheiden, was als Nächstes kommt
Allerdings arbeiten LLMs basierend auf Wahrscheinlichkeiten und nicht deterministisch. Es kann also sein, dass ein KI-System die „richtigen“ Entscheidungen trifft und den „richtigen“ Weg wählt, bei nächster Gelegenheit jedoch völlig anders entscheidet. Was passiert also in der Realität?
- Der Agent wählt die falsche Operation.
- Die Reihenfolge ist nicht optimal.
- Fehler werden nicht behandelt.
- Der Workflow bricht mittendrin ab.
Der Ablauf ist nicht reproduzierbar – bei gleicher Anfrage können damit auch unterschiedliche Ergebnisse herauskommen.
Szenario 2: Ein use-case-orientiertes Tool book_train_trip
Der Agent bekommt ein Tool, das intern 5–7 API-Calls mit deterministischer Logik orchestriert. Bei der Anfrage „Buche Zugfahrt“ muss das LLM nur:
- Entscheiden: „Passt
book_train_tripzur Anfrage?“ (Ja/Nein) - Die richtigen Parameter bestimmen (Start, Ziel, etc.)
Hier ist also nicht mehr der Weg zum Ziel den Wahrscheinlichkeiten unterworfen, sondern lediglich die konkrete Ausgestaltung des Ziels. Das heißt:
- Die Implementierung wurde getestet und funktioniert zuverlässig.
- Fehlerbehandlung ist zentral implementiert.
Das LLM konzentriert sich auf die Business-Entscheidung, nicht auf technische Details. Damit ist der Ablauf reproduzierbar – eine gleiche Eingabe führt auch zum gleichen Ergebnis.
Die Kernbotschaft: Verschiebe Komplexität aus dem probabilistischen LLM in deterministischen Code
Die Komplexität verschwindet nicht – sie wandert nur dorthin, wo sie hingehört:
- Deterministische Logik (in der Tool-Implementierung): Reihenfolge, Fehlerbehandlung, Validierung, Transaction-Management
- Business-Entscheidungen (im LLM): „Will der User kaufen?“, „Welches Tool passt?“, „Welche Parameter sind sinnvoll?“
Das LLM kann sich dann auf das konzentrieren, was es gut kann: Verstehen, was der User will, und entscheiden, welches Tool den gewünschten Business-Value liefert – nicht darauf, wie dieser Value technisch implementiert wird. Anders ausgedrückt: Du möchtest, dass das LLM entscheidet „Wir sollten eine Zugfahrt buchen“ und nicht „Jetzt rufe ich GET /stations auf, dann nehme ich die ID aus der Response, dann POST /bookings mit dieser ID …“
Faktoren von Cognitive Load
- Anzahl der Operationen: Die Train Travel API benötigt 5 separate Operationen für den Workflow "Zugfahrt buchen".
- Fehlende Intention: Keine Information über "Warum brauche ich diese Operation?"
- Implizite Abhängigkeiten: Welche Calls müssen in welcher Reihenfolge erfolgen?
- Token-Verschwendung: Jede Operation braucht eine Beschreibung im Context Window – und bei jeder weiteren Nachricht in der Konversation werden alle Tool-Beschreibungen erneut mitgeschickt.
Deshalb funktioniert einfaches 1:1-Mapping bei klassischen REST-APIs häufig nicht gut – es sei denn, die API ist bereits mit KI-Agenten im Hinterkopf designt worden.
Klassiker als Metaphern
Lass mich das Problem mit zwei Beispielen illustrieren, die du vielleicht kennst:
Die Linux-Geburtstagstorte
Ein beliebtes Meme aus der Linux-Community zeigt eine "Geburtstagstorte" mit der Überschrift "Happy Birthday! Compile your own cake" – eine Anspielung darauf, dass man unter Linux oft Software selbst aus dem Quellcode kompilieren muss, statt fertige Pakete zu nutzen. Was passiert, wenn wir dieses Prinzip auf API-Design übertragen?
Schlechtes Design (atomare Operationen):
Der Agent muss 11 separate Tools orchestrieren:
get_flour()(Hole Mehl aus dem Schrank)get_eggs()(Hole Eier aus dem Kühlschrank)get_sugar()(Hole Zucker)get_butter()(Hole Butter)mix_ingredients()(Mische Zutaten)preheat_oven()(Heize Ofen vor)bake_cake()(Backe Kuchen 40 Minuten)cool_cake()(Lasse Kuchen abkühlen)prepare_frosting()(Bereite Glasur vor)decorate_cake()(Dekoriere Kuchen)add_candles()(Füge Kerzen hinzu)
Das Problem: Der Agent muss die richtige Reihenfolge ableiten, Dependencies verstehen (Ofen vorheizen vor dem Backen!) und den kompletten Workflow selbst orchestrieren. Das ist massive Cognitive Load!
Gutes Design (use Case-orientiert):
Ein einziges Tool: serve_birthday_cake(age, flavor)
Was es macht:
- Torte ist fertig gebacken
- Passende Anzahl Kerzen ist auf der Torte
- Bereit zum Servieren
Der Vorteil: eine klare Intention. Minimale Cognitive Load. Der Agent weiß sofort, wann er dieses Tool nutzen soll.
Das IKEA-Bewerbungsgespräch
Ein weiteres Beispiel ist die Karikatur eines Bewerbungsgesprächs bei IKEA von Canary Pete – der Bewerber wird zu Beginn des Interviews aufgefordert, einen Stuhl zu montieren und Platz zu nehmen.
Das Problem: Stell dir vor, du kommst zum Bewerbungsgespräch und musst erstmal den Stuhl zusammenbauen, bevor du dich setzen kannst. Du bekommst einen Karton mit Einzelteilen, eine Anleitung in Piktogrammen und einen Inbusschlüssel. Erst wenn der Stuhl steht, kann das eigentliche Gespräch beginnen. Das ist absurd – niemand würde das von einem Bewerber oder einer Bewerberin erwarten. Der Fokus sollte auf dem Interview liegen, nicht auf der Möbelmontage.
Die Übertragung auf APIs: Genau das passiert jedoch, wenn wir KI-Agenten mit ressourcenorientierten APIs konfrontieren. Statt einem Tool für die Durchführung des Interviews bekommt der Agent:
- Bestelle Stuhlteile
- Öffne Paket
- Lies Anleitung
- Montiere Beine
- Befestige Sitzfläche
- ... (11 einzelne Schritte)
- Beginne Gespräch
Der Agent muss die gesamte "Infrastruktur" selbst aufbauen, bevor er die eigentliche Aufgabe angehen kann.
Der bessere Ansatz: Ein use-case-orientiertes Tool wie conduct_interview(candidate_name, position) abstrahiert all diese Details weg. Der Stuhl steht bereits. Der Raum ist vorbereitet. Das Interview kann sofort beginnen. Der Agent kann sich auf das Wesentliche konzentrieren – genau wie ein*e Bewerber*in sich auf das Gespräch konzentrieren sollte, nicht auf Möbelmontage.
Warum aber erwarten wir das von KI-Agenten bei APIs – oder nehmen diese Situation einfach hin?
Fazit: Ein fundamentales Designproblem – und warum es jetzt wichtig ist
Das Problem ist real und relevant
Wir haben gesehen, warum klassische REST-APIs KI-Agenten verwirren und überfordern – und es ist kein theoretisches Problem. Wenn du heute einen KI-Agenten mit deiner API verbindest, wird er mit einiger Wahrscheinlichkeit:
- Aus Dutzenden von Operationen unter Umständen die falschen auswählen
- Workflows in suboptimaler Reihenfolge ausführen
- Bei gleichen Anfragen unterschiedliche Wege wählen
- Vielleicht sogar häufiger scheitern als erfolgreich sein
Das liegt nicht an der Qualität der Modelle. Claude, GPT-5 und andere moderne LLMs sind beeindruckend leistungsfähig. Aber sie kämpfen gegen ein fundamentales Design-Mismatch: APIs wurden für Menschen gebaut, die Dokumentationen lesen, mentale Modelle aufbauen und mit unbegrenztem "Context Window" (Gehirn + IDE + Erfahrung) arbeiten.
Warum jetzt handeln?
Die KI-Integration von APIs ist keine Zukunftsmusik mehr – sie passiert jetzt. Unternehmen entwickeln MCP-Tools und bauen KI-Agenten, die ihre internen und externen APIs nutzen sollen. Die Frage ist nicht mehr "ob", sondern "wie gut".
Klar, die Modelle werden nach wie vor weiterentwickelt. Und wir können annehmen, dass damit auch die Möglichkeiten und Fähigkeiten, mit den in diesem Artikel beschriebenen Herausforderungen umzugehen, besser werden. Wir haben jedoch durchaus Mittel und Wege, das auch heute schon anders anzugehen – und unseren Agenten das “Leben” damit etwas leichter zu machen.
Und hier liegt die Chance: Du musst nicht zwischen "KI-freundlich" und "entwicklungsfreundlich" wählen. Die Prinzipien, die APIs für KI-Agenten besser machen – klarer Business-Kontext, explizite Use Cases, dokumentierte Workflows –, machen sie auch für menschliche Entwickler*innen intuitiver und einfacher zu nutzen.
Darüber “freuen” sich dann bestimmt auch die KI-Agenten. Sie danken es uns, indem sie weniger Tokens verbrauchen oder bessere und reproduzierbarere Ergebnisse erzielen.
Die Kernbotschaft zum Mitnehmen
Verschiebe Komplexität aus dem probabilistischen LLM in deterministischen Code.
Das ist kein Plädoyer gegen Flexibilität oder für starre, unflexible Systeme. Es ist ein Plädoyer für klare Verantwortlichkeiten:
- Das LLM versteht die Intention des/der Nutzenden und wählt das passende Tool.
- Der deterministische Code führt die komplexe Orchestrierung zuverlässig aus.
- Nutzende bekommen reproduzierbare, verlässliche Ergebnisse.
