Unit Testing für KI-Agenten: Agent-Logik testen

Idee in 30 Sekunden

Unit-Tests für KI-Agenten prüfen lokale Logik: Tool-Auswahl, Antwortverarbeitung, Stop Reason und Ausgabeformat.

Ihr Hauptwert liegt in Tempo, Determinismus und Isolation. Dadurch sieht man sofort, welcher konkrete Teil des Systems gebrochen ist.

Problem

Ohne Unit-Tests prüfen Teams Agenten oft nur über manuelle Runs oder schwere End-to-End-Tests.

Das erzeugt typische Probleme:

• Fehler in lokaler Logik werden zu spät gefunden;
• es ist schwer zu erkennen, ob der Code oder eine externe Abhängigkeit gebrochen ist;
• kleine Regressionen sammeln sich und landen in Production.

Am Ende kann selbst eine kleine Änderung eine Kette intransparenter Ausfälle in Production auslösen.

Wann einsetzen

Unit-Tests solltet ihr immer dann schreiben, wenn ihr lokale und prüfbare Logik habt:

• Tool-Auswahl nach Anfrage-Typ;
• Validierung der Output-Struktur;
• Fehlerbehandlung von Tools;
• Abschlussbedingungen eines Runs (stop_reason);
• Sicherheitsregeln auf Schritt- oder Funktionsebene.

Wenn Verhalten ohne Netzwerk und ohne vollständige Agent-Runtime prüfbar ist, ist es ein guter Kandidat für Unit-Tests.

Umsetzung

In der Praxis folgt Unit-Testing für Agenten einer einfachen Regel: ein Verhalten, ein Test, kontrollierte Bedingungen. Die Beispiele unten sind schematisch und nicht an ein konkretes Framework gebunden.

Die Unit-Ebene eignet sich nicht, um die Gesamtqualität einer Antwort, den Nutzwert des Ergebnisses oder die allgemeine "Intelligenz" des Agenten zu bewerten. Dafür sind eval harness und golden datasets besser geeignet.

Wie es in einem Test funktioniert

1. Entscheidungslogik des Agenten isolieren

def choose_tool(intent: str, tools_allowed: list[str]) -> str:
    if intent == "price_lookup" and "crypto_price_api" in tools_allowed:
        return "crypto_price_api"
    return "web_search"

Je weniger Seiteneffekte und Abhängigkeiten eine Funktion hat, desto stabiler ist der Test.

2. Externe Tools ersetzen

class FakeTools:
    def crypto_price_api(self, symbol: str):
        return {"symbol": symbol, "price": 65000}

Ein Unit-Test soll Agentenlogik prüfen, nicht die Verfügbarkeit externer APIs.

3. Nicht nur den finalen Antworttext prüfen

def test_tool_selection_and_schema():
    tools = FakeTools()
    agent = Agent(tools=tools)
    result = agent.run("What is the price of BTC?")

    assert result.selected_tool == "crypto_price_api"
    assert isinstance(result.output, dict)
    assert result.output["symbol"] == "BTC"

Besser sind strukturelle Invarianten (selected_tool, schema, stop reason) statt nur finalem Text.

4. Negative Szenarien testen

def test_tool_error_is_handled():
    tools = FailingTools()
    agent = Agent(tools=tools)
    result = agent.run("Find BTC price")

    assert result.stop_reason == "tool_error_handled"
    assert result.error is not None

Tool-Fehler müssen ein vorhersehbares und prüfbares Verhalten haben.

5. Unit-Tests in CI integrieren

name: unit-tests
on:
  pull_request:
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install -r requirements.txt
      - run: pytest tests/unit -q

Wenn ein Test langsam oder instabil ist, verschiebt ihn in eval harness oder in die Integrationsschicht.

Typische Fehler

Abhängigkeit von echten APIs

Der Test fällt nicht wegen Agentenlogik, sondern wegen Netzwerk oder externer Dienste.

Typische Ursache: fehlende fakes oder mocks für Tools.

Nur finalen Text testen

Der Test ist "grün", garantiert aber weder korrekte Tool-Auswahl noch korrektes Ausgabeformat.

Typische Ursache: keine Checks für selected_tool, schema und stop reason.

Zu viel Logik in einem Test

Ein Test prüft mehrere Szenarien auf einmal, und bei einem Fehler ist unklar, was genau gebrochen ist.

Typische Ursache: keine Regel "ein Test - ein Verhalten".

Instabile Testumgebung

Selbst korrekte Unit-Tests werden verrauscht, wenn zwischen Runs Abhängigkeiten, Konfiguration oder Tool-Ersatz schwanken.

Typische Ursache: Unit-Tests hängen teilweise noch an echter Runtime oder externen Aufrufen.

Versuch, alles nur über e2e-Runs abzudecken

Das Team schreibt nur große Szenarien und überspringt lokale Basisprüfungen.

Typische Ursache: keine klare Trennung zwischen Unit-, Eval- und Regression-Ebene.

Kurzfassung

FAQ

Q: Können Unit-Tests eval harness ersetzen?
A: Nein. Unit-Tests fangen lokale Fehler ab, eval harness prüft das vollständige Agentenverhalten auf abgeschlossenen Szenarien.

Q: Soll in Unit-Tests eine echte LLM eingebunden werden?
A: Möglichst wenig. Für die Unit-Ebene sind deterministische Logik mit fakes oder mocks und kontrollierte Bedingungen besser.

Q: Was muss ein Unit-Test für Agenten zwingend prüfen?
A: Tool-Auswahl, Output-Struktur, Fehlerbehandlung und stop reason in negativen Szenarien.

Q: Wann sollte ein Test von Unit-Ebene zur Eval-Ebene wechseln?
A: Wenn er vom vollständigen Szenarioverhalten, Qualitätsmetriken der Antworten oder baseline-Vergleichen abhängt.

Was als Nächstes

Nach der Unit-Ebene ergänzt szenariobasierte Validierung über Eval Harness, und pflegt einen stabilen Casesatz über Golden Datasets.

Für Versionskontrolle ergänzt Regression Testing. Für die Analyse von Production-Incidents nutzt Replay and Debugging. Das Gesamtbild bleibt in Testing Strategy.