Agenten Pipelines für komplexe Aufgaben designen

1. Was eine Agenten-Pipeline von einem einzelnen Prompt unterscheidet

Eine Agenten-Pipeline zerlegt eine komplexe Aufgabe in eine geordnete Abfolge klar abgegrenzter Stufen, wobei jede Stufe von einem eigenen Agentenaufruf mit spezifischem Auftrag bearbeitet wird und ihr Ergebnis als Eingabe an die nächste Stufe weitergibt. Der fundamentale Unterschied zu einem einzelnen, umfassenden Prompt liegt darin, dass eine Pipeline die Aufgabe explizit in überprüfbare Zwischenschritte gliedert, statt zu erwarten, dass ein Agent die gesamte Komplexität in einem Durchgang bewältigt.

Bei einem monolithischen Prompt für eine komplexe Aufgabe, etwa die vollständige Umsetzung eines neuen Features von der Anforderung bis zu den Tests, besteht das Risiko, dass Fehler in frühen gedanklichen Schritten unbemerkt bleiben, weil sie im selben Durchgang wie alle nachfolgenden Schritte verarbeitet werden. Eine Agenten-Pipeline macht jeden Zwischenschritt zu einem eigenständigen, prüfbaren Artefakt, wodurch sich Fehler früh erkennen lassen, bevor sie sich in nachfolgende Stufen fortpflanzen.

Der Aufbau einer Agenten-Pipeline lohnt sich vor allem bei wiederkehrenden, strukturell ähnlichen Aufgaben, bei denen sich die Stufenfolge stabil wiederverwenden lässt, etwa die Einführung neuer Features, Datenbankmigrationen oder die Modernisierung von Legacy-Modulen. Für einmalige, unstrukturierte Anfragen lohnt sich der zusätzliche Entwurfsaufwand einer Pipeline dagegen meist nicht.

2. Pipeline-Stufen definieren: Komplexe Aufgaben zerlegen

Der erste Entwurfsschritt für jede Agenten-Pipeline ist die Zerlegung der Gesamtaufgabe in einzelne Stufen mit jeweils klar definiertem Ein- und Ausgabeformat. Für eine typische Feature-Entwicklung ergeben sich häufig vier bis sechs Stufen: Anforderungsanalyse, technischer Entwurf, Implementierung, Testgenerierung, Dokumentation und abschließende Prüfung. Jede Stufe sollte genau eine Frage beantworten und ihr Ergebnis in einer Form liefern, die die nächste Stufe direkt konsumieren kann.

Eine gute Faustregel bei der Definition von Stufen einer Agenten-Pipeline: Eine Stufe ist zu groß, wenn ihr Ergebnis mehrere unabhängig überprüfbare Aussagen enthält, die sich nicht klar einer einzigen Verantwortung zuordnen lassen. In diesem Fall lohnt es sich, die Stufe in zwei kleinere Stufen mit jeweils eigenem, engerem Auftrag aufzuteilen. Zu viele, zu kleinteilige Stufen erhöhen dagegen den Koordinationsoverhead, ohne einen echten Mehrwert an Nachvollziehbarkeit zu bringen.

{
  "pipeline": "feature-development",
  "stages": [
    { "id": "requirements", "input": "ticket_description", "output": "structured_requirements" },
    { "id": "design", "input": "structured_requirements", "output": "technical_design" },
    { "id": "implementation", "input": "technical_design", "output": "code_diff" },
    { "id": "tests", "input": "code_diff", "output": "test_suite" },
    { "id": "documentation", "input": ["code_diff", "test_suite"], "output": "updated_docs" },
    { "id": "final_check", "input": ["code_diff", "test_suite", "updated_docs"], "output": "review_ready_bundle" }
  ]
}

3. Datenfluss zwischen Pipeline-Stufen gestalten

Der Datenfluss innerhalb einer Agenten-Pipeline sollte so gestaltet sein, dass jede Stufe genau die Informationen erhält, die sie für ihren Auftrag benötigt, ohne den vollständigen Verlauf aller vorherigen Stufen erneut zu verarbeiten. In der Praxis bedeutet das, dass jede Stufe ein strukturiertes Ausgabeartefakt produziert, üblicherweise als JSON-Objekt mit klar benannten Feldern, das direkt als Eingabe für die nächste Stufe dient, ergänzt um nur die Kontextteile, die tatsächlich benötigt werden.

Ein häufiger Entwurfsfehler in einer Agenten-Pipeline besteht darin, jeder Stufe den kompletten Verlauf aller vorherigen Stufen mitzugeben, aus Sorge, sonst könnten wichtige Informationen fehlen. Das führt zu unnötig großen Kontextfenstern und verschleiert, welche Information tatsächlich für die aktuelle Stufe relevant war. Besser ist ein expliziter Vertrag zwischen den Stufen: Jede Stufe dokumentiert genau, welche Felder sie als Eingabe erwartet, und der Orchestrator stellt sicher, dass nur diese Felder übergeben werden.

# Explicit contract between pipeline stages: each stage declares its inputs
# The orchestrator passes only the declared fields, not the full history

from dataclasses import dataclass
from typing import Any

@dataclass
class StageContract:
    stage_id: str
    required_inputs: list[str]
    output_schema: dict[str, str]

CONTRACTS = {
    "design": StageContract(
        stage_id="design",
        required_inputs=["structured_requirements"],
        output_schema={"technical_design": "object"},
    ),
    "implementation": StageContract(
        stage_id="implementation",
        required_inputs=["technical_design"],
        output_schema={"code_diff": "object"},
    ),
}

def build_stage_input(stage_id: str, pipeline_state: dict[str, Any]) -> dict:
    contract = CONTRACTS[stage_id]
    missing = [f for f in contract.required_inputs if f not in pipeline_state]
    if missing:
        raise ValueError(f"Stage {stage_id} is missing required inputs: {missing}")
    return {field: pipeline_state[field] for field in contract.required_inputs}

4. Bedingte Verzweigungen und Wiederholungen in der Pipeline

Nicht jede Agenten-Pipeline verläuft linear. In der Praxis entstehen häufig bedingte Verzweigungen, etwa wenn die Testgenerierungsstufe fehlschlägt und ein zusätzlicher Korrekturschritt vor der Dokumentationsstufe eingefügt werden muss. Ein robustes Pipeline-Design sieht solche Verzweigungen explizit vor, statt sie als Sonderfall nachträglich einzubauen, indem jede Stufe neben ihrem regulären Ausgang auch einen definierten Fehlerausgang besitzt, der auf eine Korrektur- oder Eskalationsstufe verweist.

Wiederholungen innerhalb einer Agenten-Pipeline sollten grundsätzlich begrenzt sein. Eine Stufe, die dreimal hintereinander fehlschlägt, deutet meist auf ein strukturelles Problem in der vorgelagerten Stufe hin, nicht auf eine zufällige Schwankung, die durch einfaches Wiederholen behoben werden könnte. Nach Erreichen des Wiederholungslimits sollte die Pipeline anhalten und den aktuellen Zustand zusammen mit allen bisherigen Fehlschlägen an einen Menschen eskalieren, statt endlos weiterzulaufen.

{
  "stage": "tests",
  "regular_output": "test_suite",
  "error_output": {
    "target": "implementation_fix_stage",
    "condition": "test_generation_failed"
  },
  "retry_policy": {
    "max_attempts": 3,
    "on_limit_exceeded": "escalate_to_human"
  }
}

5. Qualitätsgates zwischen den Stufen einbauen

Ein Qualitätsgate ist eine Prüfung, die zwischen zwei Stufen einer Agenten-Pipeline sitzt und entscheidet, ob das Ergebnis der vorherigen Stufe ausreichend ist, um fortzufahren. Gates können automatisiert sein, etwa ein Linter- oder Testlauf nach der Implementierungsstufe, oder sie können eine zweite, unabhängige Agentenprüfung sein, die das Ergebnis der vorherigen Stufe gegen definierte Kriterien bewertet, ohne deren Denkprozess zu kennen.

Qualitätsgates sind der wichtigste Baustein, um zu verhindern, dass sich Fehler unbemerkt durch eine mehrstufige Agenten-Pipeline fortpflanzen. Ohne Gates bestätigen sich Fehler oft gegenseitig: Eine fehlerhafte Anforderungsanalyse führt zu einem fehlerhaften Entwurf, der wiederum zu passendem, aber falschem Code führt. Ein Gate direkt nach der Anforderungsanalyse, das die Vollständigkeit und Widerspruchsfreiheit der extrahierten Anforderungen prüft, verhindert, dass sich dieser Fehler in die folgenden, aufwendigeren Stufen fortsetzt.

6. Praxisbeispiel: Eine Pipeline für Feature-Entwicklung von Spec bis Test

Ein konkretes Beispiel verdeutlicht das Zusammenspiel aller Elemente: Für die Einführung eines neuen Rabattmechanismus in einem Magento-Shop durchläuft die Anforderung zunächst die Analysestufe, die aus einem Ticket-Text strukturierte Anforderungen extrahiert. Ein Qualitätsgate prüft, ob alle notwendigen Geschäftsregeln, etwa Kombinierbarkeit mit anderen Rabatten, explizit erfasst wurden, bevor die Entwurfsstufe beginnt.

Die Entwurfsstufe übersetzt die Anforderungen in eine technische Lösung, die auf bestehende Repository-Interfaces referenziert. Die Implementierungsstufe setzt diesen Entwurf in Code um, die Teststufe generiert passende PHPUnit-Tests, und ein abschließendes Qualitätsgate prüft Code und Tests gemeinsam gegen die Konventionen aus der CLAUDE.md. Erst wenn dieses letzte Gate besteht, gilt das Ergebnis der Agenten-Pipeline als reviewfertig und wird als Pull Request bereitgestellt.

#!/usr/bin/env bash
# Run a multi stage agent pipeline with quality gates between stages
set -euo pipefail

TICKET_ID="${1:?Usage: run-pipeline.sh TICKET-123}"
STATE_DIR="pipeline/${TICKET_ID}"
mkdir -p "$STATE_DIR"

run_stage() {
  local stage="$1"
  local input_file="$2"
  claude --agent-config "pipeline-stages/${stage}.json" \
    --input "$input_file" \
    --output "${STATE_DIR}/${stage}.json"
}

run_gate() {
  local gate_name="$1"
  local artifact="$2"
  claude --agent-config "pipeline-gates/${gate_name}.json" \
    --input "$artifact" \
    --output "${STATE_DIR}/${gate_name}-result.json"
  jq -e '.passed == true' "${STATE_DIR}/${gate_name}-result.json" > /dev/null
}

run_stage "requirements" "tickets/${TICKET_ID}.md"
run_gate "requirements_gate" "${STATE_DIR}/requirements.json" \
  || { echo "[pipeline] requirements gate failed, escalating" >&2; exit 1; }

run_stage "design" "${STATE_DIR}/requirements.json"
run_stage "implementation" "${STATE_DIR}/design.json"
run_stage "tests" "${STATE_DIR}/implementation.json"

run_gate "final_gate" "${STATE_DIR}/tests.json" \
  || { echo "[pipeline] final gate failed, escalating" >&2; exit 1; }

echo "[pipeline] Feature pipeline complete and review ready for ${TICKET_ID}"

7. Fehlerbehandlung und Rollback in mehrstufigen Pipelines

Fehler in einer Agenten-Pipeline müssen anders behandelt werden als Fehler in einem einzelnen Agentenaufruf, weil ein Fehlschlag in einer späten Stufe unter Umständen bedeutet, dass Ergebnisse mehrerer vorheriger Stufen verworfen werden müssen. Ein durchdachtes Pipeline-Design speichert daher den Zustand nach jeder erfolgreich abgeschlossenen Stufe persistent, sodass ein erneuter Lauf nicht zwingend bei der ersten Stufe beginnen muss, sondern an der zuletzt erfolgreichen Stufe fortsetzen kann.

Für kritische Agenten-Pipelines, die auch produktive Systeme berühren, etwa Datenbankmigrationsstufen, sollte zusätzlich ein expliziter Rollback-Mechanismus vorgesehen werden, der bei einem Fehlschlag in einer späten Stufe die Auswirkungen früherer Stufen rückgängig macht, statt das System in einem inkonsistenten Zwischenzustand zu belassen. Dieser Rollback-Mechanismus ist kein optionales Extra, sondern ein Pflichtbestandteil jeder Pipeline, die über reine Codegenerierung hinausgeht.

8. Monitoring und Kostenkontrolle einer Agenten-Pipeline

Der Betrieb einer Agenten-Pipeline im Produktivbetrieb erfordert Monitoring auf zwei Ebenen: technisch, um Laufzeit und Fehlerquote pro Stufe zu erfassen, und wirtschaftlich, um den Tokenverbrauch pro Stufe und über die gesamte Pipeline hinweg im Blick zu behalten. Eine Stufe, die überdurchschnittlich oft an einem Qualitätsgate scheitert, deutet häufig auf ein strukturelles Problem in ihrem Prompt oder in der vorgelagerten Stufe hin und sollte gezielt untersucht werden, statt das Gate einfach zu lockern.

Für die Kostenkontrolle empfiehlt sich eine Obergrenze für Tokens pro Pipeline-Lauf, verbunden mit einer Warnung, wenn eine einzelne Stufe überdurchschnittlich viele Tokens verbraucht. Diese Grenze verhindert, dass eine fehlerhaft konfigurierte Stufe unbemerkt hohe Kosten verursacht, bevor jemand das Problem bemerkt. Regelmäßige Auswertungen zeigen zudem, welche Stufen einer Agenten-Pipeline sich für eine Optimierung lohnen, etwa durch kleinere, gezieltere Prompts.

#!/usr/bin/env bash
# Monitor token consumption per stage and warn on above average usage
set -euo pipefail

STATE_DIR="$1"
TOKEN_LIMIT_PER_RUN=150000
total_tokens=0

for stage_file in "${STATE_DIR}"/*.json; do
  stage_tokens=$(jq -r '.token_usage // 0' "$stage_file")
  stage_name=$(basename "$stage_file" .json)
  total_tokens=$(( total_tokens + stage_tokens ))

  if (( stage_tokens > 20000 )); then
    echo "[monitoring] WARNING: stage ${stage_name} used ${stage_tokens} tokens, above average" >&2
  fi
done

echo "[monitoring] Total pipeline token usage: ${total_tokens}"
if (( total_tokens > TOKEN_LIMIT_PER_RUN )); then
  echo "[monitoring] ERROR: pipeline exceeded token budget of ${TOKEN_LIMIT_PER_RUN}" >&2
  exit 1
fi

9. Monolithischer Prompt und Agenten-Pipeline im Vergleich

Die folgende Tabelle vergleicht einen einzelnen, umfassenden Prompt mit dem Ansatz einer strukturierten Agenten-Pipeline.

Eine Agenten-Pipeline zahlt sich vor allem bei wiederkehrenden, strukturell ähnlichen Aufgaben aus, bei denen der einmalige Entwurfsaufwand über viele Durchläufe amortisiert wird. Für Einzelfälle bleibt ein direkter, gut formulierter Prompt oft die effizientere Wahl.

10. Zusammenfassung

Eine gut entworfene Agenten-Pipeline zerlegt komplexe Entwicklungsaufgaben in klar abgegrenzte, überprüfbare Stufen, statt sie einem einzelnen, überladenen Prompt zu überlassen. Klar definierter Datenfluss zwischen den Stufen, eingebaute Qualitätsgates und eine durchdachte Fehlerbehandlung mit Rollback-Möglichkeit sind die entscheidenden Bausteine, die aus einer losen Abfolge von Agentenaufrufen ein zuverlässiges, wiederverwendbares System machen.

Der Entwurf einer Agenten-Pipeline lohnt sich vor allem für wiederkehrende, strukturell ähnliche Aufgaben, bei denen sich der Aufwand für Stufen- und Gate-Design über viele Durchläufe amortisiert. Wer diesen Aufwand konsequent investiert und Monitoring sowie Kostenkontrolle von Anfang an mitdenkt, gewinnt eine Automatisierung, die auch bei komplexen, mehrstufigen Aufgaben nachvollziehbar und robust bleibt.

11. FAQ: Agenten Pipelines für komplexe Aufgaben designen