DEV Community

Cover image for KI Agenten Testen: APIs aufrufen ohne Datenverlust
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

KI Agenten Testen: APIs aufrufen ohne Datenverlust

Ein KI-Code-Agent führte ein Skript aus, meldete Erfolg – und kurz danach war eine Produktionsdatenbanktabelle weg. Der Hacker-News-Post-Mortem wurde viral: „KI hat Ihre Datenbank nicht gelöscht, das haben Sie getan.“ Das trifft den Kern. Der Agent folgte einer Tool-Definition, das Tool traf einen echten Endpunkt, der Endpunkt hatte keine Schutzvorkehrungen, und ein Mensch hatte einem Prozess Schlüssel gegeben, der nicht innehält, wenn DELETE FROM users verdächtig aussieht. Ein r/ClaudeAI-Thread beschrieb dasselbe Muster aus einer anderen Richtung: Ein Agent geriet in eine Abrechnungsschleife und verbrauchte Hunderte 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.

Apidog noch heute ausprobieren

💡 Wenn Sie autonome Agenten ausliefern, die Ihre APIs aufrufen, ist dieser Leitfaden für Sie. Sie lernen, wie Sie externe Endpunkte während der Agentenentwicklung mocken, destruktive Operationen in einer Sandbox ausführen, Vertragstests für Tool-Schemas schreiben, pro-Agenten-Budgetlimits setzen und Fehlerfälle in CI proben. Wir verwenden Apidog als Testgerüst, weil es OpenAPI nativ unterstützt, Mock-Server ohne Glue-Code bereitstellt und Szenario-Tests bietet, die gut zu Tool-Call-Sequenzen von Agenten passen.

TL;DR

Agenten scheitern in Produktion selten „wegen KI“, sondern wegen fehlender API-Schutzvorkehrungen: keine Ratenbegrenzung, keine Idempotenz, direkte Löschoperationen, driftende Schemas. Der pragmatische Fix besteht aus vier Schritten:

  1. Tool-Definitionen gegen Ihre OpenAPI-Spezifikation testen.
  2. Destruktive Endpunkte mocken oder in einer Sandbox ausführen.
  3. Idempotenzschlüssel und Budgets pro Agent erzwingen.
  4. Fehler- und Wiederholungsszenarien in CI ausführen.

Apidog bündelt OpenAPI-Import, Mocks und Szenario-Runner in einem Projekt.

Einleitung

Vor einem Jahr bedeutete „KI-Agent testen“ oft: Prompt ausführen, Antwort lesen, Daumen hoch oder runter. Das reicht nicht mehr.

Heutige Agenten rufen Funktionen auf. Diese Funktionen treffen APIs. Diese APIs schreiben in Datenbanken, lösen Zahlungen aus, versenden E-Mails oder rufen Drittanbieter auf. Eine ungenaue Tool-Definition oder eine fehlende Ratenbegrenzung ist deshalb kein kosmetisches Problem. Es ist ein potenzieller Produktionsvorfall.

Die virale Hacker-News-Geschichte zeigt diese Verschiebung gut: Nicht „die KI“ löschte die Datenbank, sondern ein System, das einem Agenten Schreibzugriff gab, ohne Kontrollen zwischen Modell und Daten einzubauen. Der Reddit-Fall mit der 800-Euro-Abrechnungsschleife hatte dieselbe Ursache: Vertrauen wurde in die falsche Schicht gelegt.

Die API-Schicht ist der Ort, an dem Sie Agenten zuverlässig begrenzen können. In diesem Artikel bauen wir dafür ein umsetzbares Test-Setup:

  • Vertragstests für Tool-Schemas
  • Mock-Server für destruktive Endpunkte
  • Idempotenz und Soft-Deletes
  • Budgetlimits pro Agent
  • Szenario-Tests in CI
  • Schema-Drift-Erkennung und getrennte Schlüssel für Lese-/Schreibzugriff

Warum Agentenfehler wie API-Fehler aussehen

Wenn man Agenten-Post-Mortems liest, wiederholt sich ein Muster: Das Modell ist selten die eigentliche Fehlerquelle. Die API ist es.

Prompt Injection

Ein Benutzer lädt ein PDF mit versteckten Anweisungen hoch. Der Agent liest es und ruft anschließend Ihren /admin/users-Endpunkt mit delete_all=true auf.

Das Modell hat nicht „böse“ gehandelt. Es folgte Anweisungen, denen es keinen Grund hatte zu misstrauen.

Der Fix liegt nicht nur im Prompt. Der Fix ist API-seitige Autorisierung:

Ein Token aus einer normalen Benutzer-Session darf niemals delete_all=true ausführen.
Enter fullscreen mode Exit fullscreen mode

OWASP behandelt dieses Risiko in den LLM Top 10. Die relevante Gegenmaßnahme ist API-seitige Zugriffskontrolle, nicht nur Prompt-Härtung.

Driftende Tool-Schemas

Ihre OpenAPI-Spezifikation sagt:

{
  "amount": {
    "type": "integer",
    "description": "Betrag in Cents"
  }
}
Enter fullscreen mode Exit fullscreen mode

Die Tool-Definition des Agenten sagt:

{
  "amount": {
    "type": "number",
    "description": "Betrag in Dollar"
  }
}
Enter fullscreen mode Exit fullscreen mode

Drei Monate später wird eine Gebühr von 19 Cent als 19 Dollar erstattet. Das Modell hat das Schema verwendet, das Sie ihm gegeben haben. Der Vertrag war falsch.

Fehlende Ratenbegrenzung

Ein Agent interpretiert einen fehlgeschlagenen Schritt als „noch nicht abgeschlossen“ und ruft denselben E-Mail-Endpunkt tausendmal in zwei Minuten auf.

Das Ergebnis:

  • Anbieter sperrt das Konto
  • Kunden erhalten Spam
  • Kosten steigen
  • Logs sind voller Duplikate

Das Modell war nicht böswillig. Das Tool hatte keine Obergrenze.

Fehlende Idempotenz

Ein Agent ruft POST /payments auf. Der Server belastet den Kunden, aber die Verbindung bricht ab. Der Agent sieht einen Timeout und versucht es erneut.

Ohne Idempotenz:

1 logische Zahlung = 2 echte Abbuchungen
Enter fullscreen mode Exit fullscreen mode

Mit Idempotenz:

1 logische Zahlung = 1 Abbuchung + wiederholbare Antwort
Enter fullscreen mode Exit fullscreen mode

Der gemeinsame Nenner: Agenten tun, was ihre Tools erlauben. Ihre Tools sind API-Verträge. Wenn diese Verträge nicht getestet und begrenzt sind, wird der Agent früher oder später genau diese Lücken ausnutzen.

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

Wenn Sie nur wenig Zeit haben, implementieren Sie diese vier Kontrollen in dieser Reihenfolge.

1. Vertragstests für Tool-Schemas

Ihre OpenAPI-Spezifikation sollte die einzige Quelle der Wahrheit sein. Die Tool-Definition des Agenten ist ein abgeleitetes Artefakt. Wenn beide auseinanderlaufen, muss CI fehlschlagen.

Minimaler Python-Check:

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 not in tool_schema.get("properties", {}):
            continue

        tool_prop = tool_schema["properties"][prop]

        if api_def.get("type") != tool_prop.get("type"):
            errors.append(
                f"Typ-Fehler bei {prop}: API={api_def.get('type')} "
                f"Tool={tool_prop.get('type')}"
            )

    return errors
Enter fullscreen mode Exit fullscreen mode

Beispiel für CI-Logik:

errors = validate_tool_against_openapi(tool_def, openapi_spec)

if errors:
    for error in errors:
        print(f"Schema mismatch: {error}")
    raise SystemExit(1)
Enter fullscreen mode Exit fullscreen mode

Führen Sie diesen Check bei jeder PR aus, die eine dieser Dateien ändert:

  • openapi.yaml
  • openapi.json
  • Tool-Definitionen des Agenten
  • SDK- oder API-Client-Code

So erkennen Sie Fehler wie „Float in Dollar“ vs. „Integer in Cents“, bevor echte Daten betroffen sind.

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

Agenten brauchen eine Umgebung zum Üben. Diese Umgebung darf nicht Produktion sein.

Das Muster:

Umgebung Zweck Daten
Mock lokale Agentenentwicklung keine echten Writes
Sandbox/Staging Integrationstests isolierte Testdaten
Produktion echte Nutzung nur nach Freigabe

Jeder zustandsändernde Endpunkt sollte ein Mock-Äquivalent haben:

  • POST
  • PUT
  • PATCH
  • DELETE

Apidog kann Mock-Antworten direkt aus Ihrer OpenAPI-Spezifikation generieren. Sie richten die Basis-URL des Agenten auf den Mock-Server aus und führen Prompts oder Tool-Call-Sequenzen wiederholt aus.

Wenn der Agent versehentlich DELETE /users/{id} aufruft, sieht Ihre echte Datenbank diesen Fehler nicht.

Mehr zum übergeordneten Ansatz: Contract-First Development.

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

Jeder Schreib-Endpunkt, den ein Agent aufrufen darf, sollte einen Idempotenzschlüssel akzeptieren.

Beispiel für Express:

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);
Enter fullscreen mode Exit fullscreen mode

Der Agent erzeugt pro logischer Operation eine UUID:

const idempotencyKey = crypto.randomUUID();

await fetch("/payments", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "idempotency-key": idempotencyKey
  },
  body: JSON.stringify({
    customer_id: "cus_123",
    amount: 1900,
    currency: "EUR"
  })
});
Enter fullscreen mode Exit fullscreen mode

Bei einem Retry wird derselbe Schlüssel wiederverwendet. Die API gibt die gecachte Antwort zurück, statt die Operation doppelt auszuführen.

Für Löschoperationen gilt zusätzlich:

DELETE /users/{id}         → Soft-Delete
DELETE /users/{id}/purge   → Hard-Delete, nur mit menschlicher Freigabe
Enter fullscreen mode Exit fullscreen mode

4. Budget-Obergrenzen pro Agent

Jeder Agent braucht harte Limits:

  • Token-Budget
  • Anfrage-Budget
  • Dollar-Budget
  • Zeit-Budget
  • maximale Tool-Call-Tiefe

Beispielwerte für den Start:

Limit Startwert
Tokens pro Sitzung 50.000
API-Aufrufe pro Minute 30
Kosten pro Aufgabe 5 EUR
Verschachtelte Tool-Aufrufe 10
Refunds pro Sitzung 5

Wenn ein Limit erreicht wird, sollte die API sauber schließen:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-Budget-Exceeded: api_calls_per_minute
Content-Type: application/json

{
  "error": "budget_exceeded",
  "limit": "api_calls_per_minute",
  "message": "Agent exceeded 30 API calls per minute"
}
Enter fullscreen mode Exit fullscreen mode

Der Agenten-Planer kann dann:

  1. stoppen,
  2. einen Menschen einschalten,
  3. die Aufgabe abbrechen,
  4. oder nach Retry-After kontrolliert fortfahren.

Diese vier Schutzvorkehrungen ergänzen sich:

  • Vertragstests fangen Schemafehler ab.
  • Mocks verhindern echte Schäden in der Entwicklung.
  • Idempotenz verhindert doppelte Writes.
  • Budgets stoppen Endlosschleifen.

API-Aufrufe von Agenten mit Apidog testen

Jetzt zum konkreten Workflow mit Apidog.

Sie benötigen:

  • eine OpenAPI-3.x-Spezifikation Ihrer API
  • die Tool-Definitionen Ihres Agenten
  • Test-Credentials oder Mock-Daten
  • eine CI-Umgebung wie GitHub Actions, GitLab CI oder Jenkins

Schritt 1: OpenAPI-Spezifikation importieren

Erstellen Sie in Apidog ein neues Projekt und importieren Sie Ihre OpenAPI-Datei.

Apidog erstellt daraus:

  • Endpunkte
  • Request-Schemas
  • Response-Schemas
  • Beispiele
  • Mock-Grundlagen
  • Testfälle/Szenario-Bausteine

Falls Ihre API noch nicht als OpenAPI dokumentiert ist, sollten Sie diesen Schritt zuerst nachholen. Agentenzuverlässigkeit hängt davon ab, dass Menschen, Tests und Tools dieselbe API-Quelle verwenden.

Ein passender Einstieg ist der Design-First-API-Workflow.

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

Gehen Sie alle zustandsändernden Endpunkte durch:

POST   /tickets
PATCH  /tickets/{id}
DELETE /users/{id}
POST   /payments/refunds
POST   /notifications
Enter fullscreen mode Exit fullscreen mode

Für jeden dieser Endpunkte:

  1. Öffnen Sie den Endpunkt in Apidog.
  2. Erstellen Sie eine Mock-Antwort.
  3. Verwenden Sie das echte Schema.
  4. Überschreiben Sie sensible Werte mit offensichtlichen Testdaten.

Beispiel für Mock-Daten:

{
  "id": "mock_user_1970_001",
  "email": "mock.user@example.test",
  "deleted": true,
  "deleted_at": "1970-01-01T00:00:00Z"
}
Enter fullscreen mode Exit fullscreen mode

Warum so auffällig?

Wenn diese Daten in Logs, Dashboards oder Traces auftauchen, ist sofort klar: Das war ein Mock, keine Produktion.

Starten Sie danach den Mock-Server. Apidog stellt eine stabile URL bereit, zum Beispiel:

https://mock.apidog.com/m1/your-project-id/
Enter fullscreen mode Exit fullscreen mode

Konfigurieren Sie Ihren Agenten über Umgebungsvariablen:

AGENT_API_BASE_URL=https://mock.apidog.com/m1/your-project-id/
Enter fullscreen mode Exit fullscreen mode

Nicht im Prompt hardcoden. Dieselbe Agentenkonfiguration sollte gegen Mock, Staging und Produktion laufen können.

Schritt 3: Szenario schreiben, das die Tool-Call-Sequenz simuliert

Apidog-Szenarien erlauben verkettete API-Aufrufe mit Assertions. Damit bilden Sie typische Agenten-Flows nach.

Beispiel: Support-Ticket-Agent

  1. POST /auth/token mit Test-Credentials
  2. Bearer-Token aus der Antwort speichern
  3. GET /tickets?status=open
  4. erste Ticket-ID extrahieren
  5. POST /tickets/{id}/triage
  6. Statuscode 200 prüfen
  7. Kategorie und Assignee prüfen
  8. POST /notifications
  9. Nachrichtentext per Regex validieren

Beispiel-Assertionen:

pm.test("triage returns 200", function () {
  pm.response.to.have.status(200);
});

pm.test("assignee is present", function () {
  const body = pm.response.json();
  pm.expect(body.assigned_to).to.be.a("string");
});

pm.test("category is valid", function () {
  const body = pm.response.json();
  pm.expect(["billing", "technical", "account"]).to.include(body.category);
});
Enter fullscreen mode Exit fullscreen mode

So testen Sie nicht nur einzelne Endpunkte, sondern die Sequenz, die ein Agent tatsächlich ausführen würde.

Wenn ein Entwickler später das Ticket-Schema ändert und assigned_to entfernt oder umbenennt, schlägt das Szenario fehl, bevor der Agent in Produktion läuft.

Mehr dazu: API-Tests für QA-Ingenieure.

Schritt 4: Szenarien in CI ausführen

Apidog bietet eine CLI für CI-Runs. Ein typischer Befehl sieht so aus:

apidog run -t scenario-id --env test
Enter fullscreen mode Exit fullscreen mode

Beispiel für GitHub Actions:

name: Agent API Contract Tests

on:
  pull_request:
    paths:
      - "openapi/**"
      - "agents/**"
      - "tools/**"

jobs:
  test-agent-api:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run Apidog scenario
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: apidog run -t scenario-id --env test
Enter fullscreen mode Exit fullscreen mode

Lassen Sie CI fehlschlagen, wenn:

  • ein Schema nicht passt,
  • ein Mock keine gültige Antwort liefert,
  • ein Szenario eine Assertion verletzt,
  • ein Endpunkt ohne Idempotenzschlüssel erreichbar ist,
  • ein destruktiver Endpunkt in Testkonfiguration auf Produktion zeigt.

Schritt 5: Modellversionen nebeneinander vergleichen

Wenn Sie von Modell A auf Modell B wechseln, testen Sie nicht nur Antwortqualität. Vergleichen Sie Tool-Calls.

Vorgehen:

  1. Agent mit Modell A gegen Apidog-Szenarien ausführen.
  2. Tool-Call-Trace speichern.
  3. Agent mit Modell B gegen dieselben Szenarien ausführen.
  4. Tool-Call-Trace speichern.
  5. Request-Bodies vergleichen.

Achten Sie auf Unterschiede wie:

{
- "priority": "medium"
+ "priority": "urgent"
}
Enter fullscreen mode Exit fullscreen mode

Oder:

{
- "amount": 1900
+ "amount": 19.00
}
Enter fullscreen mode Exit fullscreen mode

Solche Abweichungen sind oft gefährlicher als eine andere Formulierung im Textoutput.

Dieses Evaluierungsmuster wird auch im Kontext von Modell-Upgrades in der GPT-5.5-API-Integration behandelt.

Fortgeschrittene Techniken und Profi-Tipps

Temperatur in Tests auf 0 setzen

Nicht-deterministische Agenten erzeugen nicht-deterministische Testfehler.

Für Tool-Call-Tests:

{
  "temperature": 0,
  "seed": 1234
}
Enter fullscreen mode Exit fullscreen mode

Sie testen hier nicht Kreativität, sondern API-Verhalten.

Tool-Call-Traces versionieren

Speichern Sie pro Testlauf:

  • Tool-Name
  • HTTP-Methode
  • Pfad
  • Request-Body
  • Response-Code
  • relevante Header
  • Zeitstempel
  • Agenten-/Modellversion

Beispiel:

[
  {
    "tool": "list_tickets",
    "method": "GET",
    "path": "/tickets?status=open",
    "status": 200
  },
  {
    "tool": "triage_ticket",
    "method": "POST",
    "path": "/tickets/t_123/triage",
    "body": {
      "category": "billing",
      "priority": "medium"
    },
    "status": 200
  }
]
Enter fullscreen mode Exit fullscreen mode

Vergleichen Sie diesen Trace gegen eine Baseline. Wenn der Agent plötzlich /users zweimal aufruft, sehen Sie es sofort.

Niemals Produktionszugangsdaten an Agenten geben

Agenten sollten aufgabenspezifische Service-Konten verwenden.

Nicht:

DATABASE_URL=prod-db-url
STRIPE_SECRET_KEY=live-key
Enter fullscreen mode Exit fullscreen mode

Besser:

AGENT_API_BASE_URL=https://agent-proxy.internal
AGENT_SERVICE_TOKEN=short-lived-token
Enter fullscreen mode Exit fullscreen mode

Wenn ein Agent Produktion erreichen muss, dann über einen Proxy, der:

  • kurzlebige Tokens verwendet,
  • Requests signiert,
  • Budgetlimits erzwingt,
  • gefährliche Pfade blockiert,
  • vollständige Audit-Logs schreibt.

API-Schlüssel für Lese- und Schreibzugriff trennen

Die meisten Agentenaufgaben sind überwiegend lesend.

Geben Sie getrennte Schlüssel aus:

agent_read_key     → GET, HEAD
agent_write_key    → POST, PUT, PATCH
agent_admin_key    → nie direkt an Agenten
Enter fullscreen mode Exit fullscreen mode

Schreibzugriff sollte nur für Aufgaben verfügbar sein, die ihn wirklich benötigen. Das reduziert den Schadensradius sofort.

HTTP 423 Locked für menschliche Freigaben verwenden

Wenn ein Agent eine Operation ausführen will, die menschliche Bestätigung braucht, geben Sie nicht einfach 403 Forbidden zurück.

Besser:

HTTP/1.1 423 Locked
Content-Type: application/json

{
  "error": "human_confirmation_required",
  "confirmation_url": "https://app.example.com/confirm/abc123",
  "message": "Refund requires human approval"
}
Enter fullscreen mode Exit fullscreen mode

Semantik:

  • 403: Du darfst das nicht.
  • 423: Du darfst das noch nicht.

Der Agent kann die URL einem Menschen anzeigen und warten.

Bei Schema-Drift fehlerhaft schließen

Warnungen reichen nicht. Wenn Tool-Definition und OpenAPI-Schema auseinanderlaufen, muss der Build fehlschlagen.

Schema drift detected → CI failed
Enter fullscreen mode Exit fullscreen mode

Die Kosten eines fehlgeschlagenen Builds sind niedriger als die Kosten eines Produktionsvorfalls.

Häufige Fehler vermeiden

Vermeiden Sie diese Muster:

  • Mock-URLs direkt in Prompts hardcoden.
  • Idempotenz bei „kleinen“ Endpunkten weglassen.
  • Vollständige Request-Bodies mit PII in Produktion loggen.
  • Agenten direkten Datenbankzugriff geben.
  • Vertrauensscores des Modells als Sicherheitsentscheidung verwenden.
  • Schreibschlüssel für Aufgaben ausgeben, die nur lesen müssen.
  • Retrys ohne Backoff und Budgetlimit erlauben.
  • DELETE-Endpunkte ohne Soft-Delete bereitstellen.

Wenn Ihr Agent mehrere interne Services anspricht, helfen Microservices-Testmuster, Szenariotests über Servicegrenzen hinweg aufzubauen.

Alternativen und Werkzeuge

Sie haben mehrere Optionen. Wichtig ist, dass die API-Schicht explizit getestet wird.

Ansatz Einrichtungszeit Stärke Schwäche Am besten für
Handgeschriebene Unit-Tests Niedrig Volle Kontrolle, keine Herstellerbindung Hoher Wartungsaufwand, driftet leicht von der echten API weg Kleine Projekte, Ein-Entwickler-Teams
LangSmith / LangGraph Eval-Harness Mittel Trace-Replay, modellbewusste Metriken Stark auf Agenten-Seite, schwächer auf API-Seite Eval-intensive KI-Teams
Postman + Postbot Mittel Vertraute UI, große Vorlagenbibliothek Mock-Server als Add-on, Szenario-Syntax wirkt älter Teams, die bereits in Postman arbeiten
Apidog-Szenarien + Mocks Mittel Native OpenAPI-Unterstützung, Mocks, Szenario-CLI für CI Weniger Markenbekanntheit als Postman Teams, die Design, Mocks und Tests in einem Tool wollen

Pragmatische Empfehlung:

  • Wenn Sie bereits LangSmith nutzen, behalten Sie es für Prompt- und Agenten-Evals und ergänzen Sie eine API-Testschicht.
  • Wenn Sie Postmans Mock- oder Preismodell entwachsen sind, ist Apidog ein starker Ersatz.
  • Wenn Sie neu starten, wählen Sie ein Tool, das OpenAPI, Mocks und Szenarien in einem Projekt abbildet.

Viele Teams kombinieren die Werkzeuge: LangSmith für Agenten-Evaluierung, Apidog für API-Verträge, Mocks und Szenario-Replays.

Anwendungsfälle aus der Praxis

Agent aktualisiert Produktionsdatenbankzeilen

Ein Kundenerfolgsteam baute einen Agenten, der Kontofelder aus Support-Tickets aktualisiert.

Vor dem Launch implementierten sie:

  • Idempotenzschlüssel für alle Schreibendpunkte
  • Soft-Deletes
  • 200 Szenario-Wiederholungen in Apidog
  • Sandbox-Datenbank statt Produktion
  • Schema-Validierung für Enums

Die Tests deckten zwei Fälle auf, in denen der Agent subscription_status auf eine Zeichenfolge setzen wollte, die nicht im Enum enthalten war. Das Team ergänzte Validierung und lieferte ohne Vorfall aus.

Agent ruft eine Zahlungs-API auf

Ein Fintech-Team entwickelte einen automatisierten Rückerstattungsagenten.

Grenzen:

  • maximal 5 Rückerstattungen pro Sitzung
  • maximal 50 Dollar pro Rückerstattung
  • Idempotenz bei jedem Zahlungsaufruf
  • Vertragstests bei jeder PR

Die Vertragstestsuite lief gegen die OpenAPI-Spezifikation. Nach sechs Monaten wurden 12.000 Rückerstattungen ohne doppelte Abbuchungen verarbeitet.

Agent triagiert GitHub-Issues

Ein Plattformteam entwickelte einen Issue-Triage-Agenten, inspiriert von Clawsweeper.

Setup:

  • GitHub-API in Apidog gemockt
  • 50 Szenariotests für Edge Cases
  • Tests für gelöschte Issues
  • Tests für fehlende Labels
  • Tests für fehlerhafte Benutzereingaben

Vor dem Launch fanden sie drei Abstürze. Danach konnte der Agent die Triage in einem öffentlichen Repository mit 5.000 offenen Issues übernehmen.

Fazit

Wenn Sie nur eine Sache mitnehmen: Der Agent ist selten das eigentliche Problem. Die API ist entweder das Problem oder die Lösung.

Ihre Checkliste:

  • Tool-Schemas als Verträge behandeln.
  • Vertragstests in CI ausführen.
  • Destruktive Endpunkte mocken.
  • Schreiboperationen nur mit Idempotenzschlüssel erlauben.
  • Soft-Deletes als Standard verwenden.
  • Pro-Agenten-Budgetlimits erzwingen.
  • Szenarien bei jeder PR wiederholen.
  • Produktionszugangsdaten niemals direkt an Agenten geben.

Die viralen Agenten-Vorfälle dieses Jahres werden nicht die letzten sein. Teams, die sich schnell erholen, haben Schutzvorkehrungen bereits eingebaut.

Laden Sie Apidog herunter und beginnen Sie mit dem Mock-Server-Schritt. Für die QA-Perspektive siehe API-Test-Tools für QA-Ingenieure. Für sichere Agenten-Dokumentation siehe wie man AGENTS.md-Dateien schreibt.

FAQ

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

Führen Sie den Agenten während der Entwicklung gegen einen Mock-Server aus. Apidogs Mock-URLs liefern realistische Antworten, ohne echte API-Credits zu verbrauchen.

Zusätzlich:

  • Temperatur auf 0 setzen
  • festen Prompt-Satz verwenden
  • Tool-Call-Traces speichern
  • Szenarien automatisiert wiederholen

Eine vollständige Checkliste finden Sie unter API-Tests für QA-Ingenieure.

Was ist der Unterschied zwischen Agententest und API-Test?

Agententests prüfen:

  • Wählt das Modell das richtige Tool?
  • Füllt es Argumente korrekt aus?
  • Stoppt es bei Fehlern?
  • Reagiert es sinnvoll auf Limits?

API-Tests prüfen:

  • Funktioniert der Endpunkt korrekt?
  • Validiert er Eingaben?
  • Erzwingt er Autorisierung?
  • Unterstützt er Idempotenz?
  • Gibt er strukturierte Fehler zurück?

Sie brauchen beides. Ein guter Agent auf einer schlechten API verursacht trotzdem Vorfälle.

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

Für jeden Schreib-Endpunkt: ja.

Leseoperationen sind per Definition idempotent. Schreiboperationen nicht. Agenten wiederholen fehlgeschlagene Schritte, insbesondere bei Timeouts, 500ern oder unklaren Antworten.

Idempotenz schützt vor:

  • doppelten Zahlungen
  • doppelten E-Mails
  • doppelten CRM-Einträgen
  • mehrfachen Statusänderungen
  • wiederholten Refunds

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

Verlassen Sie sich nicht nur auf Prompts.

Die API muss Autorisierung anhand des ursprünglichen Benutzerkontexts erzwingen. Wenn ein normaler Benutzer nicht auf /admin/delete-all-users zugreifen darf, darf auch ein Agent im Namen dieses Benutzers diesen Endpunkt nicht aufrufen.

Implementieren Sie:

  • rollenbasierte Autorisierung
  • getrennte Service-Konten
  • eingeschränkte Scopes
  • menschliche Freigaben für gefährliche Aktionen
  • Audit-Logs
  • blockierte Admin-Pfade für Agenten

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

Sie richten die Tool-Definitionen während des Tests auf die Apidog-Mock-URL aus.

Das sollte über Konfiguration erfolgen:

AGENT_API_BASE_URL=https://mock.apidog.com/m1/your-project-id/
Enter fullscreen mode Exit fullscreen mode

Wenn Sie gegen Staging oder Produktion testen wollen, ändern Sie nur die Variable:

AGENT_API_BASE_URL=https://staging-api.example.com
Enter fullscreen mode Exit fullscreen mode

So bleibt dieselbe Tool-Definition nutzbar, während die Zielumgebung wechselt.

Was ist das richtige Budgetlimit für einen Agenten?

Starten Sie streng und lockern Sie anhand echter Metriken.

Gute Anfangswerte:

  • 50.000 Tokens pro Sitzung
  • 30 API-Aufrufe pro Minute
  • 5 EUR pro Aufgabe
  • 10 verschachtelte Tool-Aufrufe
  • 5 Schreiboperationen pro Sitzung

Beobachten Sie zwei Wochen lang:

  • Welche Limits werden legitimerweise erreicht?
  • Welche Limits werden nie erreicht?
  • Welche Agenten laufen in Schleifen?
  • Welche Tools verursachen hohe Kosten?

Passen Sie monatlich an.

Wie erkenne ich Schema-Drift zwischen Agenten-Tools und API?

Führen Sie bei jeder PR einen Schema-Diff in CI aus.

Vergleichen Sie:

  • Tool-Definition als JSON Schema
  • OpenAPI-Request-Body-Schema
  • erforderliche Felder
  • Typen
  • Enums
  • Formate
  • zusätzliche Felder

Wenn sie abweichen: Build fehlschlagen lassen.

Der Python-Snippet im Abschnitt „Vertragstests“ ist ein minimaler Startpunkt. Kopieren Sie ihn in Ihr Repository und binden Sie ihn in Ihre CI-Pipeline ein.

Top comments (0)