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

Das API-Team benannte ein Feld von customer_name in customer_full_name um. Sie kündigten es an, aktualisierten die Dokumentation, und jeder manuell gepflegte Client erhielt einen Pull Request. Ihr Agent erhielt nichts, weil niemand ihn als Client betrachtete. Er sendete weiterhin das alte Feld, die API akzeptierte die Anfrage und ignorierte den unbekannten Schlüssel, und zwei Wochen lang hatte jeder von ihm erstellte Datensatz einen leeren Namen.

Agenten sind die API-Konsumenten, die am wenigsten in der Lage sind, eine Änderung zu bemerken, und am ehesten dazu neigen, darüber hinwegzusehen. Ein menschlicher Client löst eine Ausnahme aus. Ein Agent liest einen 200, entscheidet, dass der Aufruf funktioniert hat, und fährt fort. Manchmal improvisiert er um das Problem herum auf eine Weise, die wie ein Erfolg aussieht.

Dieser Leitfaden behandelt, warum Agenten ungewöhnlich anfällig für API-Drift sind, welche Änderungen sie brechen, die gewöhnliche Clients nicht brechen würden, wie man Versionen festnagelt und erkennt und wie man Drift in CI abfängt, bevor ein Lauf dies tut. Unser Beitrag zu warum KI-Agenten in der Produktion ausfallen behandelt die Fehlerursachen; dies ist diejenige, die außerhalb Ihrer Codebasis entsteht.

Apidog ist hier relevant, weil die Erkennung ein Spezifikationsproblem ist. Wenn Sie die vorherige Version einer API-Definition und die aktuelle haben, ist der Unterschied mechanisch.

Warum Agenten weniger bemerken als Clients

Vier Eigenschaften wirken sich schlecht aus.

Stille Toleranz. Die meisten APIs ignorieren unbekannte Felder in einem Request-Body. Ein umbenanntes Feld bedeutet, dass das neue fehlt und das alte verworfen wird, mit einem 200 auf dem Weg nach draußen. Nichts wird gemeldet.

Improvisation. Wenn in einer Antwort ein Wert fehlt, fährt ein Modell oft mit einem plausiblen Ersatz fort, anstatt anzuhalten. Das ist im Gespräch hilfreich, aber im Umgang mit einer API gefährlich.

Beschreibungen im Prompt. Agenten-Tool-Beschreibungen kodieren Annahmen über die API in Textform. Wenn sich die API ändert, werden die Beschreibungen subtil falsch, und falsche Beschreibungen führen zu falschen Aufrufen, ohne dass Code beteiligt ist. Unser Beitrag zum Design von Tool-Schemas behandelt, wie viel Verhalten von diesem Text abhängt.

Kein Compiler. Ein typisierter Client bricht zur Build-Zeit ab, wenn ein Feld verschwindet. Der Vertrag eines Agenten lebt in JSON-Schemas und Prosa, und nichts überprüft ihn, bis ein Aufruf fehlschlägt oder, schlimmer noch, bis einer stillschweigend nicht fehlschlägt.

Das Fazit: Änderungen, die für typische Clients sicher sind, sind nicht immer sicher für Agenten, und Sie sollten sie getrennt klassifizieren.

Welche Änderungen Agenten tatsächlich brechen

Die übliche Unterscheidung zwischen additiv und brechend gilt weiterhin, und Agenten fügen eine mittlere Kategorie hinzu.

• Tatsächlich brechend, für alle. Das Entfernen eines Endpunkts, das Entfernen eines Feldes, das Umbenennen eines Feldes, das Ändern eines Typs, das Erforderlichmachen eines optionalen Parameters, das Ändern der URL. Agenten brechen hier auch, nur stillschweigender.
• Sicher für typisierte Clients, riskant für Agenten:
  • Ein neues erforderliches Feld. Jeder bestehende Aufrufer bricht, aber ein Agent bricht mit einem Validierungsfehler, den er möglicherweise durch Erfinden eines Wertes zu beheben versucht. Das ist schlimmer als ein harter Fehler.
  • Ein neuer Enum-Wert. Gewöhnliche Clients ignorieren, was sie nicht verarbeiten. Ein Agent könnte über den unbekannten Wert nachdenken und eine Schlussfolgerung ziehen, die Ihr Produkt nie beabsichtigt hat.
  • Eine verschärfte Validierungsregel. Ein Feld, das früher jede Zeichenkette akzeptierte, erfordert jetzt ein Muster. Der Agent hat keine Möglichkeit, das Muster zu lernen, außer durch Scheitern, weshalb die Regel in der Fehlermeldung stehen sollte, wie in unserem Beitrag zum API-Fehlerdesign für Agenten beschrieben.
  • Ein geänderter Standardwert. Der Standardwert für die Paginierung sinkt von 100 auf 20, und der Agent, der nie ein Limit gesendet hat, sieht jetzt ein Fünftel der Daten und berichtet darüber, als wären sie vollständig.
  • Neu formulierte Dokumentation. Keine Verhaltensänderung, aber wenn Ihre Tools aus der Spezifikation generiert werden, wie in unserem Leitfaden zum Umwandeln einer OpenAPI-Spezifikation in Agenten-Tools, hat sich der Beschreibungstext geändert, und die Tool-Auswahl kann sich damit verschieben.
• Auch für Agenten sicher. Hinzufügen eines optionalen Feldes, Hinzufügen eines Endpunkts, Hinzufügen eines optionalen Parameters mit einem beibehaltenen Standardwert, Lockerung der Validierung.

Die mittlere Liste ist diejenige, die man im Auge behalten sollte, denn nichts in einer Standard-Änderungsprüfung kennzeichnet sie.

Immer die Version festlegen

Die erste Verteidigung besteht darin, sich implizit nicht zu bewegen.

Senden Sie bei jeder Anfrage eine explizite Version, unabhängig vom Mechanismus, den die API bietet: ein Pfadsegment, einen Header oder eine kontoweite Pin. Die API-Versionsdokumentation von GitHub verwendet einen Datums-Header, und Stripe legt eine Version pro Konto mit einem expliziten Upgrade-Schritt fest. Beide geben Ihnen die gleiche Eigenschaft: Nichts ändert sich unter Ihnen, bis Sie es entscheiden.

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

Der User-Agent ist genauso viel wert wie die Versionspin. Wenn ein API-Anbieter Aufrufer über eine Deprecation warnen muss, schauen sie sich den Traffic an. Ein Agent, der sich selbst identifiziert, erhält die E-Mail; einer, der eine Standard-Bibliothekszeichenfolge sendet, nicht.

Wenn Sie die API besitzen, veröffentlichen Sie eine Version und halten Sie sie. Unser Leitfaden zur besten API-Versionsstrategie behandelt die Optionen, und das Verwalten von API-Versionierung in Apidog behandelt das gleichzeitige Betreiben mehrerer Live-Versionen.

Für Drittanbieter-APIs ohne jegliche Versionierung, legen Sie fest, was Sie können: Erfassen Sie die Antwortstruktur, gegen die Sie entwickelt haben, und überprüfen Sie sie, was im nächsten Abschnitt behandelt wird.

Drift erkennen, bevor ein Lauf es tut

Das Festlegen kauft Zeit. Es stoppt nicht das eventuelle Upgrade und nützt nichts bei APIs, die sich ohne Versionierung ändern. Also: Erkennen.

Spezifikation regelmäßig abgleichen. Wenn der Anbieter ein OpenAPI-Dokument veröffentlicht, holen Sie es täglich ab und vergleichen Sie es mit der Kopie, aus der Sie Tools generiert haben. Entfernte Felder, geänderte Typen, hinzugefügte Anforderungen, erweiterte Enums, bearbeitete Beschreibungen. In Apidog können Sie die importierte Definition im Projekt behalten und sehen, was sich zwischen den Versionen geändert hat, was "hat sich etwas geändert" zu einem Bericht anstatt einer Untersuchung macht.

Kontrakttest der Endpunkte, die Sie aufrufen. Senden Sie für jedes Tool, das der Agent hat, eine bekannte gute Anfrage und überprüfen Sie die Antwortstruktur: erforderliche Felder vorhanden, korrekte Typen, Enum-Werte innerhalb des erwarteten Bereichs. Dies fängt Drift in APIs ab, die überhaupt keine Spezifikation veröffentlichen, was die meisten sind. Unser Leitfaden zum API-Kontrakttest behandelt das Muster, und der bidirektionale Kontrakttest behandelt das Ausführen von beiden Seiten.

Form zur Laufzeit prüfen. Validieren Sie Antworten im Tool-Wrapper gegen das erwartete Schema und protokollieren Sie eine Warnung, wenn etwas Unerwartetes auftritt. Dies ist die letzte Linie und diejenige, die die Änderung abfängt, die niemand angekündigt hat.

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. Ein fehlendes erforderliches Feld bedeutet, dass der Agent mit unvollständigen Daten arbeiten wird, was ein Fehler ist, für den es sich lohnt, anzuhalten. Neue Felder sind normalerweise additiv und es lohnt sich, sie zu kennen, ohne einen Lauf zu unterbrechen. Leiten Sie beides in den Trace-Eintrag weiter, der in unserem Beitrag zum Tracing von Agenten-Tool-Aufrufen beschrieben wird.

Verhalten beobachten, nicht nur Schemas. Einige Abweichungen sind für eine Formprüfung unsichtbar: ein geänderter Standardwert, eine verschärfte Ratenbegrenzung, eine langsamer gewordene Antwort. Verfolgen Sie Aufrufe pro abgeschlossener Aufgabe, Wiederholungsrate pro Endpunkt und durchschnittliche Antwortgröße pro Tool. Eine sprunghafte Änderung in einem davon bedeutet normalerweise, dass sich etwas stromaufwärts bewegt hat.

Upgrade ohne den Agenten zu stören

Wenn Sie auf eine neue Version umsteigen, behandeln Sie es als eine Änderung am Agenten, denn das ist es auch.

Generieren Sie die Tools neu, anstatt sie manuell zu bearbeiten, damit Beschreibungen und Schemas zusammenpassen. Lesen Sie dann den Diff der generierten Tool-Definitionen. Dieser Diff ist der tatsächliche Auswirkungsbereich und oft kleiner oder größer, als das API-Änderungsprotokoll andeutet.

Führen Sie den Agenten gegen einen Mock der neuen Version aus, bevor Sie ihn auf etwas Live-Ähnliches richten. Dies ist der wertvollste Schritt und derjenige, der am häufigsten übersprungen wird: Ein Mock, der aus der neuen Spezifikation erstellt wurde, ermöglicht es Ihnen, Ihre gesamte Task-Suite risikofrei gegen die neuen Formen auszuführen, gemäß unserem Beitrag zum Ausführen von Agenten gegen Mocks statt Produktion.

Führen Sie die Auswahl-Suite erneut aus. Änderungen an der Beschreibung verschieben, welches Tool das Modell auswählt, und diese Regression ist für einen Schema-Diff unsichtbar. Überprüfen Sie die Tool-Auswahl für eine feste Reihe von Prompts, wie in unserem Leitfaden zum Testen nicht-deterministischer Agenten beschrieben.

Führen Sie die Einführung hinter einem Feature-Flag durch, auf einem Teil des Datenverkehrs, wobei die alte Version noch fest verankert und bereit ist. Beobachten Sie die gleichen vier Zahlen einen Tag lang. Agenten-Regressionen zeigen sich als mehr Aufrufe pro Aufgabe und mehr Wiederholungen, lange bevor jemand eine Beschwerde einreicht.

Drei Drifts, die es in die Produktion schafften

Das umbenannte Feld. Die Eröffnungsgeschichte. Ein 200 bei jedem Anruf, leere Namen in jedem Datensatz, zwei Wochen später von einem Menschen entdeckt, der einen Bericht las. Eine Laufzeit-Formprüfung der Antwort hätte es beim ersten Anruf erkannt, weil das Feld, das der Agent zurücklesen sollte, verschwunden war.

Die verschärfte Standardeinstellung für die Paginierung. Ein Anbieter reduzierte die Standard-Seitengröße von 100 auf 20. Der Agent sandte nie ein limit, so dass er begann, 20 Datensätze zu sehen und sie als vollständige Menge zusammenzufassen. Es gab keine Fehlermeldung. Die Zusammenfassungen waren einfach falsch, auf eine Weise, die selbstbewusst wirkte. Die Lösung war eine Zeile, das Senden eines expliziten limit, und die Lektion ist allgemeiner: Verlassen Sie sich auf Standardwerte, und Sie haben eine unerklärte Abhängigkeit von der Entscheidung eines anderen.

Der neue Enum-Wert. Eine Zahlungs-API fügte status: "disputed" hinzu. Typisierte Clients ignorierten es. Der Agent überlegte, entschied, dass eine strittige Belastung als Rückerstattung zählte, und meldete abgeglichene Bücher, die es nicht waren. Eine explizite Enum-Validierung hätte bei dem unbekannten Wert einen Fehler ausgelöst, anstatt das Modell ihn interpretieren zu lassen.

Das Muster: Jede Änderung wurde angekündigt, jede war laut Klassifizierung des Anbieters additiv oder geringfügig, und jede war für einen Agenten störend. Diese Lücke ist das, worum man herumplanen muss.

Veraltetheit als Arbeitsaufgabe behandeln

Anbieter warnen Sie in der Regel. Die Warnung kommt in einem Changelog, einer E-Mail oder einem Deprecation-Header in der Antwort an, und es ist leicht, dass keine davon die Person erreicht, die den Agenten wartet.

Integrieren Sie sie in Ihre normale Warteschlange. Der Deprecation-Header und der Sunset-Header sind beide standardisiert, sodass eine generische Prüfung bei allen Anbietern funktioniert. Protokollieren Sie sie, wenn sie erscheinen, und alarmieren Sie beim ersten Auftreten statt beim tausendsten. Ein Header, der heute bei 3 Prozent der Aufrufe auftaucht, ist am Sunset-Datum ein vollständiger Ausfall.

Führen Sie auch ein Inventar: welcher Agent, welcher Anbieter, welche Version, welche Endpunkte und wer dafür verantwortlich ist. Zehn Zeilen in einer Datei reichen aus. Wenn eine Deprecation-Meldung eintrifft, sollte die Frage „betrifft uns das?“ eine Minute dauern, nicht einen Nachmittag mit Grepping.

Drift ist Arbeit, also gib ihr einen Besitzer

Die Erkennung erzeugt eine Warteschlange: einen Spezifikations-Diff, einen fehlschlagenden Kontrakttest, einen erstmals gesehenen Deprecation-Header. Jeder ist eine kleine Arbeitsaufgabe mit einer Frist, und der Fehlermodus besteht darin, dass er in einem Kanal liegt, den niemand besitzt, bis das Sunset-Datum erreicht ist.

Legen Sie sie dorthin, wo Ihr Team bereits Arbeit verfolgt. Wenn Ihre Agenten als Coding-Runtimes und nicht als von Ihnen bereitgestellter Dienst laufen, kann die Verwaltungsplattform den Kreis schließen: Sharkly weist einem Agenten oder einer Crew eine Aufgabe zu und hält das Ziel, die Ausführungsverfolgung und die Überprüfung an einem Ort, so dass „die Zahlungs-API diesen Endpunkt als veraltet markiert hat“ zu einer zugewiesenen Aufgabe mit einem Ergebnis wird, anstatt einer Nachricht in einem Thread. Was auch immer Sie verwenden, die Regel ist dieselbe. Eine Drift-Warnung ohne Besitzer ist eine Veraltetheit, der Sie am Tag des Ausfalls wieder begegnen werden.

Eine Checkliste

• Jede Anfrage sendet eine explizite API-Version und einen identifizierenden User-Agent.
• Spezifikationsdokumente von Drittanbietern werden regelmäßig abgerufen und abgeglichen.
• Jedes Tool, das der Agent aufrufen kann, verfügt über einen Kontrakttest, der die Antwortform überprüft.
• Tool-Wrapper validieren Antworten zur Laufzeit: Fehlschlagen bei fehlenden, warnen bei neuen.
• Verhaltensmetriken werden pro Endpunkt verfolgt, damit stille Drift sichtbar wird.
• Versions-Upgrades generieren Tools neu, anstatt sie manuell zu bearbeiten.
• Die Task-Suite und die Auswahl-Suite werden beide zuerst gegen einen Mock der neuen Version ausgeführt.
• Das Rollout ist gekennzeichnet und reversibel, wobei die vorherige Version weiterhin fest verankert ist.

Das API-Team wird weiterhin Änderungen veröffentlichen, und das ist in Ordnung. Was Sie brauchen, ist, dass Ihr Agent ein Client ist, der Änderungen bemerkt, wofür eine Versions-Pin, ein Kontrakttest und eine Laufzeit-Formprüfung erforderlich sind. Laden Sie Apidog herunter, um die Spezifikation abzugleichen und die nächste Version zu mocken, bevor sie in den Live-Betrieb geht.

Häufig gestellte Fragen

Wie oft sollte ich eine Drittanbieter-Spezifikation auf Änderungen überprüfen? Täglich reicht für die meisten aus und ist günstig zu automatisieren. Für APIs ohne veröffentlichte Spezifikation sollten Sie stattdessen auf in CI laufende Kontrakttests setzen, da diese denselben Drift von außen erkennen.

Sollte ich immer auf die älteste funktionierende Version festlegen? Nein. Legen Sie fest, damit Upgrades bewusst erfolgen, und führen Sie dann Upgrades nach einem Zeitplan durch. Das Verharren auf einer alten Version, bis sie entfernt wird, verwandelt eine geplante Änderung in einen Notfall.

Was, wenn der Agent nach einer Änderung einwandfrei funktioniert? Überprüfen Sie, anstatt anzunehmen. Die gefährlichen Ergebnisse sind diejenigen, die immer noch 200 zurückgeben, wie ein umbenanntes Feld, das stillschweigend verworfen wird. Eine Formprüfung sagt Ihnen, was ein erfolgreicher Lauf nicht kann.

Muss ich meine eigene API für Agenten anders versionieren? Nicht anders, aber strenger. Behandeln Sie neue erforderliche Felder, neue Enum-Werte und geänderte Standardwerte als brechend für Agenten-Konsumenten, auch wenn sie für typisierte Clients additiv sind, und kündigen Sie sie auf dieselbe Weise an.

Woher weiß ich, welche Agenten welche Endpunkte aufrufen? Aus Ihren Traces. Toolname plus Endpunkt pro Lauf ergibt die Abhängigkeitskarte und sagt Ihnen genau, wer von einer Veralterung betroffen ist. Unser Beitrag zum Tracing von Agenten-Tool-Aufrufen behandelt die Datensatzform.

Kann sich der Agent selbst an eine geänderte API anpassen? Manchmal, und Sie sollten sich nicht darauf verlassen. Ein Modell, das um ein fehlendes Feld herum improvisiert, erzeugt eine plausible Ausgabe, ohne dass ein Signal für einen Fehler vorliegt. Brechen Sie lautstark ab und beheben Sie stattdessen die Tools.