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ängen bleibt, trifft Ihr Agent eine selbstbewusste Entscheidung auf Basis schlechter Daten. Produktions-Agenten stehen und fallen deshalb mit einer getesteten Tool- und API-Schicht.

Apidog noch heute ausprobieren

Diese Anleitung zeigt, wie Sie einen Agenten erstellen, der reale Tools aufruft, und wie Sie Apidog als API-Schicht und Testumgebung verwenden. Sie definieren Tool-Endpunkte, mocken sie für die Offline-Entwicklung und schreiben Assertions, die fehlerhafte Tool-Aufrufe abfangen, bevor sie Benutzer erreichen.

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

Reduziert auf die technische Schleife passiert Folgendes:

1. Das Modell erhält ein Benutzerziel und eine Liste verfügbarer Tools.
2. Es gibt einen Tool-Aufruf zurück: Tool-Name plus JSON-Argumente.
3. Ihr Code führt den Aufruf aus, meist als HTTP-Request.
4. Das API-Ergebnis geht zurück an das Modell.
5. Das Modell ruft ein weiteres Tool auf oder antwortet dem Benutzer.

Die kritischen Fehler entstehen fast immer in Schritt 3 und 4:

• Das Modell halluziniert ein Argument.
• Die API gibt 400, 422, 429 oder 500 zurück.
• Das Antwortschema hat sich geändert.
• Der Request läuft in ein Timeout.
• Eine Ratenbegrenzung greift mitten in der Agenten-Schleife.

Wenn Sie KI-Agenten als neue API-Konsumenten betrachten, wird klar: Ihr Agent ist ein API-Client. Er braucht dieselbe Teststrenge wie jeder andere produktive Client.

Die Arbeit besteht aus zwei Teilen:

1. Tools als reale, testbare API-Operationen definieren.
2. Prüfen, ob der Agent diese Tools unter guten und schlechten Bedingungen korrekt aufruft.

Schritt 1: Tools als reale API-Operationen entwerfen

Definieren Sie jedes Tool zuerst als API-Endpunkt in Apidog. Behandeln Sie Tool-Schema und API-Schema als denselben Vertrag.

Beispiel:

• Tool: get_weather
• API-Operation: GET /weather
• Parameter: city
• Antwort: typisiertes JSON-Objekt mit Wetterdaten

Erstellen Sie in Apidog für jedes Tool:

• Pfad, z. B. /weather
• HTTP-Methode, z. B. GET
• Query-, Path- oder Body-Parameter
• OpenAPI-Schema
• Beispielantworten
• Fehlerantworten wie 400, 422, 429 und 500

Das bringt drei konkrete Vorteile:

• Eine zentrale Quelle der Wahrheit für Tool-Vertrag, Prompt und Tests.
• Generierte Dokumentation, die Sie als Tool-Definition verwenden können.
• Schema-Validierung, damit abweichende Antworten sofort auffallen.

Diese Schema-First-Arbeit entspricht solidem API-Design. Für Agenten ist der Nutzen besonders direkt: Wenn Tool-Definition und Endpunkt aus demselben Schema stammen, kann das Modell kein Tool korrekt anfordern, das Ihre API gar nicht unterstützt.

Schritt 2: Tools mocken, damit Sie offline entwickeln können

Sie sollten Agenten nicht bei jedem lokalen Test gegen Live-APIs ausführen. Live-Endpunkte können:

• Kosten verursachen
• Ratenbegrenzungen auslösen
• instabil sein
• noch nicht implementiert sein

Apidog kann aus Ihrem Schema einen Mock-Server erzeugen. Jeder Tool-Endpunkt liefert dann schemavalide Beispieldaten, ohne dass ein Backend existieren muss.

Damit können Sie:

• die Agenten-Schleife vor der Backend-Implementierung bauen
• Integrationstests in CI ausführen, ohne kostenpflichtige APIs aufzurufen
• gezielt Fehlerfälle simulieren, z. B. leere Ergebnisse, 500, fehlende Felder oder langsame Antworten

Richten Sie den Tool-Executor während der Entwicklung auf die Mock-URL:

TOOL_BASE_URL=https://mock-url.example.com

In Produktion wechseln Sie nur die Basis-URL:

TOOL_BASE_URL=https://api.example.com

Das Modell ruft weiter get_weather auf. Ihr Code entscheidet über die Umgebungsvariable, ob der Request an den Apidog-Mock oder an die echte API geht. Dieses Muster ist die Grundlage für reproduzierbare KI-Agenten-Tests.

Schritt 3: Agenten mit Tool-Aufrufen verdrahten

Mit definierten Endpunkten und Mocks bleibt der Agenten-Code klein. Das folgende Beispiel zeigt eine einfache Tool-Schleife mit der Claude Messages API. Die Tool-Definition sollte dem Schema entsprechen, das Sie in Apidog definiert haben.

import os
import requests
import anthropic

client = anthropic.Anthropic()

# In der Entwicklung: Apidog Mock-URL
# In Produktion: reale API-Basis-URL
TOOL_BASE = os.environ["TOOL_BASE_URL"]

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":
        response = requests.get(
            f"{TOOL_BASE}/weather",
            params={"city": args["city"]},
            timeout=10,
        )
        response.raise_for_status()
        return response.json()

    raise ValueError(f"Unknown tool: {name}")

messages = [
    {
        "role": "user",
        "content": "What should I wear in Tokyo today?"
    }
]

while True:
    response = client.messages.create(
        model="claude-fable-5",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )

    if response.stop_reason == "tool_use":
        tool_block = next(
            block for block in response.content
            if block.type == "tool_use"
        )

        result = run_tool(tool_block.name, tool_block.input)

        messages.append({
            "role": "assistant",
            "content": response.content,
        })

        messages.append({
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": tool_block.id,
                    "content": str(result),
                }
            ],
        })

    else:
        print(response.content[0].text)
        break

Die wichtigsten Zeilen sind nicht der Modellaufruf, sondern diese beiden:

timeout=10
response.raise_for_status()

Sie verhindern, dass ein hängender oder fehlerhafter API-Aufruf still in die Agenten-Schleife zurückläuft. Für weitere Muster rund um Agenten in API-Workflows siehe 5 KI-Agenten für Ihren API-Workflow.

Schritt 4: Tool-Endpunkte unabhängig vom Modell testen

Testen Sie nicht nur, ob der Agent auf dem Happy Path antwortet. Testen Sie zuerst jedes Tool unabhängig vom Modell.

Für jeden Tool-Endpunkt sollten Sie in Apidog gespeicherte Requests mit Assertions anlegen:

• Statuscode ist 200 bei gültiger Eingabe.
• Antwort entspricht dem OpenAPI-Schema.
• Felder, die das Modell benötigt, sind vorhanden.
• Feldtypen stimmen, z. B. String, Number, Array.
• Antwortzeit liegt unter dem Timeout Ihres Agenten.

Beispielhafte Checks für GET /weather:

GET /weather?city=Tokyo

Erwartungen:
- HTTP 200
- response.city ist String
- response.temperature ist Number
- response.condition ist String
- response.generated_at ist vorhanden
- response time < 1000 ms

Testen Sie danach gezielt Unhappy Paths:

• city ist leer
• city fehlt
• city ist eine Zahl statt ein String
• API gibt 500 zurück
• API gibt 429 zurück
• Antwort enthält ein leeres Ergebnis
• Antwort enthält ein fehlendes oder falsch typisiertes Feld

Beispiel:

GET /weather?city=

Erwartung:
- HTTP 400 oder 422
- Fehlerantwort enthält eine verständliche Fehlermeldung
- kein 500

Das ist Vertragstesting für Agenten-Tools. Dieselbe Disziplin aus dem API-Vertragstesting wird auf die Endpunkte angewandt, die Ihr Modell tatsächlich aufruft.

Wenn sich die Antwortform eines Tools ändert, sollte CI fehlschlagen, bevor der Agent mit einer kaputten Payload arbeitet.

Schritt 5: Timeouts, Wiederholungen und Ratenbegrenzungen implementieren

Agenten verstärken API-Probleme. Ein einzelner fehlgeschlagener Request in einer normalen App ist ein Fehler. In einer Agenten-Schleife kann das Modell dasselbe Tool mehrfach erneut aufrufen und damit Budget und Rate Limits verbrauchen.

Implementieren und testen Sie daher explizite Schutzmechanismen.

Timeouts

Jeder Tool-Request braucht ein Timeout:

requests.get(url, timeout=10)

Simulieren Sie in Apidog einen langsamen Endpunkt und prüfen Sie, ob Ihr Client sauber abbricht, statt die gesamte Schleife zu blockieren.

Wiederholungen mit Backoff

Wiederholen Sie nur vorübergehende Fehler und begrenzen Sie die Anzahl der Versuche.

Beispiel:

import time
import requests

def request_with_retry(url, params, retries=3):
    for attempt in range(retries):
        try:
            response = requests.get(url, params=params, timeout=10)
            response.raise_for_status()
            return response.json()

        except requests.exceptions.HTTPError as error:
            status = error.response.status_code

            if status not in [429, 500, 502, 503, 504]:
                raise

            if attempt == retries - 1:
                raise

            time.sleep(2 ** attempt)

Testen Sie dieses Verhalten gegen einen Mock, der zweimal fehlschlägt und danach erfolgreich antwortet.

Ratenbegrenzungen

Planen Sie 429 Too Many Requests ein. Simulieren Sie eine ratenbegrenzte Antwort und prüfen Sie, ob Ihr Agent wartet oder kontrolliert abbricht, statt sofort weitere Requests zu senden.

Wenn Sie mit Modell-APIs bereits ähnliche Probleme hatten, sind GPT API-Ratenbegrenzungen ein vergleichbares Muster. Bei Agenten ist der Effekt stärker, weil die Schleife Tool-Aufrufe vervielfachen kann.

Circuit Breaker

Nach mehreren Fehlern sollte Ihr Agent ein Tool vorübergehend nicht mehr aufrufen.

Ein einfaches Muster:

tool_failures = {}

def can_call_tool(name, max_failures=3):
    return tool_failures.get(name, 0) < max_failures

def record_tool_failure(name):
    tool_failures[name] = tool_failures.get(name, 0) + 1

def reset_tool_failures(name):
    tool_failures[name] = 0

Wenn can_call_tool("get_weather") False zurückgibt, sollte der Agent den Fehler melden, statt weiter im Kreis zu laufen.

Schritt 6: End-to-End gegen Mocks in CI testen

Führen Sie die vollständige Schleife in CI gegen Apidog-Mocks aus:

1. Agent startet mit TOOL_BASE_URL auf Mock-Server.
2. Test übergibt ein festes Benutzerziel.
3. Agent ruft deterministische Tool-Endpunkte auf.
4. Test prüft Endergebnis und Tool-Aufruf-Reihenfolge.

Beispielhafte Testfälle:

Input:
"What should I wear in Tokyo today?"

Erwartung:
- Agent ruft get_weather mit city="Tokyo" auf
- Tool-Response entspricht Schema
- finale Antwort verwendet Wetterdaten
- keine zusätzlichen unnötigen Tool-Aufrufe

Da die Mocks deterministisch sind, werden Agententests reproduzierbarer. Wenn die Mock-Tests stabil sind, führen Sie zusätzlich eine kleine Live-Smoke-Suite gegen echte APIs aus.

Diese Aufteilung ist pragmatisch:

• viele deterministische Mock-Tests
• wenige Live-Smoke-Tests

Damit werden Agenten-KI-Tests praktisch statt nur theoretisch.

Checkliste für einen vertrauenswürdigen Agenten

• [ ] Jedes Tool ist als reale API-Operation mit OpenAPI-Schema definiert.
• [ ] Für jedes Tool existiert ein Mock-Endpunkt.
• [ ] Jeder Tool-Endpunkt hat Assertions für Status, Schema und Timing.
• [ ] Fehlerfälle wie schlechte Argumente, leere Ergebnisse und Serverfehler werden getestet.
• [ ] Timeouts sind für jeden Tool-Request gesetzt.
• [ ] Wiederholungen sind begrenzt und verwenden Backoff.
• [ ] 429-Antworten werden kontrolliert behandelt.
• [ ] Ein Circuit Breaker verhindert Endlosschleifen.
• [ ] CI testet die vollständige Agenten-Schleife gegen deterministische Mocks.
• [ ] Eine kleine Live-Smoke-Suite prüft reale Endpunkte.

Wenn alle Punkte erfüllt sind, können Sie die Zuverlässigkeit Ihres Agenten mit Tests belegen, nicht nur mit einem erfolgreichen Demo-Lauf.

FAQ

Warum einen API-Client verwenden, um einen Agenten zu testen, statt nur den Agenten auszuführen?

Weil ein vollständiger Agentenlauf Modell und Tools gleichzeitig testet. Wenn etwas fehlschlägt, ist die Ursache unklar. Tests der Tool-Endpunkte in Apidog isolieren die API-Ebene. So sehen Sie, ob das Problem am Modellverhalten oder an einem defekten Tool liegt.

Muss ich die realen APIs vor dem Agenten bauen?

Nein. Definieren Sie zuerst die Tool-Verträge als Schemas in Apidog, generieren Sie Mocks und bauen Sie die Agenten-Schleife gegen diese Mocks. Später tauschen Sie die Basis-URL per Umgebungsvariable gegen echte Endpunkte aus.

Wie verhindere ich Endlosschleifen bei fehlschlagenden Tools?

Begrenzen Sie Wiederholungen, verwenden Sie Backoff und lösen Sie nach mehreren Fehlern einen Circuit Breaker aus. Testen Sie diese Logik gegen Mocks, die gezielt Fehler zurückgeben.

Kann ich Agenten testen, ohne Geld für Modell- und API-Aufrufe auszugeben?

Größtenteils ja. Mocken Sie Tool-APIs in Apidog und führen Sie deterministische Integrationstests gegen diese Mocks aus. Live-Modell- und API-Aufrufe sollten auf eine kleine Smoke-Test-Suite begrenzt bleiben.

Funktioniert das mit Frameworks wie LangChain oder dem Claude Agent SDK?

Ja. Die Tool-Schicht ist HTTP. Unabhängig davon, welches Framework die Schleife steuert, können Sie Tool-Aufrufe im Test auf Apidog-Mocks und in Produktion auf reale Endpunkte richten. Siehe auch die Claude Code SDK-Anleitung.

Zusammenfassung

Ein zuverlässiger Agent entsteht nicht nur durch einen besseren Prompt. Entscheidend ist eine getestete Tool-Schicht.

Definieren Sie Tools als API-Operationen, mocken Sie sie für schnelle Entwicklung, validieren Sie jede Antwortstruktur und testen Sie Fehlerfälle bewusst. Apidog bietet dafür einen zentralen Workflow zum Entwerfen, Mocken und Testen der Endpunkte, die Ihr Agent verwendet.