API-Versionierung für KI-Agenten: Umgang mit Breaking Changes

API-Drift bei KI-Agenten erkennen, bevor sie Produktion trifft

Das API-Team benennt customer_name in customer_full_name um, aktualisiert die Dokumentation und informiert bekannte Clients. Der Agent sendet weiter das alte Feld; die API ignoriert es stillschweigend, antwortet mit 200 OK, und zwei Wochen lang entstehen Datensätze ohne Namen.

Teste Apidog noch heute

Agenten sind besonders anfällig für API-Drift: Sie lesen ein 200 als Erfolg, improvisieren bei fehlenden Werten und arbeiten mit Tool-Beschreibungen, die nach einer API-Änderung unbemerkt falsch werden können. Anders als typisierte Clients haben sie keinen Compiler, der einen Vertragsbruch vor dem Deployment erkennt.

Warum KI-Agenten in der Produktion ausfallen behandelt die internen Ursachen. Dieser Artikel konzentriert sich auf Änderungen außerhalb Ihrer Codebasis.

Warum Agenten Änderungen übersehen

Vier Eigenschaften machen API-Drift für Agenten gefährlich:

• Stille Toleranz: Viele APIs ignorieren unbekannte Request-Felder. Nach einer Umbenennung fehlt das neue Feld, das alte wird verworfen, und der Aufruf endet trotzdem mit 200.
• Improvisation: Fehlt ein Wert in der Antwort, ersetzt ein Modell ihn oft durch eine plausible Annahme, statt den Lauf abzubrechen.
• **Tool-Beschreibungen im [REDACTED PROMPT]men über Endpunkte, Parameter und Verhalten. Ändert sich die API, können falsche Beschreibungen zu falschen Tool-Aufrufen führen. Siehe Design von Tool-Schemas.
• Kein Compiler: Typisierte Clients schlagen beim Build fehl. Agenten-Verträge bestehen oft aus JSON-Schemas und Prosa und werden erst beim Aufruf geprüft — oder gar nicht.

Behandeln Sie API-Änderungen deshalb für Agenten getrennt von herkömmlichen Clients.

Änderungen, die Agenten brechen können

Für alle brechend

Diese Änderungen sind klar inkompatibel:

• Endpunkt oder Feld entfernen
• Feld umbenennen
• Typ ändern
• optionalen Parameter erforderlich machen
• URL ändern

Agenten brechen dabei oft leiser als klassische Clients.

Für typisierte Clients oft akzeptabel, für Agenten riskant

• Neues Pflichtfeld: Der Agent erhält einen Validierungsfehler und kann versuchen, einen Wert zu erfinden.
• Neuer Enum-Wert: Ein Agent kann einen unbekannten Status interpretieren und daraus falsche Geschäftslogik ableiten.
• Strengere Validierung: Wenn ein String jetzt einem Muster entsprechen muss, sollte die API dies klar in der Fehlermeldung nennen. Siehe API-Fehlerdesign für Agenten.
• Geänderter Standardwert: Sinkt die Standard-Seitengröße von 100 auf 20, sieht ein Agent ohne explizites Limit nur noch ein Fünftel der Daten und kann sie trotzdem als vollständig zusammenfassen.
• Überarbeitete Dokumentation: Werden Tools aus OpenAPI generiert, kann schon eine geänderte Beschreibung die Tool-Auswahl beeinflussen. Siehe OpenAPI-Spezifikationen in Agenten-Tools umwandeln.

Auch für Agenten normalerweise sicher

• optionales Feld hinzufügen
• Endpunkt hinzufügen
• optionalen Parameter mit unverändertem Standardwert hinzufügen
• Validierung lockern

Versionen immer explizit festlegen

Die erste Verteidigung lautet: Nicht unbemerkt mitwandern.

Senden Sie bei jeder Anfrage eine explizite API-Version — per Pfad, Header oder kontoweiter Pin. GitHub verwendet beispielsweise einen Datums-Header in seiner API-Versionsdokumentation; Stripe arbeitet mit kontoweiten Versionen und expliziten Upgrades.

DEFAULT_HEADERS = {
    "X-API-Version": "2026-06-01",
    "User-Agent": "billing-agent/1.4 (+https://example.com/agents)",
}

Der User-Agent ist ebenso wichtig wie die Versions-Pin. Anbieter prüfen bei Deprecations ihren Traffic. Ein eindeutig identifizierter Agent kann eine Warnung erhalten; ein generischer Bibliotheks-User-Agent möglicherweise nicht.

Wenn Sie die API selbst betreiben:

1. Veröffentlichen Sie versionierte Verträge.
2. Halten Sie jede Version stabil.
3. Erzwingen Sie bewusste Upgrades.

Siehe die beste API-Versionierungsstrategie und API-Versionierung in Apidog verwalten.

Bei nicht versionierten Drittanbieter-APIs pinnen Sie zumindest den erwarteten Antwortvertrag und prüfen ihn kontinuierlich.

Drift vor dem Agentenlauf erkennen

Versionierung verschafft Zeit, ersetzt aber keine Erkennung. Kombinieren Sie drei Kontrollen.

1. Spezifikationen regelmäßig vergleichen

Wenn ein Anbieter OpenAPI bereitstellt:

1. Laden Sie die Spezifikation täglich herunter.
2. Vergleichen Sie sie mit der Version, aus der Ihre Tools generiert wurden.
3. Prüfen Sie insbesondere entfernte Felder, geänderte Typen, neue Anforderungen, erweiterte Enums und geänderte Beschreibungen.

In Apidog können Sie importierte Definitionen versioniert halten und Unterschiede zwischen Versionen prüfen.

2. Kontrakttests für jedes Agenten-Tool ausführen

Senden Sie für jedes Tool eine bekannte gültige Anfrage und validieren Sie die Antwort:

• erforderliche Felder vorhanden
• korrekte Typen
• erwartete Enum-Werte
• erwartete Standardwerte und Seitengrößen

Das erkennt Drift auch bei APIs ohne veröffentlichte Spezifikation. Siehe API-Kontrakttests und bidirektionale Kontrakttests.

3. Antwortformen zur Laufzeit validieren

Prüfen Sie Antworten im Tool-Wrapper gegen das erwartete Schema:

def check_shape(tool_name, payload, expected):
    missing = [f for f in expected["required"] if f not in payload]
    extra = [f for f in payload if f not in expected["properties"]]
    if missing:
        log.error("api_drift", tool=tool_name, missing=missing)
        raise ApiDriftError(f"{tool_name}: missing fields {missing}")
    if extra:
        log.warning("api_new_fields", tool=tool_name, fields=extra)
    return payload

Fehlschlagen bei fehlenden, warnen bei zusätzlichen Feldern.

Ein fehlendes Pflichtfeld bedeutet, dass der Agent mit unvollständigen Daten weiterarbeiten würde. Neue Felder sind meist additiv, sollten aber in Ihren Traces erscheinen. Leiten Sie beide Ereignisse in die Tool-Aufruf-Telemetrie weiter, wie in Tracing von Agenten-Tool-Aufrufen beschrieben.

Zusätzlich sollten Sie Verhalten beobachten, das ein Schema-Diff nicht sieht:

• Aufrufe pro abgeschlossener Aufgabe
• Wiederholungsrate pro Endpunkt
• durchschnittliche Antwortgröße pro Tool
• Latenz und Ratenbegrenzungen

Sprünge in diesen Kennzahlen weisen oft auf Upstream-Änderungen hin.

API-Upgrades sicher durchführen

Ein API-Upgrade ist auch eine Änderung am Agenten. Nutzen Sie diesen Ablauf:

1. Tools neu generieren: Bearbeiten Sie Tool-Schemas und Beschreibungen nicht manuell.
2. Generierten Diff prüfen: Er zeigt den tatsächlichen Auswirkungsbereich besser als ein Changelog.
3. Gegen einen Mock der neuen Version testen: Führen Sie Ihre gesamte Task-Suite zunächst gegen einen aus der neuen Spezifikation erzeugten Mock aus. Siehe Agenten gegen Mocks statt Produktion ausführen.
4. Tool-Auswahl erneut testen: Geänderte Beschreibungen können die Tool-Auswahl verschieben, obwohl das Schema gleich bleibt. Siehe nicht-deterministische Agenten testen.
5. Hinter einem Feature-Flag ausrollen: Lassen Sie die alte Version gepinnt und rollback-fähig.
6. Metriken beobachten: Achten Sie mindestens einen Tag auf mehr Aufrufe pro Aufgabe und mehr Wiederholungen.

Drei typische Produktionsfehler

Umbenanntes Feld

customer_name wird zu customer_full_name. Die API ignoriert das alte Feld, liefert 200 OK, und erzeugte Datensätze haben leere Namen.

Schutz: Validieren Sie, dass das erwartete Feld in der Antwort vorhanden ist.

Geänderte Standard-Seitengröße

Ein Anbieter reduziert die Standardgröße von 100 auf 20. Der Agent sendet kein limit, sieht nur einen Teil der Daten und fasst ihn als vollständige Menge zusammen.

Schutz: Senden Sie limit immer explizit.

Neuer Enum-Wert

Eine Zahlungs-API ergänzt status: "disputed". Typisierte Clients ignorieren ihn vielleicht; der Agent deutet ihn als Rückerstattung und meldet fälschlich abgeglichene Bücher.

Schutz: Validieren Sie Enums explizit und brechen Sie bei unbekannten Werten ab.

Das Muster ist immer gleich: Die Änderung ist angekündigt und aus Sicht des Anbieters klein oder additiv. Für einen Agenten kann sie trotzdem produktionskritisch sein.

Deprecations als Arbeitsaufgabe behandeln

Deprecation-Warnungen erscheinen häufig in Changelogs, E-Mails oder Response-Headern. Erfassen Sie insbesondere:

• Deprecation
• Sunset

Protokollieren und alarmieren Sie beim ersten Auftreten, nicht beim tausendsten. Ein Header, der heute bei 3 % der Aufrufe erscheint, kann am Sunset-Datum zu einem vollständigen Ausfall werden.

Pflegen Sie außerdem ein kleines Inventar:

Agent	Anbieter	API-Version	Endpunkte	Verantwortlich
Billing-Agent	Zahlungsanbieter	2026-06-01	/charges, /refunds	Team Payments

Wenn eine Deprecation eintrifft, sollte die Frage „Betrifft uns das?“ in einer Minute beantwortbar sein.

Drift-Warnungen brauchen einen Besitzer. Legen Sie sie in Ihrem normalen Arbeitssystem ab. Wenn Agenten als Coding-Runtimes laufen, kann eine Verwaltungsplattform wie Sharkly aus einer Warnung eine zugewiesene, überprüfbare Aufgabe machen. Entscheidend ist nicht das Tool, sondern die Regel: Eine Drift-Warnung ohne Verantwortlichkeit wird erst am Ausfalltag wieder sichtbar.

Checkliste

• [ ] Jede Anfrage sendet eine explizite API-Version und einen identifizierenden User-Agent.
• [ ] Drittanbieter-Spezifikationen werden regelmäßig abgerufen und verglichen.
• [ ] Jedes Agenten-Tool besitzt einen Kontrakttest für die Antwortform.
• [ ] Tool-Wrapper schlagen bei fehlenden und warnen bei neuen Feldern fehl.
• [ ] Endpunktmetriken machen stille Verhaltensänderungen sichtbar.
• [ ] API-Upgrades generieren Tools neu, statt sie manuell zu ändern.
• [ ] Task- und Tool-Auswahl-Suite laufen zuerst gegen einen Mock der neuen Version.
• [ ] Rollouts sind per Feature-Flag steuerbar und auf die zuvor gepinnte Version zurücksetzbar.
• [ ] Deprecation- und Sunset-Header erzeugen zugewiesene Arbeitsaufgaben.

API-Teams werden weiter Änderungen veröffentlichen. Das ist normal. Ihr Agent muss aber ein Client sein, der diese Änderungen bemerkt: mit Versions-Pins, Kontrakttests und Laufzeit-Validierung der Antwortform.

Lade Apidog herunter, um Spezifikationen zu vergleichen und neue API-Versionen zu mocken, bevor sie Produktion erreichen.

Häufig gestellte Fragen

Wie oft sollte ich Drittanbieter-Spezifikationen prüfen?

Täglich reicht für die meisten APIs und lässt sich günstig automatisieren. Gibt es keine veröffentlichte Spezifikation, setzen Sie auf Kontrakttests in CI.

Sollte ich dauerhaft auf der ältesten funktionierenden API-Version bleiben?

Nein. Pinnen Sie Versionen, damit Upgrades bewusst stattfinden, und planen Sie diese Upgrades regelmäßig. Bis zur Abschaltung auf einer alten Version zu bleiben, verwandelt planbare Arbeit in einen Notfall.

Was, wenn der Agent nach einer Änderung scheinbar einwandfrei funktioniert?

Prüfen Sie trotzdem. Die gefährlichsten Fehler liefern weiterhin 200 OK, etwa wenn ein umbenanntes Feld stillschweigend verworfen wird. Eine Formprüfung erkennt, was ein scheinbar erfolgreicher Lauf nicht zeigt.

Muss ich meine eigene API für Agenten anders versionieren?

Nicht grundsätzlich anders, aber strenger. Behandeln Sie neue Pflichtfelder, neue Enum-Werte und geänderte Standardwerte als potenziell brechend für Agenten, selbst wenn sie für typisierte Clients additiv wirken.

Woher weiß ich, welche Agenten welche Endpunkte nutzen?

Aus Ihren Traces. Toolname und Endpunkt pro Lauf ergeben eine Abhängigkeitskarte und zeigen, welche Agenten von einer Deprecation betroffen sind.

Kann sich ein Agent selbst an eine geänderte API anpassen?

Manchmal, aber darauf sollten Sie nicht vertrauen. Ein Modell kann fehlende Daten plausibel ersetzen, ohne dass ein Fehler sichtbar wird. Brechen Sie stattdessen laut ab und aktualisieren Sie Vertrag, Tool und Tests.