Agentenfähige APIs: 9 Designregeln für KI-Agenten
API-Design für KI-Agenten: OpenAPI für Modelle geschrieben, kuratierte MCP-Tools, Idempotenzschlüssel, RFC-9457-Fehler, Paginierung und Ratenlimits.
Am 28. Juli 2026 erschien die MCP-Spezifikation 2026-07-28. Ihr Kapitel zu Tools hält unmissverständlich fest, was API-Teams auf die harte Tour gelernt haben: Die Fehlermeldung eines Tools richtet sich nicht an einen Menschen, sondern an ein Modell. Clients sollen sie laut Spezifikation an das Modell weitergeben, um die Selbstkorrektur zu ermöglichen. Parallel dazu haben Azure API Management, Amazon Bedrock AgentCore Gateway und Frameworks wie FastMCP dafür gesorgt, dass aus einer bestehenden REST-API mit wenigen Klicks ein Satz Agenten-Tools wird.
Jedes API-Team bekommt deshalb dasselbe Ticket: „Macht unsere API agentenfähig". Der OpenAPI-Export nach MCP funktioniert in der Demo. In Produktion wählt der Agent die falsche Operation, legt nach einem Timeout dasselbe Ticket zweimal an oder ertrinkt in einer Liste mit 400 Einträgen. Dieser Leitfaden richtet sich an alle, die darüber entscheiden: CTOs, API- und Plattformverantwortliche, Architektinnen und Architekten. Wir stellen neun Designregeln vor, zeigen, was wir in 127 öffentlichen OpenAPI-Beschreibungen gemessen haben, und geben Ihnen eine Checkliste für Ihre eigene API.
TL;DR / Das Wichtigste in Kürze
- Erst generieren, dann kuratieren. OpenAPI-zu-MCP-Konverter sind ein Startpunkt. Laut FastMCP-Dokumentation arbeiten Modelle mit kuratierten Servern deutlich besser als mit automatisch konvertierten. Liefern Sie aufgabenorientierte Tools, nicht ein Tool pro Endpunkt.
- Agenten wiederholen, also müssen Schreibzugriffe idempotent sein. Timeouts, unklare Fehler und „noch einmal versuchen"-Schleifen senden Schreibzugriffe erneut. Ein
Idempotency-Keyan jedem unsicheren POST ist die günstigste Versicherung, die Sie abschließen können. - Fehler sind Prompts. RFC-9457-Problem-Details mit stabilem Typ, betroffenem Feld und Wiederholungssignal lassen den Agenten seinen Aufruf selbst korrigieren. Ein nacktes
400 Bad Requestschickt ihn in eine Schleife. - Öffentliche API-Beschreibungen sind nicht so weit. In unserer Stichprobe deklariert keine von 127 Beschreibungen
application/problem+json, nur eine von sieben Flaggschiff-APIs deklariert einen Idempotenzschlüssel, und die mittlere Long-Tail-Spezifikation enthält keine Beispiele. - Alles begrenzen. Cursor-Paginierung, Filter, Antwortbudgets und agentenbewusste Ratenlimits schützen Kontextfenster und Backends. Erst in den Vertrag, dann ins Gateway.
Download: Editierbare draw.io-Datei · In diagrams.net öffnen · Diagrammdaten (CSV)
Warum das jetzt wichtig ist
Agenten rufen Ihre APIs bereits auf, ob Sie dafür entworfen haben oder nicht. Postmans 2025 State of the API Report, eine Befragung von über 5.700 Entwicklern, Architekten und Führungskräften, zeigt: 89 % der Entwickler nutzen KI, aber nur 24 % entwerfen APIs für KI-Agenten. 60 % entwerfen weiterhin primär für Menschen, und 51 % sorgen sich um unautorisierte oder übermäßige API-Aufrufe durch KI-Agenten.
Die Werkzeuge haben die Lücke von der anderen Seite geschlossen. Azure API Management stellt ausgewählte Operationen einer verwalteten REST-API als Tools eines Remote-MCP-Servers bereit. Amazon Bedrock AgentCore Gateway wandelt OpenAPI-, Smithy- und Lambda-Ziele in MCP-Tools um und ergänzt eine semantische Tool-Suche. FastMCPs from_openapi() macht standardmäßig aus jeder Route ein Tool.
Die technische Anbindung ist gelöst, das Design nicht. Ein Agent liest Ihre Beschreibungen wörtlich, leitet Argumente ab, wiederholt im Zweifel und bezahlt jedes Token, das Sie zurückgeben. Der größte Teil der Arbeit gehört in den API-Vertrag; der Adapter reicht ihn nur durch.
Die neun Designregeln, Zone für Zone
Die Nummern entsprechen den Markierungen im Diagramm. Die Regeln ①, ④, ⑤ und ⑧ leben in Ihrer API, ②, ③, ⑥ und ⑦ im Adapter, ⑨ zieht sich durch alle drei Zonen.
① Den Vertrag für ein Modell schreiben
Ihre OpenAPI-Beschreibung ist jetzt ein Prompt.
- Stabile
operationIds, die mit einem Verb beginnen. Sie werden zu Tool-Namen:createRefundschlägtpost_v2_refunds_by_id. MCP empfiehlt Namen mit 1 bis 128 Zeichen aus Buchstaben, Ziffern, Unterstrich, Bindestrich und Punkt. - Beschreibungen, die sagen, wann, nicht nur was. „Erstellt eine Erstattung für eine erfasste Zahlung. Nur nach Bestätigung durch den Kunden verwenden." Anthropic empfiehlt, Tool-Beschreibungen wie für eine neue Kollegin zu schreiben und Parameter eindeutig zu benennen:
user_id, nichtuser. - Enums, Formate und Beispiele. Jedes Freitextfeld, das Sie in ein Enum verwandeln, beseitigt eine Klasse fehlerhafter Argumente.
- Fehlerantworten mit Schema. Beschreibt der Vertrag keine Fehler, können weder Adapter noch Modell sie nutzen. Die Grundlagen für menschliche Konsumenten finden Sie in unseren Enterprise-API-Design-Prinzipien.
OpenAPI 3.1 ist die Untergrenze, weil es auf JSON Schema 2020-12 aufsetzt, den Dialekt, den MCP-Tool-Schemas standardmäßig verwenden. OpenAPI 3.2.0 vom 19. September 2025 bringt die Methode QUERY für sichere Suchen mit Request-Body und bessere Streaming-Unterstützung. Steigen Sie um, sobald Ihre Werkzeuge es können.
② Eine aufgabenorientierte Tool-Oberfläche kuratieren
Hier scheitern die meisten Agentenprojekte. Ein Eins-zu-eins-Export von 150 Operationen gibt dem Modell 150 fast gleiche Optionen und füllt den Kontext mit Schemas, bevor der Nutzer etwas gesagt hat.
Anthropics Leitfaden vom September 2025 plädiert für weniger, an Abläufen orientierte Tools, etwa ein Terminplanungs-Tool statt getrennter Tools für Nutzerliste, Terminliste und Terminanlage, und für Namensräume (asana_search, jira_search), wenn mehrere Server in einem Client zusammenkommen.
Kennzeichnen Sie dann das Verhalten. MCP-Tool-Annotationen kennen readOnlyHint (Standard false), destructiveHint (Standard true), idempotentHint (Standard false) und openWorldHint (Standard true). Ein Tool ohne Annotation gilt also als destruktiver, nicht idempotenter Schreibzugriff. Setzen Sie die Hinweise ehrlich und beachten Sie die Warnung der Spezifikation: Annotationen nicht vertrauenswürdiger Server sind als nicht vertrauenswürdig zu behandeln. Sie steuern die Freigabe-Oberfläche, sie sind keine Sicherheitsgrenze. Ergänzen Sie ein outputSchema, damit Clients structuredContent validieren können.
③ Jedem Aufruf Identität und Scope geben
Ein Agentenaufruf hat zwei Prinzipale: den Nutzer, für den er handelt, und den Agenten selbst. Autorisierung und Audit brauchen beide. Für MCP heißt das OAuth mit zielgruppengebundenen Tokens über den Resource-Parameter nach RFC 8707 und eigene Tokens für nachgelagerte Aufrufe statt weitergereichter. Den Ablauf zeigt unsere Analyse der MCP-Autorisierung, Token Exchange behandelt unser Leitfaden zur Identität von KI-Agenten.
Für das API-Design ist die Regel einfacher: Scope pro Tool, nicht pro API. Ein Such-Tool sollte nicht mit einem Token laufen, das Erstattungen auslösen kann. Die Spezifikation 2026-07-28 erlaubt ausdrücklich, dass tools/list je nach vorgelegter Autorisierung variiert. Ein Agent mit Lese-Scope muss die Schreib-Tools also gar nicht sehen.
④ Jeden unsicheren Schreibzugriff idempotent machen
Agenten wiederholen. Timeouts, 502-Fehler des Gateways, unklare Fehler und Modellschleifen erzeugen einen zweiten POST. Bei einer Suche ist das harmlos, bei einer Zahlung oder Bestellung ist es ein Vorfall.
Die Lösung ist ein Idempotency-Key-Header: ein eindeutiger Schlüssel pro fachlicher Operation, bei jeder Wiederholung derselbe; der Server speichert das erste Ergebnis und spielt es erneut aus. Der Entwurf der IETF-Arbeitsgruppe HTTPAPI (Revision 08 vom 22. Oktober 2026, weiterhin Internet-Draft) empfiehlt 400 für einen fehlenden Schlüssel, 422 für einen wiederverwendeten Schlüssel mit anderem Inhalt und 409, solange die erste Anfrage läuft. Stripe akzeptiert Schlüssel bis 255 Zeichen bei allen POST-Anfragen, darf sie in der v1-API löschen, sobald sie mindestens 24 Stunden alt sind, und lehnt Wiederholungen mit abweichenden Parametern ab.
Den Schlüssel sollte der Adapter aus dem Aufgabenschritt erzeugen, nicht das Modell; ein Modell merkt sich UUIDs nicht zuverlässig. Setzen Sie idempotentHint: true nur, wenn der Server es wirklich durchsetzt.
⑤ Fehler liefern, die anleiten
Die MCP-Spezifikation unterscheidet zwei Fehlerarten. Protokollfehler betreffen unbekannte Tools und fehlerhafte Anfragen. Tool-Ausführungsfehler, markiert mit isError: true, enthalten verwertbares Feedback, mit dem sich Sprachmodelle selbst korrigieren können. Das Beispiel der Spezifikation: ein ungültiges Abflugdatum, das in der Zukunft liegen muss.
Gestalten Sie REST-Fehler so, dass der Adapter genau so einen Satz erzeugen kann. RFC 9457 (Juli 2023, Nachfolger von RFC 7807) definiert application/problem+json. Für Agenten ergänzen wir drei Konventionen:
- Eine stabile
type-URI pro Fehlerklasse, damit der Adapter sie abbilden und Sie sie zählen können. - Ein
detail, das Feld, Regel und ein gültiges Beispiel nennt. „currencymuss ein ISO-4217-Code wieEURsein" schlägt „Validierung fehlgeschlagen". - Ein explizites Wiederholungssignal, etwa ein Erweiterungsfeld
retryable: false, damit Agenten denselben fehlerhaften Aufruf nicht erneut senden.
Stacktraces und interne Kennungen haben in detail nichts verloren.
⑥ Antworten für ein Kontextfenster paginieren und gestalten
Ein JSON-Array mit 2.000 Zeilen ist ein Denial-of-Service-Angriff auf ein Kontextfenster. Anthropic empfiehlt eine Kombination aus Paginierung, Bereichsauswahl, Filterung und Kürzung mit sinnvollen Standardwerten und nennt für Claude Code eine Standardgrenze von 25.000 Token pro Tool-Antwort. In Anthropics Beispiel kam eine kompakte Antwort mit 72 Token aus, die ausführliche brauchte 206, also rund das Dreifache.
Für Listen gilt: opake Cursor statt Seitennummern (MCP selbst nutzt cursor und nextCursor), kleine Standard-Seitengröße mit hartem Maximum, Filter, mit denen der Agent weniger anfordern kann, Namen neben IDs und ein Hinweis, ob mehr folgt. Wenn Sie kürzen, sagen Sie dem Agenten, wie er die Abfrage eingrenzt.
⑦ Pro Agent begrenzen und das Limit lesbar machen
Ein Agent in einer Schleife ruft mehr auf als ein ganzes Team, und Limits pro IP oder Subscription Key können ihn nicht von allen anderen auf demselben Schlüssel unterscheiden.
Setzen Sie Budgets pro Agentenidentität, pro Endnutzer und pro teurem Tool. Antworten Sie mit 429 Too Many Requests und Retry-After. Die IETF-Felder RateLimit und RateLimit-Policy (Entwurf 11, Mai 2026, noch kein RFC) kündigen das verbleibende Kontingent an, bevor der Client an die Wand fährt. Die MCP-Spezifikation verlangt, dass Server Tool-Aufrufe begrenzen. In API Management gelten rate-limit-by-key-Richtlinien für die Tools eines MCP-Servers wie für APIs.
⑧ Bei lang laufender Arbeit nie blockieren
MCP-Clients sollen Timeouts durchsetzen. Ein synchroner Aufruf, der drei Minuten läuft, bricht ab, der Agent wiederholt, und ohne Regel ④ laufen zwei Exporte.
Nutzen Sie 202 Accepted mit einer Status-Ressource, die der Agent abfragen kann. In MCP liefert ein Start-Tool ein explizites Handle zurück, das ein Status-Tool entgegennimmt. Die Spezifikation 2026-07-28 empfiehlt genau das für Zustand über mehrere Aufrufe hinweg: Die Lebensdauer des Handles gehört in die Tool-Beschreibung, und ein abgelaufenes Handle soll einen Tool-Fehler erzeugen, aus dem sich das Modell erholen kann.
⑨ Freigabe und Audit dort, wo der Schaden entsteht
Laut MCP-Spezifikation sollte immer ein Mensch Tool-Aufrufe ablehnen können. Ihre API macht das praktikabel: Probelauf-Modi für destruktive Operationen, prepare- und confirm-Schritte für hochwertige Aktionen und ein Audit-Eintrag pro Aufruf mit Nutzer, Agent, Tool-Call-ID, Idempotenzschlüssel und Ergebnis. Die Laufzeitseite behandelt unser Beitrag zu Human-in-the-Loop-Freigabe-Gates.
Was die Zahlen sagen
Wie weit sind heutige API-Beschreibungen von diesen Regeln entfernt? Wir haben zufällig 120 Anbieter (Seed 44) aus dem APIs.guru OpenAPI Directory gezogen, je eine Beschreibung, insgesamt 9.006 Operationen. Es sind Verzeichnisstände von 2017 bis 2023, also der Long Tail. Daneben haben wir sieben aktuelle, von den Anbietern veröffentlichte Beschreibungen geprüft, abgerufen am 15. November 2026: Stripe, GitHub, Twilio (API 2010), Box, PagerDuty, Jira Cloud und Adyen Checkout v72. Das Stichproben-Skript ist veröffentlicht. Es misst, was die Beschreibung deklariert; eine API kann sich besser verhalten, als ihre Beschreibung sagt.
Die Grundlagen sind weitgehend da, die agentenspezifischen Teile fehlen. Alle Flaggschiffe und die mittlere Long-Tail-Spezifikation geben jeder Operation eine ID, und sechs von sieben Flaggschiffen haben Beispiele an mehr als 80 % der Operationen. Im Long Tail nicht: Die mittlere Spezifikation hat weder Beispiele noch ein 4xx-Fehlerschema.
Problem Details deklariert niemand, 429 fast niemand. Keine der 127 Beschreibungen deklariert application/problem+json. Unter den Flaggschiffen dokumentiert nur PagerDuty 429 an den meisten Operationen; im Long Tail tun das 9 von 120 Spezifikationen an mindestens 80 % ihrer Operationen.
Idempotenz ist unsichtbar. Adyen Checkout deklariert einen Idempotency-Key-Header an 88 % seiner POST-Operationen, keine andere Beschreibung in der Stichprobe tut das. Stripe unterstützt Schlüssel an jedem POST, deklariert den Header aber nicht. Ein generierter Adapter sendet ihn also nie, solange niemand ihn ergänzt.
Das zweite Raster ist unsere Analyse, keine Messung. Jede Regel verhindert nur einen der acht Fehlermodi vollständig, eine allein reicht also nie. Die Regeln gegen die teuren Fehler, doppelte Seiteneffekte und überprivilegierte Aktionen, sind ③, ④ und ⑨, und ein generierter Adapter liefert keine davon.
Aus einem aktuellen Projekt
Anfang des Jahres sollten wir für einen europäischen Versicherer einen internen Schadenassistenten prüfen, der auf der bestehenden Schaden-API aufsetzte. Das Team hatte getan, was die Werkzeuge leicht machen: API ins Gateway importiert, jede Operation als MCP-Tool exportiert, einen Agenten darauf gesetzt. Die Demo überzeugte.
Die Produktion nicht. Der Agent wählte oft eine veraltete Suche statt der aktuellen, weil beide fast gleich beschrieben waren. Ein langsamer Endpunkt zur Dokumenterstellung lief in den Timeout, der Agent wiederholte, und in der Schadenakte lagen doppelte Schreiben. Generische 400-Fehler ließen den Agenten dieselbe Nutzlast erneut senden, bis ein Limit pro Subscription Key griff, das auch alle anderen Konsumenten der API ausbremste.
Keine der Korrekturen war raffiniert. Eine Handvoll aufgabenorientierter Tools ersetzte den Export, veraltete Operationen flogen raus. Der Adapter erzeugte Idempotenzschlüssel aus der Tool-Call-ID, die Dokumenterstellung wechselte auf 202 Accepted, Fehler wurden zu Problem Details mit Wiederholungssignal, Limits galten pro Agent und Nutzer. Am schwierigsten war die Frage, wem die Tool-Beschreibungen gehören: dem API-Team, mit Review wie bei Code.
Die Checkliste für agentenfähige APIs
Nutzen Sie sie als Prüftor, bevor eine API für Agenten freigegeben wird.
| Regel | Mindeststandard | So testen Sie es |
|---|---|---|
| ① Vertrag | OpenAPI 3.1+, operationId mit Verb, Beschreibung mit 40+ Zeichen je Operation, Enums, Beispiele, Fehlerschemas | Linting mit Spectral oder Redocly; unser Stichproben-Skript auf Ihre Beschreibung anwenden |
| ② Tool-Oberfläche | Aufgabenorientierte Tools; Legacy- und Admin-Operationen ausgeschlossen; Namensräume; Annotationen und outputSchema | Evals zur Tool-Auswahl in der CI: Prompts mit erwartetem Tool |
| ③ Identität | Zielgruppengebundene OAuth-Tokens; Scope pro Tool; Nutzer und Agent identifizierbar | Jedes Tool mit zu schwachem Token aufrufen; 403 und kein gelistetes Tool erwarten |
| ④ Idempotenz | Idempotency-Key an jedem unsicheren POST, vom Adapter erzeugt, mindestens 24 h aufbewahrt | Anfrage wiederholen, dann mit geändertem Body; genau ein Effekt und 422 erwarten |
| ⑤ Fehler | application/problem+json; stabile type-URIs; detail auf Feldebene; Wiederholungssignal | Argumente fuzzen; der Agent muss sich in höchstens zwei Versuchen korrigieren |
| ⑥ Antworten | Cursor-Paginierung; Standard-Seitengröße höchstens 50; Filter; Kompaktmodus; Hinweis auf weitere Ergebnisse | Token-Größe der größten Standardantwort messen |
| ⑦ Ratenlimits | Budgets pro Agent und Nutzer; 429 + Retry-After; eigene Limits für teure Tools | Lasttest mit Agent in Schleife; andere Konsumenten bleiben unberührt |
| ⑧ Langläufer | Nichts Synchrones über dem Client-Timeout; 202 + Status-Ressource oder Handle | Verbindung mitten im Aufruf trennen und wiederholen; genau ein Job |
| ⑨ Freigabe und Audit | Probelauf für destruktive Tools; Freigabe für hochwertige Aktionen; Audit-Eintrag pro Aufruf | Einen Aufruf allein aus dem Audit-Log vollständig rekonstruieren |
Seitengröße und Aufbewahrungsdauer sind unsere Standardwerte, keine Normen.
Governance für europäische Unternehmen
Keine EU-Regulierung behandelt API-Design für Agenten direkt. Mehrere greifen aber bei dem, was ein Agent über Ihre API tut.
DSGVO. Jedes Feld, das ein Tool zurückgibt, landet im Kontext eines Modells und oft bei einem Modellanbieter als Ihrem Auftragsverarbeiter. Datenminimierung (Art. 5 Abs. 1 lit. c DSGVO) und Datenschutz durch Technikgestaltung (Art. 25 DSGVO) sind die juristischen Namen für Regel ⑥. Halten Sie personenbezogene Daten auch aus detail und aus Idempotenzschlüsseln heraus.
NIS2. Artikel 21 der Richtlinie (EU) 2022/2555, in Deutschland § 30 BSIG, verlangt Konzepte für Zugriffskontrolle und die Bewältigung von Sicherheitsvorfällen. Agentenidentitäten mit Scope, Protokollierung und Widerrufbarkeit (Regeln ③ und ⑨) sind Ihr Nachweis für nicht-menschliche Aufrufer.
DORA. Der IKT-Risikomanagementrahmen eines Finanzunternehmens nach Verordnung (EU) 2022/2554 sollte jeden Agenten mit Schreibzugriff auf eine Kern-API abdecken.
KI-Verordnung. Die meisten Agenten, die Ihre API aufrufen, sind keine Hochrisiko-KI-Systeme. Wo doch, gelten die Pflichten für Anhang-III-Systeme, darunter Protokollierung und menschliche Aufsicht, ab dem 2. Dezember 2027, nachdem die Verordnung (EU) 2026/1744 sie verschoben hat. Der Audit-Eintrag aus Regel ⑨ ist in jedem Fall das Rohmaterial.
Ein pragmatischer Einführungspfad
- Woche 1–2: messen. Führen Sie die neun Prüfungen durch und listen Sie die Operationen auf, die Agenten wirklich brauchen, meist ein Bruchteil des Katalogs.
- Woche 3–4: den Vertrag reparieren. Beschreibungen dieser Operationen neu schreiben, Enums und Beispiele ergänzen, Fehler als Problem Details beschreiben. Davon profitieren auch menschliche Konsumenten.
- Monat 2: Schreibzugriffe absichern. Idempotenzschlüssel an jedem unsicheren POST im Scope, Langläufer auf
202+ Status, Probelauf für destruktive Operationen. - Monat 2–3: den Adapter kuratieren. Aus dem Vertrag generieren, dann auf aufgabenorientierte Tools mit Annotationen, Ausgabeschemas, Scopes pro Tool und agentenbewussten Limits reduzieren. Hosting und Scope behandelt unser Leitfaden zum Design von Enterprise-MCP-Servern.
- Ab Monat 3: wie ein Produkt testen. Evals für Tool-Auswahl und Fehlerkorrektur in die CI, Telemetrie auf Wiederholungs- und 4xx-Schleifen beobachten, Tool-Beschreibungen versionieren wie Code.
Das Fazit
Eine API agentenfähig zu machen, ist kein Protokollprojekt. Die Konverter haben das Protokoll gelöst; einen Vertrag, der für sorgfältige Menschen geschrieben wurde, machen sie nicht zu einem, den ein probabilistischer Aufrufer sicher nutzen kann. Diese Arbeit liegt beim API-Team.
Unsere Haltung ist klar. Exportieren Sie nicht Ihre ganze API an Agenten. Wählen Sie die Aufgaben, kuratieren Sie die Tools und setzen Sie die Regeln ④ und ⑤ um, bevor irgendetwas live geht. Doppelte Seiteneffekte und Fehlerschleifen sind die Fehler, die Geld kosten. Alles andere erhöht die Trefferquote, diese beiden verhindern den Vorfall.
Wenn Sie einen zweiten Blick wünschen: Unser Team für Softwarearchitektur prüft Ihre API-Beschreibungen und Adapter-Konfiguration anhand dieser neun Regeln. Sie erhalten die ausgefüllte Checkliste für Ihre eigene Landschaft.
FAQ
Was macht eine API agentenfähig?
Ein Sprachmodell kann sie allein anhand der Beschreibung korrekt aufrufen, und sie hält aus, wie Agenten sich verhalten: Wiederholungen nach Timeouts, geratene Argumente, Schleifen über Ergebnisse. Dafür braucht es einen für Modelle geschriebenen Vertrag, kuratierte Tools, Identität mit Scopes, idempotente Schreibzugriffe, Fehler mit Handlungsanweisung, begrenzte Antworten, lesbare Ratenlimits, asynchrone Langläufer und einen Audit-Trail mit Nutzer und Agent.
Sollten wir einen MCP-Server aus unserer OpenAPI-Beschreibung generieren?
Als Ausgangspunkt ja, als Produkt nein. FastMCP, Azure API Management und Amazon Bedrock AgentCore Gateway wandeln OpenAPI-Operationen in MCP-Tools um, aber laut FastMCP-Dokumentation arbeiten Modelle mit kuratierten Servern deutlich besser als mit automatisch konvertierten. Generieren Sie, reduzieren Sie dann auf aufgabenorientierte Tools, schreiben Sie Beschreibungen für ein Modell, ergänzen Sie Annotationen und Ausgabeschemas und schließen Sie Operationen aus, die Agenten nicht aufrufen sollen.
Brauchen KI-Agenten Idempotenzschlüssel?
Ja, für jeden Schreibzugriff, der nicht doppelt passieren darf. Agenten wiederholen bei Timeouts, bei unklaren Fehlern und wenn das Modell es noch einmal versucht. Ein Idempotency-Key-Header lässt den Server das erste Ergebnis wiederholen, statt eine zweite Zahlung oder ein zweites Ticket anzulegen. Der IETF-Entwurf (Revision 08, Oktober 2026) empfiehlt 400 für einen fehlenden Schlüssel, 422 für einen wiederverwendeten Schlüssel mit anderem Inhalt und 409, solange die erste Anfrage noch läuft.
Wie sollten API-Fehler für KI-Agenten aussehen?
Liefern Sie RFC-9457-Problem-Details (application/problem+json) mit stabiler Typ-URI und einem detail, das Feld, erwartetes Format und Wiederholbarkeit nennt. Die MCP-Spezifikation 2026-07-28 trennt Protokollfehler von Tool-Ausführungsfehlern und sagt, dass Clients Ausführungsfehler, markiert mit isError, an das Modell weitergeben sollen, damit es sich selbst korrigieren kann.
Wie paginieren wir API-Antworten für LLM-Agenten?
Mit opaken Cursorn, kleiner Standard-Seitengröße, Filtern und einem Hinweis, ob weitere Ergebnisse folgen, dazu kompakte und ausführliche Antwortformate. Anthropic empfiehlt eine Kombination aus Paginierung, Bereichsauswahl, Filterung und Kürzung und nennt für Claude Code eine Standardgrenze von 25.000 Token pro Tool-Antwort.
Wie begrenzen wir KI-Agenten, ohne sie zu blockieren?
Mit Budgets pro Agentenidentität und pro Endnutzer statt nur pro IP oder Subscription Key. Antworten Sie mit 429 und Retry-After, damit Clients zurückweichen, und prüfen Sie die Felder RateLimit und RateLimit-Policy aus dem IETF-HTTPAPI-Entwurf, im November 2026 noch ein Internet-Draft. Auf Agentenseite gehören begrenzte Wiederholungen mit Jitter dazu, damit eine Agentenflotte aus einer langsamen Abhängigkeit keinen Retry-Sturm macht.
Quellen
Alle Quellen geprüft am 15. November 2026. Diagramm 1 ist unsere eigene Analyse; Methode und Skript sind unten verlinkt.
Stufe A: Primärquellen, Spezifikationen und Regulierung
- Model Context Protocol, Spezifikation 2026-07-28, Tools: https://modelcontextprotocol.io/specification/2026-07-28/server/tools
- Model Context Protocol, Schema-Referenz 2026-07-28 (ToolAnnotations, Paginierung): https://modelcontextprotocol.io/specification/2026-07-28/schema
- OpenAPI Specification 3.2.0 (19. September 2025): https://spec.openapis.org/oas/v3.2.0.html
- RFC 9457, Problem Details for HTTP APIs: https://www.rfc-editor.org/rfc/rfc9457.html
- RFC 9110, HTTP Semantics (202 Accepted, Retry-After): https://www.rfc-editor.org/rfc/rfc9110.html
- RFC 8707, Resource Indicators for OAuth 2.0: https://www.rfc-editor.org/rfc/rfc8707.html
- IETF draft-ietf-httpapi-idempotency-key-header-08: https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
- IETF draft-ietf-httpapi-ratelimit-headers-11: https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/
- Verordnung (EU) 2016/679 (DSGVO), Art. 5 und 25: https://eur-lex.europa.eu/eli/reg/2016/679/oj/deu
- Richtlinie (EU) 2022/2555 (NIS2), Artikel 21: https://eur-lex.europa.eu/eli/dir/2022/2555/oj/deu
- Verordnung (EU) 2022/2554 (DORA): https://eur-lex.europa.eu/eli/reg/2022/2554/oj/deu
Stufe B: Forschung und Daten
- Postman, 2025 State of the API Report: https://www.postman.com/state-of-api/2025/
- Anthropic Engineering, „Writing effective tools for agents — with agents" (11. September 2025): https://www.anthropic.com/engineering/writing-tools-for-agents
- APIs.guru OpenAPI Directory (Stichprobenrahmen): https://api.apis.guru/v2/list.json
- CC Conceptualise, Stichproben-Skript und Ergebnisse: https://www.conceptualise.de/blog/agent-ready-api-design-guidelines/openapi_sample.py und https://www.conceptualise.de/blog/agent-ready-api-design-guidelines/data.csv
Stufe C: Herstellerdokumentation, richtungsweisend
- Microsoft Learn, REST-API in API Management als MCP-Server bereitstellen: https://learn.microsoft.com/de-de/azure/api-management/export-rest-mcp-server
- AWS, Amazon Bedrock AgentCore Gateway: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html
- FastMCP, OpenAPI-Integration: https://gofastmcp.com/integrations/openapi
- Stripe API Reference, Idempotent requests: https://docs.stripe.com/api/idempotent_requests
- Geprüfte Flaggschiff-Beschreibungen: Stripe (github.com/stripe/openapi), GitHub (github.com/github/rest-api-description), Twilio (github.com/twilio/twilio-oai), Box (github.com/box/box-openapi), PagerDuty (github.com/PagerDuty/api-schema), Jira Cloud (developer.atlassian.com), Adyen (github.com/Adyen/adyen-openapi)
Themen