KI Agenten testen: So vermeiden Sie Datenverlust beim API-Test

Ein KI-Programmieragent führte ein Skript aus, sah, wie es erfolgreich war, und beobachtete dann, wie eine Produktionstabellen-Datenbank verschwand. Der Hacker News Post-Mortem ging viral mit einem prägnanten Titel: „Die KI hat deine Datenbank nicht gelöscht, du hast es getan.“ Der Punkt traf, weil er wahr ist. Der Agent folgte einer Tool-Definition, das Tool traf einen echten Endpunkt, der Endpunkt hatte keine Schutzvorkehrungen, und ein Mensch hatte die Schlüssel an einen Prozess übergeben, der nicht inne hält, um zu fragen, ob `DELETE FROM users` verdächtig aussieht. Ein separater r/ClaudeAI-Thread erzählte eine ähnliche Geschichte aus einem anderen Blickwinkel: Ein Agent in einer Abrechnungsschleife verbrauchte Hunderte von Dollar an Tokens, bevor es jemand bemerkte. Andere Oberfläche, gleiche Fehlerklasse. Das Problem ist nicht, dass das Modell dumm ist. Das Problem ist, dass niemand die API getestet hat.

Kurz gesagt

Agenten scheitern in der Produktion, wenn ihre Tools keine API-seitigen Schutzvorkehrungen haben: fehlende Ratenbegrenzungen, keine Idempotenz, Hot-Deletes, fehlerhafte Schemas. Sie beheben dies mit vier Schritten: Vertragstests der Tool-Definitionen des Agenten gegen Ihre OpenAPI-Spezifikation, Betrieb eines Mock-Servers für destruktive Endpunkte, Erzwingen von pro-Agenten-Budget und Idempotenzschlüsseln und Wiederholung von Fehlerszenarien in CI. Apidog bietet Ihnen den OpenAPI-Import, Mocks und den Szenario-Runner, um all dies aus einem Projekt heraus zu erledigen.

Einleitung

Vor einem Jahr bedeutete „KI-Agenten testen“, Claude oder GPT aufzufordern und die Antwort zu bewerten. Das ist nicht mehr der Maßstab. Die heutigen Agenten rufen Funktionen auf, diese Funktionen treffen Ihre APIs, und Ihre APIs kommunizieren mit realen Datenbanken, Zahlungsabwicklern und Drittanbieterdiensten. Eine schlechte Tool-Definition oder eine fehlende Ratenbegrenzung ist kein stilistisches Problem. Es ist ein Produktionsvorfall, der auf Ihren Namen läuft.

Die virale Hacker News-Geschichte dieses Monats erfasste die Verschiebung. Der Autor argumentierte, dass die KI die Datenbank nicht gelöscht hat; der Mensch hat es getan, indem er dem Agenten Schreibzugriff gewährte, ohne Kontrollen zwischen dem Modell und den Daten zu platzieren. Der Thread explodierte, weil jeder Entwickler, der ihn las, gedacht hatte: „Das hätte ich fast ausgeliefert.“ Ein paar Wochen zuvor beschrieb ein Reddit-Beitrag eine Abrechnungsschleife, bei der ein Agent einen fehlgeschlagenen Aufruf so oft wiederholte, dass die Rechnung über 800 Euro stieg, bevor es jemand bemerkte. Gleiche Grundursache: Vertrauen in die falsche Schicht.

Sie können dies beheben. Die Modellebene ist wichtig, aber die API-Ebene ist der Ort, an dem Sie die Blutung stoppen. Dieser Artikel zeigt Ihnen, wie Sie die API-Integrationen von KI-Agenten End-to-End testen können. Wir behandeln die vier Schutzvorkehrungen, die jedes Agenten-API-Setup benötigt, führen einen Schritt-für-Schritt-Apidog-Workflow zum Mocking destruktiver Endpunkte durch und schließen mit fortgeschrittenen Techniken wie Schema-Drift-Erkennung und Dual-Key-Trennung ab. Sie werden mit konkreten Mustern gehen, die Sie noch heute in Ihr Repository kopieren können. Laden Sie Apidog herunter, bevor Sie beginnen, damit Sie die Mock-Server-Schritte mitverfolgen können.

Warum Agentenfehler wie API-Fehler aussehen

Liest man genug Agenten-Post-Mortems, zeigt sich ein Muster: Das Modell ist nicht der Protagonist. Die API ist es.

Nehmen wir die Prompt-Injektion. Ein Benutzer lädt ein PDF mit versteckten Anweisungen hoch, der Agent liest es, und der nächste Tool-Aufruf geht an Ihren /admin/users-Endpunkt mit delete_all=true. Das Modell hat dies nicht gewählt; es folgte Anweisungen, denen es keinen Grund hatte zu misstrauen. Die Lösung besteht nicht darin, den Prompt zu härten. Die Lösung besteht darin, eine API zu erstellen, die delete_all=true nicht einem Token aus einer Benutzerkontext-Sitzung aussetzt. OWASP nennt dies LLM01 in seinen LLM Top 10, und die Abhilfe ist API-seitige Autorisierung, nicht Prompt-Engineering.

Nehmen wir fehlerhafte Tool-Schemas. Ihre OpenAPI-Spezifikation besagt, dass amount eine Ganzzahl in Cent ist. Die Tool-Definition des Agenten besagt, dass amount eine Gleitkommazahl in Dollar ist. Drei Monate später erstattet jemand eine 19-Cent-Gebühr als 19 Dollar, und Sie erfahren von der Diskrepanz durch die Buchhaltung. Das Modell lag nicht falsch; das Modell verwendete das Schema, das Sie ihm gaben. Das Schema wich von der API ab. Niemand testete den Vertrag.

Nehmen wir fehlende Ratenbegrenzungen. Ein Agent in einer Wiederholungsschleife hämmert tausendmal in zwei Minuten auf Ihren Transaktions-E-Mail-Endpunkt, weil der Planer des Agenten den Schritt immer wieder als „noch nicht erfolgreich“ markierte. Jeder Wiederholungsversuch kostet Geld. Jeder Wiederholungsversuch stellt eine echte E-Mail in die Warteschlange. Wenn Sie aufwachen, hat Ihr Anbieter Ihr Konto gesperrt und Ihre Kunden werden mit Spam überflutet. Das Modell war nicht bösartig. Das Modell arbeitete mit einem Tool, das keine Obergrenze hatte.

Nehmen wir fehlende Idempotenz. Der Agent ruft POST /payments auf, um einen Kunden zu belasten, erhält ein Netzwerk-Timeout, versucht es erneut, weil der Planer den Aufruf für fehlgeschlagen hält, und jetzt wird der Kunde zweimal belastet. Die Agenten-Schicht kann nicht feststellen, ob der ursprüngliche Aufruf erfolgreich war; die API gab ihr keine Möglichkeit, dies zu erfragen. Idempotenzschlüssel lösen dies in fünf Zeilen Servercode, aber Sie müssen sie schreiben.

Der rote Faden: Bei jedem dieser Vorfälle tut der Agent genau das, was seine Tools ihm sagen. Die Tools sind die API. Wenn Sie also prüfen, wo die Zuverlässigkeit des Agenten versagt, schauen Sie zuerst auf den API-Vertrag, dann auf das Agenten-Harness und fast nie auf das Modell selbst. Dieses Umdenken ist wichtig, denn es sagt Ihnen, wo Sie investieren müssen. Sie brauchen kein intelligenteres Modell. Sie brauchen testbare APIs mit aktivierten Schutzvorkehrungen.

Die vier Schutzvorkehrungen, die jede Agenten-API-Integration benötigt

Vier Kontrollen trennen Agenten-Setups, die sicher scheitern, von solchen, die teuer scheitern. Wenn Sie in diesem Quartal nur Zeit haben, eine hinzuzufügen, beginnen Sie oben. Wenn Sie alle vier umsetzen können, haben Sie mehr als 90 Prozent der Vorfallsszenarien abgedeckt, die Sie im Jahr 2026 sehen werden.

1. Vertragstests für Tool-Schemas

Ihre OpenAPI-Spezifikation ist die einzige Quelle der Wahrheit für Ihre API. Ihr Agent hat eine separate Tool-Definition, oft handgeschrieben oder aus Dokumenten kopiert. Diese beiden Artefakte driften ständig auseinander. Vertragstests lassen Ihren CI-Build fehlschlagen, sobald sie divergieren.

Hier ist eine minimale Python-Prüfung, die eine Claude-ähnliche Tool-Definition gegen die Live-OpenAPI-Spezifikation validiert:

import json
from jsonschema import Draft202012Validator

def validate_tool_against_openapi(tool_def: dict, openapi_spec: dict) -> list[str]:
    """Return a list of mismatch errors, empty list = pass."""
    errors = []
    op = openapi_spec["paths"][tool_def["path"]][tool_def["method"].lower()]
    api_schema = op["requestBody"]["content"]["application/json"]["schema"]
    tool_schema = tool_def["input_schema"]

    api_props = set(api_schema.get("properties", {}).keys())
    tool_props = set(tool_schema.get("properties", {}).keys())

    for missing in api_props - tool_props:
        if missing in api_schema.get("required", []):
            errors.append(f"Tool missing required field: {missing}")
    for extra in tool_props - api_props:
        errors.append(f"Tool defines field not in API: {extra}")

    for prop, api_def in api_schema.get("properties", {}).items():
        if prop in tool_schema.get("properties", {}):
            tool_def_prop = tool_schema["properties"][prop]
            if api_def.get("type") != tool_def_prop.get("type"):
                errors.append(
                    f"Type mismatch on {prop}: API={api_def.get('type')} "
                    f"tool={tool_def_prop.get('type')}"
                )
    return errors

Führen Sie dies bei jedem PR aus, der entweder die OpenAPI-Spezifikation oder die Tool-Definitionen betrifft. Lassen Sie den Build fehlschlagen, wenn die Liste nicht leer ist. Diese einzige Prüfung hätte den Float-vs-Cents-Fehler im vorherigen Abschnitt Monate vor einer Rückerstattung entdeckt.

2. Sandbox- und Mock-Umgebungen für destruktive Endpunkte

Agenten brauchen einen Ort zum Üben. Sie sollten niemals in der Produktion üben. Das Muster ist unkompliziert: Jeder Endpunkt, der den Zustand verändert, hat ein Mock-Äquivalent, das die gleiche Form der Antwort zurückgibt, ohne die eigentliche Arbeit zu erledigen. Ihr Agenten-Entwicklungszyklus verwendet die Mocks. Ihre Staging-Tests verwenden eine Sandbox-Datenbank. Die Produktion bleibt unberührt, bis ein Mensch die Bereitstellung genehmigt.

Apidog generiert Mocks direkt aus der OpenAPI-Spezifikation, einschließlich realistischer Feldwerte, die von Faker-Mustern gesteuert werden. Sie richten die Basis-URL Ihres Agenten auf den Mock-Server, führen hundert Iterationen Ihres Prompts aus und beobachten, wie er sich verhält. Wenn der Agent immer wieder versucht, PUT an /users/{id}/delete zu senden, weil er die Dokumentation missverstanden hat, fängt der Mock dies ab. Die Benutzertabelle in der Produktion sieht den Fehler nie. Für das breitere Muster, in das dies passt, siehe Contract-First Development.

3. Idempotenzschlüssel und Soft-Deletes für irreversible Operationen

Jeder Schreib-Endpunkt, den Ihr Agent aufrufen kann, sollte einen Idempotenzschlüssel akzeptieren. Jeder Löschvorgang sollte standardmäßig ein Soft-Delete sein, mit einem separaten Hard-Delete-Pfad, den Menschen autorisieren.

Die Middleware sieht in Express so aus:

const idempotencyCache = new Map();

function idempotency(req, res, next) {
  const key = req.headers['idempotency-key'];
  if (!key) {
    return res.status(400).json({ error: 'Missing Idempotency-Key header' });
  }
  if (idempotencyCache.has(key)) {
    const cached = idempotencyCache.get(key);
    return res.status(cached.status).json(cached.body);
  }
  const originalJson = res.json.bind(res);
  res.json = function (body) {
    idempotencyCache.set(key, { status: res.statusCode, body });
    setTimeout(() => idempotencyCache.delete(key), 24 * 60 * 60 * 1000);
    return originalJson(body);
  };
  next();
}

app.post('/payments', idempotency, createPayment);

Der Agent generiert eine UUID pro logischer Operation und verwendet diese bei Wiederholungen wieder. Ihre API gibt die zwischengespeicherte Antwort beim zweiten Aufruf zurück, anstatt zweimal zu belasten. Dasselbe Muster schützt vor doppelten Sendungen in Messaging-APIs, doppelter Zeilenerstellung in CRMs und den meisten anderen Szenarien wie „Der Agent hat es erneut versucht und jetzt haben wir ein Chaos“.

4. Pro-Agenten-Budgetobergrenzen

Jeder Agent erhält ein Budget. Token-Budget, Anfrage-Budget, Dollar-Budget, Zeit-Budget. Wenn das Budget aufgebraucht ist, stoppt der Agent. Keine Ausnahmen. Der 800-Euro-Reddit-Vorfall ereignete sich, weil niemand eine Obergrenze für eine außer Kontrolle geratene Schleife festgelegt hatte, und als der Mensch es bemerkte, war der Schaden bereits angerichtet.

Eine Budget-Middleware, die Ihr API-Gateway umhüllt, könnte Folgendes verfolgen:

• Tokens pro Sitzung, begrenzt auf 50.000
• API-Aufrufe pro Minute, begrenzt auf 30
• Kumulative Ausgaben in Cent, begrenzt auf 500
• Tool-Aufruftiefe, begrenzt auf 10 verschachtelte Aufrufe

Wenn eine Obergrenze erreicht wird, geben Sie HTTP 429 mit einem strukturierten Retry-After und einem X-Budget-Exceeded-Header zurück, der die Obergrenze nennt. Der Planer des Agenten kann dann entweder einen Menschen einschalten oder die Aufgabe zurücknehmen. Kombinieren Sie dies mit Protokollierung, damit Sie sehen können, welche Agenten an die Grenzen stoßen, und entsprechend anpassen können.

Diese vier Kontrollen wirken zusammen. Vertragstests fangen die offensichtlichen Schemafehler ab. Mocks fangen die destruktiven ab. Idempotenz fängt die Wiederholungsstürme ab. Budgets fangen die außer Kontrolle geratenen Schleifen ab. Zusammen verwandeln sie „der Agent hat etwas Schreckliches getan“ in „der Agent ist auf einen 429er gestoßen, hat das Problem protokolliert und um Hilfe gebeten.“ Das ist der Maßstab.

API-Aufrufe von Agenten mit Apidog testen

Nun zum praktischen Teil. Hier erfahren Sie, wie Sie einen vollständigen Agenten-API-Test-Workflow in Apidog einrichten. Sie benötigen die OpenAPI-Spezifikation für die API, die Ihr Agent aufruft, sowie eine Liste der Tool-Definitionen des Agenten.

Schritt 1: Die OpenAPI-Spezifikation importieren

Öffnen Sie Apidog, erstellen Sie ein neues Projekt und importieren Sie Ihre OpenAPI 3.x-Datei. Apidog parst jeden Pfad, jedes Schema und jedes Beispiel und erstellt entsprechende Endpunkte im Projekt. Wenn Ihre API noch nicht in OpenAPI dokumentiert ist, ist dies der Moment, dies zu tun; die Zuverlässigkeit des Agenten hängt davon ab, eine einzige Quelle der Wahrheit zu haben, die sowohl Ihre Menschen als auch Ihre KI-Agenten lesen. Der Design-First API Workflow Guide führt Sie durch diesen Prozess, wenn Sie von Grund auf neu beginnen.

Schritt 2: Mock-Antworten für destruktive Endpunkte definieren

Suchen Sie jeden Endpunkt, der Daten verändert: POST, PUT, PATCH, DELETE. Für jeden klicken Sie auf den Endpunkt und fügen eine Mock-Antwort hinzu. Apidog kann realistische Mocks automatisch aus Ihrem Schema generieren, aber Sie sollten die Feldwerte überschreiben, damit sie wie Testdaten aussehen, nicht wie Produktionsdaten. Verwenden Sie Präfixe wie mock_user_ und Zeitstempel aus dem Jahr 1970, damit eventuelle Lecks in den Protokollen offensichtlich sind.

Starten Sie den Mock-Server. Apidog gibt Ihnen eine stabile URL wie https://mock.apidog.com/m1/your-project-id/. Richten Sie die API-Basis-URL Ihres Agenten während der Entwicklung auf den Mock-Server. Jetzt gibt Ihr DELETE /users/{id} eine 200 mit einem gefälschten Benutzer-Payload zurück, und Ihre reale Datenbank ist sicher. Siehe API-Tests für QA-Ingenieure für die breitere Szenario-Teststrategie.

Schritt 3: Ein Szenario schreiben, das die Aufrufsequenz des Agenten simuliert

Apidog-Szenarien ermöglichen es Ihnen, API-Aufrufe mit Zusicherungen zu verketten, genau wie eine Testsuite. Für einen Agenten, der Support-Tickets triagiert, könnte das Szenario sein:

1. POST /auth/token mit Testanmeldeinformationen, das Bearer-Token erfassen
2. GET /tickets?status=open mit dem Token, die erste Ticket-ID erfassen
3. POST /tickets/{id}/triage mit einer Kategorie, 200 bestätigen und das Feld `assigned-to` erfassen
4. POST /notifications mit einer Vorlagen-Nachricht, bestätigen, dass der Nachrichtentext einem Regex entspricht

Sie proben effektiv, was der Agent auf dem Mock-Server tun wird, mit Zusicherungen bei jedem Schritt. Wenn ein Entwickler das Ticket-Schema ändert und der Regex nicht mehr übereinstimmt, schlägt das Szenario fehl und Sie wissen es, bevor der Agent jemals die Produktion sieht. Für das breitere Playbook zum Szenario-Testen siehe API-Tests für QA-Ingenieure.

Schritt 4: Aus CI ausführen

Apidog liefert eine CLI, die Szenarien von einer GitHub Action, GitLab Pipeline oder einem beliebigen CI-Runner ausführt. Der Befehl lautet apidog run -t scenario-id --env test. Hängen Sie ihn an Ihre PR-Pipeline an, sodass jede Änderung an der OpenAPI-Spezifikation oder den Agenten-Tool-Definitionen eine vollständige Szenario-Wiederholung auslöst.

Schritt 5: Zwei Modellversionen nebeneinander vergleichen

Wenn Sie bewerten, ob Sie von einem Modell auf ein anderes aktualisieren sollen, möchten Sie wissen, ob die Tool-Aufrufe des neuen Modells in denselben Szenarien dasselbe Verhalten zeigen. Führen Sie den Agenten mit Modell A gegen dasselbe Apidog-Szenario aus, erfassen Sie den Trace. Führen Sie ihn erneut mit Modell B aus, erfassen Sie den Trace. Vergleichen Sie die Anfragetexte. Überraschungen zeigen sich sofort: Modell B übergibt einen anderen priority-Wert, lässt ein Feld weg oder verwendet ein anderes Datumsformat. Sie fangen Verhaltensabweichungen ab, bevor sie ausgeliefert werden. Dies ist eines der Muster, die in GPT-5.5 API-Integration behandelt werden, wo die Bewertung neuen Modellverhaltens ein wiederkehrendes Bedürfnis ist.

Der gesamte Workflow dauert beim ersten Mal etwa eine Stunde einzurichten und danach Minuten pro Ausführung. Der Vorteil ist, dass jede Änderung an Ihrer API oder Ihren Agenten-Tools gegen dieselbe Basis von Erwartungen ausgeführt wird.

Fortgeschrittene Techniken und Profi-Tipps

Einige Muster, die erfahrene Teams anwenden, nachdem die Grundlagen geschaffen sind.

Temperatur in Tests auf Null setzen. Nicht-deterministische Agenten erzeugen nicht-deterministische Testfehler. Wenn Sie das Tool-Aufrufverhalten testen, setzen Sie die Temperatur auf 0 und seeden Sie alle Zufallsquellen. Sie testen die Tool-Schicht, nicht die Kreativitätsschicht.

Tool-Aufruf-Traces aufzeichnen (Snapshot). Jede Testausführung zeichnet die genaue Sequenz der Tool-Aufrufe des Agenten mit Argumenten auf. Vergleichen Sie diese mit dem vorherigen Baseline. Wenn der Agent plötzlich anfängt, /users zweimal statt einmal aufzurufen, möchten Sie das sofort wissen, nicht drei Wochen später, wenn die Rechnung kommt.

Einem Agenten niemals Produktionszugangsdaten geben. Agenten erhalten aufgabenspezifische Service-Konten. Produktionszugangsdaten leben in Tresoren, nicht in `.env`-Dateien, die ein Agent lesen kann. Wenn ein Agent einen Produktionsendpunkt aufrufen muss, geschieht dies über einen Proxy, der Anfragen mit kurzlebigen Tokens signiert.

Separate Lese- und Schreib-API-Schlüssel. Die meisten Agentenaufgaben sind hauptsächlich Leseoperationen. Stellen Sie für diese Lese-Schlüssel bereit. Schreibschlüssel sind für Aufgaben reserviert, die menschliche Genehmigungsschranken haben. Diese einzige Änderung halbiert den Wirkungsbereich eines kompromittierten Agenten.

HTTP 423 Locked für Endpunkte mit menschlicher Genehmigung verwenden. Wenn ein Agent versucht, einen Endpunkt aufzurufen, der eine menschliche Bestätigung erfordert, geben Sie 423 mit einem confirmation_url-Feld zurück. Der Planer des Agenten sieht den gesperrten Zustand, zeigt die URL einem Menschen an und wartet. Dies ist sauberer als ein 403, da 403 „Sie können dies nicht tun“ impliziert, während 423 „Sie können dies noch nicht tun“ impliziert.

Bei Schemaabweichung geschlossene Fehler verursachen. Wenn die Tool-Definition des Agenten nicht mit Ihrer OpenAPI-Spezifikation übereinstimmt, schlägt der Build fehl. Versenden Sie keine Warnung. Versenden Sie einen Fehler. Die Kosten für ein paar zusätzliche fehlgeschlagene Builds sind viel geringer als ein Produktionsvorfall.

Häufige Fehler, die vermieden werden sollten:

• Die Mock-URL in Agenten-Prompts hartkodieren. Verwenden Sie Umgebungsvariablen, damit derselbe Prompt gegen Mock, Staging und Produktion läuft.
• Idempotenz bei „kleinen“ Endpunkten überspringen. Jeder Schreibvorgang benötigt sie. Der E-Mail-Versand ist keine Ausnahme.
• Vollständige Anfragetexte in der Produktion protokollieren. PII gelangen in Ihren Observability-Stack. Tokens, E-Mails und Bezeichner vor dem Protokollieren redigieren.
• Agenten direkten Datenbankzugriff gewähren. Immer über die API gehen. Die API ist der Ort, an dem Ihre Tests leben.
• Dem Konfidenz-Score des Agenten vertrauen. Der Score spiegelt die Modellsicherheit bezüglich der Antwort wider, nicht die API-Sicherheit. Ein 99 Prozent selbstbewusster Agent kann immer noch den falschen Endpunkt aufrufen.

Wenn Ihr Agent mit internen Diensten kommuniziert, die sich nicht hinter einem einzigen API-Gateway befinden, beschreibt Microservices-Testmuster, wie Szenario-Tests über Dienste hinweg verteilt werden können.

Alternativen und Tools

Sie haben Optionen. Hier ist ein fairer Vergleich der vier gängigen Ansätze.

Die ehrliche Zusammenfassung: Wenn Sie in LangSmith arbeiten, machen Sie auf der Agentenseite so weiter, wie es funktioniert, und fügen Sie eine separate API-Tests-Schicht hinzu. Wenn Sie die Preisgestaltung von Postman oder sein Mock-Modell überholt haben, ist Apidog ein starker Ersatz. Wenn Sie neu anfangen, wählen Sie das Tool, das OpenAPI, Mocks und Szenarien in einem Projekt handhabt, denn dort fließt 80 Prozent Ihrer Testzeit für Agenten-APIs hin.

Einige Teams kombinieren diese. Sie verwenden LangSmith für Bewertungen auf Prompt-Ebene und Apidog für die API-seitigen Vertragstests und Szenarienwiederholungen. Das funktioniert gut; die Tools bedienen unterschiedliche Schichten.

Anwendungsfälle aus der Praxis

Agent aktualisiert Produktionsdatenbankzeilen. Ein Kundenerfolgs-Team hat einen Agenten entwickelt, der Kontofelder aus Support-Tickets aktualisiert. Vor dem Start haben sie jeden Schreib-Endpunkt so konfiguriert, dass er einen Idempotenzschlüssel erforderte, und 200 Szenario-Wiederholungen in Apidog gegen eine Sandbox-Datenbank ausgeführt. Die Wiederholungen fingen zwei Fälle ab, in denen der Agent versuchte, subscription_status auf einen String zu setzen, der nicht im Enum enthalten war. Sie fügten eine Schema-Validierung hinzu und lieferten ohne Zwischenfälle aus.

Agent ruft eine Zahlungs-API auf. Ein Fintech-Team, das einen automatisierten Rückerstattungsagenten entwickelte, setzte strenge Obergrenzen: max. 5 Rückerstattungen pro Sitzung, max. 50 Dollar pro Rückerstattung, Idempotenz bei jedem Aufruf erforderlich. Sie führten die Vertragstest-Suite bei jedem PR gegen Stripes OpenAPI aus. Sechs Monate später haben sie 12.000 Rückerstattungen ohne doppelte Abbuchungen verarbeitet.

Agent triagiert GitHub-Issues. Ein Plattform-Team entwickelte einen Issue-Triage-Agenten, inspiriert von Clawsweeper. Sie simulierten die GitHub-API in Apidog, führten den Agenten durch 50 Szenario-Tests, die Randfälle abdeckten (gelöschte Issues, fehlende Labels, fehlerhafte Benutzereingaben), und fanden vor dem Start drei Abstürze. Der Agent übernimmt nun die Triage in einem öffentlichen Repository mit 5.000 offenen Issues.

Fazit

Wenn Sie nur eine Sache aus diesem Leitfaden mitnehmen, dann diese: Der Agent ist nicht das Problem. Die API ist das Problem, oder sie ist die Lösung, je nachdem, ob Sie sie getestet haben.

Fünf Erkenntnisse:

• Behandeln Sie Tool-Schemas als Verträge und führen Sie Vertragstests in CI aus.
• Simulieren Sie destruktive Endpunkte für jeden Agenten-Entwicklungszyklus.
• Verlangen Sie Idempotenzschlüssel bei jedem Schreibvorgang, den Ihr Agent aufrufen kann.
• Setzen Sie pro-Agenten-Budgetobergrenzen fest, die bei Überschreitung geschlossene Fehler verursachen.
• Spielen Sie Szenarien bei jedem PR ab, der die API oder die Tool-Definitionen betrifft.

Die viralen Vorfälle dieses Jahres werden nicht die letzten sein. Jedes Team, das Agenten ausliefert, wird mindestens einmal auf einen dieser Fehlermodi stoßen. Die Teams, die sich schnell erholen, sind diejenigen, die bereits die Schutzvorkehrungen getroffen hatten. Laden Sie Apidog herunter und beginnen Sie mit dem Mock-Server-Schritt; allein das wird Ihnen in diesem Quartal eine schlaflose Nacht ersparen. Für die Perspektive des QA-Teams zu diesem Problem siehe API-Testwerkzeuge für QA-Ingenieure. Für einen breiteren Kontext zum Schreiben von Tool-Definitionen, die Agenten sicher verwenden können, siehe wie man AGENTS.md-Dateien schreibt.

Häufig gestellte Fragen (FAQ)

Wie teste ich API-Aufrufe von KI-Agenten, ohne Geld für Tokens auszugeben?

Führen Sie Ihren Agenten während der Entwicklung gegen einen Mock-Server aus. Die Mock-URLs von Apidog liefern kostenlose, realistische Antworten, sodass Ihre Testschleifen keine echten API-Credits verbrauchen. Setzen Sie die Temperatur auf 0 und verwenden Sie einen kleinen, festen Prompt-Satz. Sie können Tausende von Testiterationen zum Preis des Mock-Servers ausführen, der null beträgt. Die Test-Checkliste des QA-Ingenieurs enthält die vollständige Einrichtung.

Was ist der Unterschied zwischen dem Testen des Agenten und dem Testen der API?

Agenten-Tests prüfen, ob das Modell das richtige Tool auswählt und die Argumente korrekt ausfüllt. API-Tests prüfen, ob der Endpunkt beim Aufruf korrekt funktioniert. Beides ist wichtig. Ein perfekter Agent, der eine fehlerhafte API aufruft, führt immer noch zu fehlerhaften Ergebnissen, und ein fehlerhafter Agent, der eine perfekte API aufruft, liefert immer noch Fehler. Beide Schichten müssen separat getestet werden.

Benötige ich Idempotenzschlüssel an jedem Endpunkt?

Ja, an jedem Schreib-Endpunkt. Leseoperationen sind per Definition idempotent. Schreiboperationen sind es nicht, und Agenten versuchen es erneut. Die fünf Zeilen Middleware zur Unterstützung eines Idempotenz-Headers zahlen sich beim ersten Mal aus, wenn der Agent einen 500er-Fehler wiederholt und Sie keine doppelte Zeile erhalten.

Wie verhindere ich, dass Prompt-Injektionen zu schlechten API-Aufrufen führen?

Verlassen Sie sich nicht allein auf die Prompt-Schicht. Die API muss die Autorisierung basierend auf dem ursprünglichen Benutzerkontext durchsetzen, nicht auf der Anfrage des Agenten. Wenn eine Benutzersitzung normalerweise nicht auf `/admin/delete-all-users` zugreifen kann, sollte der Agent, der im Namen dieses Benutzers handelt, dies auch nicht können, unabhängig davon, was der Prompt besagt. Die LLM Top 10 von OWASP behandelt dies ausführlich.

Kann ich Apidog direkt mit Claude oder GPT verwenden, ohne meine eigene Tool-Schicht zu schreiben?

Sie richten die Tool-Definitionen Ihres Agenten während des Tests auf die Apidog Mock-URL aus. Sowohl Claude als auch GPT unterstützen beliebige HTTP-Basis-URLs in ihren Tool-Definitionen, sodass der Wechsel eine Umgebungsvariable ist. Wenn Sie bereit sind, gegen Staging oder Produktion zu testen, ändern Sie die Variable.

Was ist die richtige Budgetobergrenze für einen Agenten?

Beginnen Sie streng und lockern Sie mit Daten. Beginnen Sie mit 50.000 Tokens pro Sitzung, 30 API-Aufrufen pro Minute, 5 Dollar pro Aufgabe. Beobachten Sie die Metriken zwei Wochen lang. Erhöhen Sie die Obergrenzen, die Sie legitim erreichen. Senken Sie die Obergrenzen, die Sie nie erreichen. Monatliche Überprüfung. Das Ziel ist keine feste Zahl; es ist eine Zahl, die eng genug ist, um außer Kontrolle geratene Schleifen abzufangen, und locker genug, um echte Arbeit zuzulassen.

Wie erkenne ich Schemaabweichungen zwischen den Tools meines Agenten und meiner API?

Führen Sie bei jedem PR einen Schema-Diff in CI aus. Vergleichen Sie die Tool-Definition des Agenten (JSON-Schema) mit dem OpenAPI-Anfragekörper-Schema für denselben Endpunkt. Schlagen Sie den Build fehl, wenn sie abweichen. Der 30-zeilige Python-Codeausschnitt im Abschnitt Schutzvorkehrungen oben tut dies; kopieren Sie ihn in Ihr Repository und binden Sie ihn in GitHub Actions ein.