KI Agenten Testen: APIs aufrufen ohne Datenverlust

Ein KI-Code-Agent führte ein Skript aus, sah, wie es erfolgreich war, und sah dann, wie eine Produktionsdatenbanktabelle verschwand. Der Hacker News-Post-Mortem ging viral mit einem prägnanten Titel: „KI hat Ihre Datenbank nicht gelöscht, das haben Sie getan.“ Der Punkt traf, weil er stimmt. 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 anhä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 Token, bevor es jemandem auffiel. Andere Oberfläche, gleiche Fehlerklasse. Das Problem ist nicht, dass das Modell dumm ist. Das Problem ist, dass niemand die API getestet hat.

TL;DR

Agenten versagen 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: Testen Sie die Tool-Definitionen des Agenten mit Ihrer OpenAPI-Spezifikation, betreiben Sie einen Mock-Server für destruktive Endpunkte, erzwingen Sie Budgets und Idempotenzschlüssel pro Agent und wiederholen Sie Fehlerszenarien in CI. Apidog bietet Ihnen den OpenAPI-Import, Mocks und den Szenario-Runner, um all dies aus einem Projekt zu erledigen.

Einleitung

Vor einem Jahr bedeutete „KI-Agent 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 auf Ihre APIs, und Ihre APIs kommunizieren mit echten Datenbanken, Zahlungsabwicklern und Drittanbieterdiensten. Eine schlechte Tool-Definition oder eine fehlende Ratenbegrenzung ist kein stilistisches Problem. Es ist ein Produktionsvorfall, der Ihren Namen trägt.

Die virale Hacker News-Geschichte dieses Monats erfasste die Verschiebung. Der Autor argumentierte, dass die KI die Datenbank nicht gelöscht habe; der Mensch tat es, indem er dem Agenten Schreibzugriff gab, 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.“ Einige Wochen zuvor beschrieb ein Reddit-Beitrag eine Abrechnungsschleife, bei der ein Agent einen fehlgeschlagenen Anruf so oft wiederholte, dass die Rechnung über 800 Euro stieg, bevor es jemand bemerkte. Gleiche Ursache: Vertrauen wurde in die falsche Schicht gelegt.

Das können Sie beheben. Die Modellebene ist wichtig, aber die API-Ebene ist der Ort, an dem Sie die Blutung stoppen. Dieser Artikel zeigt Ihnen, wie Sie API-Integrationen von KI-Agenten End-to-End testen. Wir werden die vier Schutzvorkehrungen behandeln, die jede Agenten-API-Einrichtung benötigt, einen Schritt-für-Schritt-Apidog-Workflow zum Mocken destruktiver Endpunkte durchgehen und mit fortgeschrittenen Techniken wie Schema-Drift-Erkennung und Dual-Key-Trennung abschließen. 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 Schritte des Mock-Servers 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 Sie Prompt Injection. 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 bauen, die delete_all=true nicht einem Token aus einer Benutzerkontext-Sitzung aussetzt. OWASP nennt dies LLM01 in seinen LLM Top 10, und die Abhilfemaßnahme ist API-seitige Autorisierung, nicht Prompt Engineering.

Nehmen Sie fehlerhafte Tool-Schemas. Ihre OpenAPI-Spezifikation besagt, dass amount eine ganze Zahl in Cents ist. Die Tool-Definition des Agenten besagt, dass amount ein Float in Dollar ist. Drei Monate später erstattet jemand eine 19-Cent-Gebühr als 19 Dollar, und Sie erfahren vom Buchhalter von der Diskrepanz. Das Modell lag nicht falsch; das Modell verwendete das Schema, das Sie ihm gaben. Das Schema wich von der API ab. Niemand hat den Vertrag getestet.

Nehmen Sie fehlende Ratenbegrenzungen. Ein Agent in einer Wiederholungsschleife bombardiert Ihren transaktionalen E-Mail-Endpunkt tausendmal in zwei Minuten, weil der Planer des Agenten den Schritt immer wieder als „noch nicht erfolgreich“ markiert hat. Jede Wiederholung kostet Geld. Jede Wiederholung reiht eine echte E-Mail ein. Bis Sie aufwachen, hat Ihr Anbieter Ihr Konto gesperrt und Ihre Kunden werden mit Spam überflutet. Das Modell war nicht böswillig. Das Modell arbeitete mit einem Tool, das keine Obergrenze hatte.

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

Der gemeinsame Nenner: In 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 zusammenbricht, schauen Sie zuerst auf den API-Vertrag, dann auf das Agenten-Harness und fast nie auf das Modell selbst. Diese Neuausrichtung ist wichtig, weil sie Ihnen sagt, wo Sie investieren sollen. 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 versagen, von Setups, die teuer versagen. 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 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 und eingefügt. Diese beiden Artefakte driften ständig auseinander. Vertragstests lassen Ihren CI-Build fehlschlagen, sobald sie abweichen.

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]:
    """Gibt eine Liste von Diskrepanzfehlern zurück, leere Liste = erfolgreich."""
    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 fehlt erforderliches Feld: {missing}")
    for extra in tool_props - api_props:
        errors.append(f"Tool definiert Feld, das nicht in der API vorhanden ist: {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"Typ-Fehler bei {prop}: API={api_def.get('type')} "
                    f"Tool={tool_def_prop.get('type')}"
                )
    return errors

Führen Sie dies bei jeder PR aus, die entweder die OpenAPI-Spezifikation oder die Tool-Definitionen betrifft. Lassen Sie den Build fehlschlagen, wenn die Liste nicht leer ist. Diese einzelne Überprüfung hätte den Fehler mit Float vs. Cents im vorherigen Abschnitt Monate vor jeder 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 ändert, hat ein Mock-Äquivalent, das die gleiche Antwortform zurückgibt, ohne die Arbeit zu erledigen. Ihre Agenten-Entwicklungsschleife 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 aus, 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. Weitere Informationen zu diesem umfassenderen Muster finden Sie unter 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. Jede Löschung 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: 'Fehlender 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 sie bei Wiederholungen wieder. Ihre API gibt die zwischengespeicherte Antwort beim zweiten Aufruf zurück, anstatt zweimal abzurechnen. Dieses Muster schützt auch vor Doppelsendungen in Messaging-APIs, doppelten Zeilen in CRMs und den meisten anderen Szenarien, bei denen „der Agent hat es wiederholt und jetzt haben wir ein Durcheinander“.

4. Budget-Obergrenzen pro Agent

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 Reddit-Vorfall mit 800 Euro geschah, weil niemand eine Obergrenze für eine außer Kontrolle geratene Schleife festgelegt hatte, und als der Mensch nachsah, war der Schaden bereits angerichtet.

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

• Token pro Sitzung, begrenzt auf 50.000
• API-Aufrufe pro Minute, begrenzt auf 30
• Kumulative Ausgaben in Cents, begrenzt auf 500
• Tool-Aufruf-Tiefe, begrenzt auf 10 verschachtelte Aufrufe

Wenn ein Limit erreicht wird, wird HTTP 429 mit einem strukturierten Retry-After und einem X-Budget-Exceeded-Header zurückgegeben, der das Limit benennt. Der Planer des Agenten kann dann entweder einen Menschen einschalten oder die Aufgabe zurücknehmen. Kombinieren Sie dies mit Logging, damit Sie sehen können, welche Agenten an die Grenzen stoßen, und passen Sie entsprechend an.

Diese vier Kontrollen ergänzen sich. 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 hat einen 429-Fehler erhalten, 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 Test-Workflow für Agenten-APIs 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 analysiert jeden Pfad, jedes Schema und jedes Beispiel und erstellt entsprechende Endpunkte im Projekt. Falls 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 Leitfaden für den Design-First-API-Workflow führt Sie durch diesen Prozess, falls Sie ganz von vorne beginnen.

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

Finden Sie jeden Endpunkt, der Daten ändert: POST, PUT, PATCH, DELETE. Klicken Sie für jeden Endpunkt darauf und fügen Sie eine Mock-Antwort hinzu. Apidog kann realistische Mocks automatisch aus Ihrem Schema generieren, aber Sie sollten die Feldwerte überschreiben, damit sie wie Testdaten und nicht wie Produktionsdaten aussehen. Verwenden Sie Präfixe wie mock_user_ und Zeitstempel aus dem Jahr 1970, damit jede Datenlecks 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 Basis-URL der API Ihres Agenten während der Entwicklung auf den Mock-Server. Nun gibt Ihr DELETE /users/{id} einen 200er-Status mit einer gefälschten Benutzer-Payload zurück, und Ihre echte Datenbank ist sicher.

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

Apidog-Szenarien ermöglichen es Ihnen, API-Aufrufe mit Assertionen zu verketten, ähnlich wie bei einer Testsuite. Für einen Agenten, der Support-Tickets triagiert, könnte das Szenario wie folgt aussehen:

1. POST /auth/token mit Testanmeldeinformationen, den 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 „zugewiesen an“ 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 passt, schlägt das Szenario fehl, und Sie wissen es, bevor der Agent jemals in Produktion geht. Weitere Informationen zum umfassenderen Szenario-Test-Playbook finden Sie unter 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 jedem CI-Runner ausführt. Der Befehl sieht aus wie apidog run -t scenario-id --env test. Verknüpfen Sie ihn mit Ihrer PR-Pipeline, 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 upgraden 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 und erfassen Sie die Spur. Führen Sie es erneut mit Modell B aus und erfassen Sie die Spur. Vergleichen Sie die Anforderungsbodies. Überraschungen zeigen sich sofort: Modell B übergibt einen anderen priority-Wert, lässt ein Feld aus oder verwendet ein anderes Format für Daten. Sie fangen Verhaltensabweichungen ab, bevor sie ausgeliefert werden. Dies ist eines der Muster, die in der GPT-5.5 API-Integration behandelt werden, wo die Bewertung neuen Modellverhaltens ein wiederkehrendes Bedürfnis ist.

Der gesamte Workflow dauert etwa eine Stunde für die Ersteinrichtung und danach Minuten pro Lauf. Der Vorteil ist, dass jede Änderung an Ihrer API oder Ihren Agenten-Tools gegen dieselbe Erwartungsbasis geprüft wird.

Fortgeschrittene Techniken und Profi-Tipps

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

Temperatur in Tests auf Null setzen. Nicht-deterministische Agenten führen zu nicht-deterministischen Testfehlern. Wenn Sie das Verhalten von Tool-Aufrufen testen, setzen Sie die Temperatur auf 0 und seeden Sie alle Zufallsquellen. Sie testen die Tool-Schicht, nicht die Kreativitätsschicht.

Tool-Aufruf-Traces schnappschussartig erfassen. Jeder Testlauf zeichnet die exakte Reihenfolge der Tool-Aufrufe des Agenten mit Argumenten auf. Vergleichen Sie dies mit der vorherigen Baseline. Wenn der Agent plötzlich anfängt, /users zweimal statt einmal aufzurufen, möchten Sie das sofort wissen und 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.

API-Schlüssel für Lese- und Schreibzugriff trennen. Die meisten Agentenaufgaben sind hauptsächlich leseorientiert. Geben Sie dafür schreibgeschützte Schlüssel aus. Schreibschlüssel sind für Aufgaben reserviert, die Genehmigungsschranken durch Menschen erfordern. Diese einzelne Änderung halbiert den Schadenbereich eines kompromittierten Agenten.

Verwenden Sie HTTP 423 Locked für Endpunkte, die eine menschliche Genehmigung erfordern. 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 erkennt den gesperrten Zustand, zeigt die URL einem Menschen an und wartet. Dies ist sauberer als ein 403-Fehler, da 403 impliziert „Sie können das nicht tun“, während 423 impliziert „Sie können das noch nicht tun.“

Bei Schema-Drift fehlerhaft schließen. Wenn die Tool-Definition des Agenten nicht mit Ihrer OpenAPI-Spezifikation übereinstimmt, schlägt der Build fehl. Geben Sie keine Warnung aus. Geben Sie einen Fehler aus. Die Kosten für ein paar zusätzliche fehlgeschlagene Builds sind viel geringer als ein Produktionsvorfall.

Häufige Fehler, die vermieden werden sollten:

• Hartcodieren der Mock-URL in Agenten-Prompts. Verwenden Sie Umgebungsvariablen, damit derselbe Prompt gegen Mock-, Staging- und Produktionsumgebungen läuft.
• Überspringen der Idempotenz bei „kleinen“ Endpunkten. Jeder Schreibvorgang benötigt sie. Das Senden von E-Mails ist keine Ausnahme.
• Protokollieren vollständiger Anfragekörper in der Produktion. PII gelangt in Ihren Observability-Stack. Redigieren Sie Token, E-Mails und Bezeichner, bevor sie die Protokolle erreichen.
• Agenten direkten Datenbankzugriff gewähren. Gehen Sie immer über die API. Die API ist der Ort, an dem Ihre Tests leben.
• Dem Vertrauensscore des Agenten vertrauen. Der Score spiegelt die Modellsicherheit bezüglich der Antwort wider, nicht die API-Sicherheit. Ein zu 99 Prozent selbstbewusster Agent kann immer noch den falschen Endpunkt aufrufen.

Wenn Ihr Agent mit internen Diensten kommuniziert, die nicht hinter einem einzigen API-Gateway liegen, decken Microservices-Testmuster ab, wie Szenariotests über Dienste hinweg verteilt werden können.

Alternativen und Werkzeuge

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

Die ehrliche Zusammenfassung: Wenn Sie in LangSmith leben, bleiben Sie bei dem, was auf der Agenten-Seite funktioniert, und fügen Sie eine separate API-Testschicht hinzu. Wenn Sie Postmans Preismodell oder sein Mock-Modell entwachsen sind, 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 verbringen Sie 80 Prozent Ihrer Agenten-API-Testzeit.

Einige Teams kombinieren diese Ansätze. Sie behalten LangSmith für Auswertungen auf Prompt-Ebene und verwenden Apidog für API-seitige Vertragstests und Szenario-Wiederholungen. Das funktioniert gut; die Tools bedienen unterschiedliche Schichten.

Anwendungsfälle aus der Praxis

Agent aktualisiert Produktionsdatenbankzeilen. Ein Kundenerfolgsteam hat einen Agenten entwickelt, der Kontofelder aus Support-Tickets aktualisiert. Vor der Einführung haben sie jeden Schreibendpunkt so konfiguriert, dass er einen Idempotenzschlüssel erforderte, und 200 Szenario-Wiederholungen in Apidog gegen eine Sandbox-Datenbank durchgeführt. Die Wiederholungen deckten zwei Fälle auf, in denen der Agent versuchte, subscription_status auf eine Zeichenfolge zu setzen, die 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 harte Grenzen: maximal 5 Rückerstattungen pro Sitzung, maximal 50 Dollar pro Rückerstattung, Idempotenz bei jedem Aufruf erforderlich. Sie führten die Vertragstestsuite gegen Stripes OpenAPI bei jeder PR aus. Nach sechs Monaten haben sie 12.000 Rückerstattungen mit null doppelten Abbuchungen bearbeitet.

Agent triagiert GitHub-Issues. Ein Plattformteam hat einen Issue-Triage-Agenten entwickelt, inspiriert von Clawsweeper. Sie haben die GitHub-API in Apidog gemockt, den Agenten durch 50 Szenariotests für Edge-Fälle (gelöschte Issues, fehlende Labels, fehlerhafte Benutzereingaben) laufen lassen und drei Abstürze vor dem Launch gefunden. Der Agent kümmert sich jetzt um die Triage in einem öffentlichen Repository mit 5.000 offenen Issues.

Fazit

Wenn Sie eine Sache aus diesem Leitfaden mitnehmen, dann diese: Der Agent ist nicht das Problem. Die API ist das Problem, oder 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.
• Mocken Sie destruktive Endpunkte für jeden Agenten-Entwicklungszyklus.
• Fordern Sie Idempotenzschlüssel bei jedem Schreibvorgang an, den Ihr Agent aufrufen kann.
• Setzen Sie pro-Agenten-Budget-Obergrenzen, die im Fehlerfall geschlossen werden.
• Wiederholen Sie Szenarien bei jeder PR, die 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 einen dieser Fehlermodi erleben. 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 QA-Team-Perspektive zu diesem Problem siehe API-Test-Tools 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.

FAQ

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

Führen Sie Ihren Agenten während der Entwicklung gegen einen Mock-Server aus. Apidogs Mock-URLs 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 zu den Kosten des Mock-Servers ausführen, die null betragen. Eine vollständige Einrichtung finden Sie in der Test-Checkliste des QA-Ingenieurs.

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

Agententests prüfen, ob das Modell das richtige Tool auswählt und die Argumente korrekt ausfüllt. API-Tests prüfen, ob der Endpunkt korrekt funktioniert, wenn er aufgerufen wird. 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 aus. Sie müssen beide Schichten separat testen.

Benötige ich Idempotenzschlüssel für jeden Endpunkt?

Ja, für jeden Schreib-Endpunkt. Lesezugriffe sind per Definition idempotent. Schreibzugriffe 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 500-Fehler erneut versucht und Sie keine doppelte Zeile erhalten.

Wie verhindere ich, dass Prompt Injection schlechte API-Aufrufe auslöst?

Verlassen Sie sich nicht allein auf die Prompt-Ebene. Die API muss die Autorisierung basierend auf dem ursprünglichen Benutzerkontext erzwingen, nicht auf der Anfrage des Agenten. Wenn eine Benutzerkontext-Sitzung 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 sagt. Die OWASP LLM Top 10 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 das richtige Budgetlimit für einen Agenten?

Beginnen Sie streng und lockern Sie mit Daten. Beginnen Sie mit 50.000 Token pro Sitzung, 30 API-Aufrufen pro Minute, 5 Dollar pro Aufgabe. Beobachten Sie die Metriken zwei Wochen lang. Erhöhen Sie die Limits, die Sie berechtigterweise erreichen. Reduzieren Sie die Limits, die Sie nie erreichen. Monatlich überprüfen. 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 Schema-Drift zwischen den Tools meines Agenten und meiner API?

Führen Sie bei jeder PR einen Schema-Diff in CI aus. Vergleichen Sie die Tool-Definition des Agenten (JSON-Schema) mit dem OpenAPI-Request-Body-Schema für denselben Endpunkt. Lassen Sie den Build fehlschlagen, wenn sie abweichen. Der 30-zeilige Python-Snippet im Abschnitt „Schutzvorkehrungen“ oben tut dies; kopieren Sie ihn in Ihr Repository und binden Sie ihn in GitHub Actions ein.