KI-Agent Tool-Aufrufe mit Apidog testen: Vor Produktionsausfällen

Ein KI-Agent ist nur so zuverlässig wie die APIs, die er aufruft. Das Modell wählt ein Tool aus, füllt Argumente ein und sendet eine Anfrage; wenn diese Anfrage fehlschlägt, die falsche Form zurückgibt oder hängenbleibt, trifft Ihr Agent eine selbstbewusste Entscheidung auf Basis schlechter Daten. Die meisten Agenten-Demos überspringen diesen Teil. Produktions-Agenten stehen und fallen damit.

Diese Anleitung zeigt, wie Sie einen Agenten erstellen, der reale Tools aufruft, und, was noch wichtiger ist, wie Sie Apidog sowohl als API-Schicht als auch als Testumgebung dahinter verwenden. Sie entwerfen die Tool-Endpunkte, simulieren sie (mocken), damit Sie offline entwickeln können, und schreiben Assertions, die einen fehlerhaften Tool-Aufruf abfangen, bevor er einen Benutzer erreicht. Das Ziel ist ein Agent, dem Sie vertrauen können, weil Sie ihn getestet haben, nicht weil der „Happy Path“ einmal funktioniert hat.

Was ein Agent auf der API-Ebene tatsächlich tut

Nimmt man den Rahmen weg, ist eine Agenten-Schleife einfach:

1. Das Modell empfängt ein Benutzerziel und eine Liste von Tools.
2. Es gibt einen Tool-Aufruf zurück: einen Tool-Namen plus JSON-Argumente.
3. Ihr Code führt diesen Aufruf aus; normalerweise eine HTTP-Anfrage an eine API.
4. Das Ergebnis geht zurück an das Modell.
5. Das Modell ruft entweder ein anderes Tool auf oder antwortet.

Jeder interessante Fehler tritt in Schritt 3 und Schritt 4 auf. Das Modell halluziniert ein Argument, die API gibt einen 422er-Fehler zurück, das Antwortschema hat sich verschoben, der Aufruf überschreitet das Zeitlimit oder eine Ratenbegrenzung greift mitten in der Schleife. Wenn Sie über KI-Agenten als neue API-Konsumenten gelesen haben, ist dies die konkrete Version dieser Idee: Ihr Agent ist ein Client, der Ihre APIs anspricht, und er verdient die gleiche Teststrenge wie jeder andere Client.

Die Arbeit teilt sich also in zwei Bereiche: Definieren Sie die Tools als reale, testbare API-Operationen und überprüfen Sie dann, ob der Agent sie unter guten und schlechten Bedingungen korrekt aufruft.

Schritt 1: Entwerfen Sie die Tools als reale API-Operationen

Bevor Sie eine einzige Zeile Agenten-Code schreiben, definieren Sie jedes Tool als API-Endpunkt in Apidog. Behandeln Sie das Tool-Schema und das API-Schema als dasselbe, denn das sind sie auch. Ein get_weather-Tool und der GET /weather-Endpunkt teilen sich einen Vertrag: die gleichen Parameter, die gleiche Antwortstruktur.

Erstellen Sie in Apidog für jedes Tool einen Endpunkt mit seinem OpenAPI-Schema; Pfad-, Abfrage- und Body-Parametern sowie einer typisierten Antwort. Das bringt Ihnen drei Dinge kostenlos:

• Eine einzige Quelle der Wahrheit für den Tool-Vertrag, aus der sowohl Ihr Agenten-Prompt als auch Ihre Tests lesen.
• Automatisch generierte Dokumentation, die Sie dem Modell als Tool-Definition übergeben können.
• Ein Schema zur späteren Validierung, sodass Sie Abweichungen sofort erkennen, wenn eine Antwort nicht mehr übereinstimmt.

Diese Schema-First-Gewohnheit ist dieselbe, die im Allgemeinen hinter solider API-Design-Arbeit steckt. Der Vorteil für Agenten ist spezifisch: Wenn Ihre Tool-Definition und Ihr realer Endpunkt aus einem Schema stammen, kann das Modell kein Tool aufrufen, das Ihre API nicht unterstützt.

Schritt 2: Simulieren Sie die Tools (Mocking), damit Sie offline entwickeln können

Sie möchten nicht, dass jeder Entwicklungsdurchlauf Live-APIs anspricht, die Geld kosten, Ratenbegrenzungen durchsetzen oder einfach noch nicht gebaut sind. Apidog generiert einen Mock-Server direkt aus dem Schema, das Sie gerade definiert haben. Jeder Tool-Endpunkt liefert realistische, schemavalide Beispieldaten ohne ein Backend.

Das verändert, wie Sie Agenten entwickeln. Sie können:

• Die gesamte Agenten-Schleife entwickeln, bevor die realen APIs existieren, anhand von Mocks, die dem vereinbarten Vertrag entsprechen.
• Integrationstests in CI durchführen, die niemals einen kostenpflichtigen Endpunkt berühren.
• Spezifische Antworten erzwingen; ein leeres Ergebnis, einen 500er-Fehler, ein fehlerhaftes Feld; um zu sehen, wie Ihr Agent reagiert.

Richten Sie den Tool-Executor Ihres Agenten während der Entwicklung auf die Mock-Basis-URL aus. Das Modell ruft get_weather auf, Ihr Code trifft auf den Apidog-Mock, und eine gültige Antwort kommt sofort zurück. Wenn Sie bereit für die reale Implementierung sind, tauschen Sie die Basis-URL über eine Umgebungsvariable aus. Mocking macht die Agentenentwicklung schnell und deterministisch; derselbe Ansatz treibt jeden ernsthaften KI-Agenten-Test-Workflow an.

Schritt 3: Den Agenten zum Aufruf der Tools verdrahten

Mit vorhandenen Endpunkten und Mocks bleibt der Agenten-Code schlank. Hier ist die Form einer Tool-Aufruf-Schleife unter Verwendung der Claude Messages API; die Tool-Definitionen spiegeln die Schemas wider, die Sie in Apidog erstellt haben.

import anthropic, requests, os

client = anthropic.Anthropic()
TOOL_BASE = os.environ["TOOL_BASE_URL"]  # Apidog mock during dev, real API in prod

tools = [{
    "name": "get_weather",
    "description": "Get current weather for a city",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
    },
}]

def run_tool(name, args):
    if name == "get_weather":
        r = requests.get(f"{TOOL_BASE}/weather", params={"city": args["city"]}, timeout=10)
        r.raise_for_status()
        return r.json()

messages = [{"role": "user", "content": "What should I wear in Tokyo today?"}]
while True:
    resp = client.messages.create(
        model="claude-fable-5", max_tokens=1024, tools=tools, messages=messages
    )
    if resp.stop_reason == "tool_use":
        block = next(b for b in resp.content if b.type == "tool_use")
        result = run_tool(block.name, block.input)
        messages.append({"role": "assistant", "content": resp.content})
        messages.append({"role": "user", "content": [{
            "type": "tool_result", "tool_use_id": block.id,
            "content": str(result),
        }]})
    else:
        print(resp.content[0].text)
        break

Die Zeilen timeout=10 und raise_for_status() sind wichtiger als der Modellaufruf. Sie machen den Unterschied zwischen einem Agenten, der laut fehlschlägt, und einem, der eine hängende oder fehlerhafte Anfrage stillschweigend in die Schleife zurückführt. Für eine umfassendere Sichtweise, wie Agenten in API-Workflows passen, sind die Muster in 5 KI-Agenten für Ihren API-Workflow eine nützliche Ergänzung.

Schritt 4: Testen Sie die Tool-Aufrufe, nicht nur die reine Funktionalität

Dies ist der Teil, den die meisten Teams überspringen. Führen Sie jeden Tool-Endpunkt als gespeicherte Anfrage in Apidog mit Assertions aus, unabhängig vom Modell. Die Zuverlässigkeit des Agenten ist durch die Zuverlässigkeit seiner Tools begrenzt, testen Sie also zuerst die Tools.

Für jeden Tool-Endpunkt prüfen Sie:

• Status ist 200 bei gültiger Eingabe.
• Der Antwort-Body entspricht dem Schema; Apidog validiert die Antwort automatisch gegen Ihre OpenAPI-Definition.
• Erforderliche Felder, die das Modell lesen wird, sind vorhanden und korrekt typisiert.
• Die Antwortzeit liegt innerhalb des Zeitlimits, das Ihr Agent durchsetzt.

Testen Sie dann die „Unhappy Paths“, denn dort verhalten sich Agenten oft falsch:

• Senden Sie fehlerhafte Argumente, die ein Modell halluzinieren könnte; eine leere city, eine Zahl, wo ein String hingehört; und vergewissern Sie sich, dass Sie einen sauberen 400/422 erhalten, keinen 500.
• Erzwingen Sie eine Fehlerantwort vom Mock und bestätigen Sie, dass der run_tool Ihres Agenten einen Fehler auslöst, anstatt unsinnige Daten zurückzugeben.
• Testen Sie ein leeres Ergebnis und überprüfen Sie, ob der Agent „keine Daten“ verarbeitet, anstatt eine Antwort zu erfinden.

Dies ist das auf Agenten-Tools angewandte Vertragstesting; dieselbe Disziplin, die im API-Vertragstesting behandelt wird, ausgerichtet auf die Endpunkte, die Ihr Modell aufruft. Wenn sich die Antwortform eines Tools ändert, schlägt die Assertion in CI fehl, und Sie beheben dies, bevor der Agent beginnt, über eine fehlerhafte Payload zu räsonieren.

Schritt 5: Umgang mit Wiederholungen, Timeouts und Ratenbegrenzungen

Agenten verstärken die Probleme fehleranfälliger APIs. Ein einziger Wiederholungsversuch in einer normalen App ist ein Wiederholungsversuch; in einer Agenten-Schleife kann ein Modell, das ein fehlschlagendes Tool immer wieder aufruft, Ihre Ratenbegrenzung und Ihr Budget schnell aufbrauchen. Erstellen Sie die Kontrollen und testen Sie sie:

• Timeouts. Legen Sie für jede Tool-Anfrage ein explizites Timeout fest, wie im obigen Beispiel. Verwenden Sie dann Apidog, um einen langsamen Endpunkt zu simulieren und zu bestätigen, dass Ihr Client sauber abbricht, anstatt die gesamte Schleife zu blockieren.
• Wiederholungen mit Backoff. Wiederholen Sie vorübergehende Fehler, aber begrenzen Sie die Anzahl und verwenden Sie einen Backoff. Testen Sie dies gegen einen Mock, der zweimal fehlschlägt und dann erfolgreich ist, und stellen Sie sicher, dass Ihr Agent sich erholt, anstatt unendlich zu loopen.
• Ratenbegrenzungen. Erwarten Sie 429er unter Last. Simulieren Sie eine ratenbegrenzte Antwort und überprüfen Sie, ob Ihr Agent wartet und erneut versucht, anstatt ununterbrochen Anfragen zu senden. Wenn Sie dies bei rohen Modell-APIs bereits erlebt haben (siehe GPT API-Ratenbegrenzungen für dieselbe Art von Problem); ist die Agenten-Version strenger, da die Schleife jeden Aufruf multipliziert.
• Circuit Breaking. Nach N Fehlern bei einem Tool hören Sie auf, es aufzurufen, und lassen den Agenten den Fehler melden, anstatt sich im Kreis zu drehen. Testen Sie, ob der Unterbrecher auslöst.

Führen Sie diese als wiederholbare Szenarien in Apidog aus, sodass eine Regression in Ihrer Fehlerbehandlung als fehlgeschlagener Test und nicht als Produktionsvorfall erscheint.

Schritt 6: End-to-End-Ausführung gegen Mocks in CI

Führen Sie alles zusammen. Starten Sie in CI Ihren Agenten, der auf den Apidog Mock-Server zeigt, geben Sie ihm eine feste Reihe von Benutzerzielen und überprüfen Sie das Endergebnis und die Reihenfolge der Tool-Aufrufe. Da die Mocks deterministisch sind, erzeugt dieselbe Eingabe bei jedem Durchlauf dieselben Tool-Aufrufe, sodass Ihre Agententests nicht mehr unzuverlässig sind. Wenn Sie zuversichtlich sind, wechseln Sie die Basis-URL zu den realen APIs für einen kleineren Live-Smoke-Test. Diese Aufteilung; deterministische Mocks für den Großteil der Tests, eine schlanke Live-Überprüfung für die Realität; macht Agenten-KI-Tests praktisch statt nur wünschenswert.

Eine Checkliste für einen vertrauenswürdigen Agenten

• [ ] Jedes Tool ist als reale API-Operation mit einem OpenAPI-Schema definiert.
• [ ] Für jedes Tool existieren Mocks, damit Sie offline entwickeln und testen können.
• [ ] Jeder Tool-Endpunkt hat Assertions für Status, Schema und Timing.
• [ ] Unhappy Paths; schlechte Argumente, Fehler, leere Ergebnisse; werden explizit getestet.
• [ ] Timeouts, Wiederholungen mit Backoff und die Behandlung von Ratenbegrenzungen sind im Code implementiert und getestet.
• [ ] Ein End-to-End-CI-Durchlauf testet die vollständige Schleife gegen deterministische Mocks.

Erfüllen Sie alle sechs Punkte, und Sie haben einen Agenten, dessen Zuverlässigkeit Sie mit Beweisen, nicht mit Hoffnung, beschreiben können.

FAQ

Warum einen API-Client verwenden, um einen Agenten zu testen, anstatt den Agenten einfach auszuführen? Das Ausführen des Agenten testet das Modell und die Tools zusammen, daher ist ein Fehler mehrdeutig. Das Testen jedes Tool-Endpunkts in Apidog isoliert die API-Ebene, sodass Sie wissen, ob ein Problem an der Denkweise des Modells oder an einem defekten Tool liegt.

Muss ich die realen APIs vor dem Bau des Agenten erstellen? Nein. Definieren Sie die Tool-Verträge als Schemas in Apidog, generieren Sie Mocks und erstellen Sie die gesamte Agenten-Schleife gegen diese Mocks. Tauschen Sie die realen Endpunkte später über eine Umgebungsvariable aus.

Wie verhindere ich, dass mein Agent bei einem fehlschlagenden Tool endlos in einer Schleife festhängt? Begrenzen Sie Wiederholungsversuche, fügen Sie einen Backoff hinzu und lösen Sie einen Circuit Breaker nach wiederholten Fehlern aus, damit der Agent das Problem meldet, anstatt sich im Kreis zu drehen. Testen Sie jede Kontrolle gegen einen Mock, der Fehler zurückgibt.

Kann ich den Agenten testen, ohne Geld für Modell- und API-Aufrufe auszugeben? Größtenteils ja. Mocken Sie die Tool-APIs in Apidog für deterministische, kostenlose Integrationstests und beschränken Sie Live-Modellaufrufe auf eine kleine Smoke-Test-Suite.

Funktioniert dies mit Frameworks wie LangChain oder dem Claude Agent SDK? Ja. Die Tool-Schicht ist einfach HTTP. Egal welches Framework die Schleife antreibt, richten Sie seine Tool-Aufrufe für Tests auf Apidog-Mocks und für die Produktion auf reale Endpunkte. Siehe die Claude Code SDK-Anleitung für eine solche Schleife.

Zusammenfassung

Ein zuverlässiger Agent ist kein intelligenterer Prompt; es ist eine getestete Tool-Schicht. Definieren Sie Ihre Tools als reale API-Operationen, simulieren (mocken) Sie sie, damit die Entwicklung schnell und deterministisch ist, überprüfen Sie jede Antwortstruktur und testen Sie Fehler bewusst. Apidog bietet Ihnen einen zentralen Ort, um diese Endpunkte zu entwerfen, zu simulieren und als Testumgebung auszuführen, sodass Sie das Verhalten Ihres Agenten beweisen können. Laden Sie Apidog herunter und bauen Sie den Agenten, dem Sie in der Produktion tatsächlich vertrauen können.