Einmalige Agent-Aufgaben in wiederverwendbare Workflows überführen

Um eine mehrstufige Aufgabe eines KI-Agenten wiederverwendbar zu machen, speichern Sie ihre Schritte als typisierte Modelldefinitionen und eine deklarative Workflow-Datei in Ihrem Repository. So führt die nächste Session den gespeicherten Prozess aus, statt ihn aus einem Prompt neu aufzubauen.

Wahrscheinlich kennen Sie das: Ein Agent führt einen sauberen Release-Check durch (Tests, Build, Smoke-Test, alles in der richtigen Reihenfolge), dann wird die Session geschlossen und der Prozess ist mit ihr verschwunden. Am nächsten Tag beschreiben Sie ihn erneut und erhalten eine leicht abweichende Version.

Dieser Artikel zeigt, wie Sie diesen Prozess mit Swamp festhalten. Er behandelt, was wiederverwendbar wird und was nicht, stellt einen kleinen Release-Check-Workflow vor und zeigt, wie derselbe Workflow unter Claude Code, Cursor, OpenCode oder Codex läuft.

Warum ein guter Agent-Lauf verloren geht

Eine Agent-Session hält ihren Arbeitsprozess nur im Konversationskontext fest, daher endet der Prozess mit der Session. Die ausgeführten Befehle, die gewählte Reihenfolge und die ergänzten Prüfungen werden nirgends gespeichert, wo die nächste Session sie ausführen könnte. Übrig bleiben ein Chat-Transkript und die Dateien, die sich zufällig geändert haben.

Die Lösung besteht darin, den Prozess des Agenten in Dateien im Repository zu überführen, die ausgeführt werden. Sobald die Schritte im Repository liegen, müssen Sie die Aufgabe nicht mehr in jeder Session neu erklären, und der Agent investiert seine Zeit in Änderungen statt in die Rekonstruktion des Ablaufs.

Wiederverwendbare KI-Agent-Workflows mit Swamp: Was bleibt und was nicht

Swamp ist ein Kommandozeilenwerkzeug, das die funktionierende Automatisierung eines Agenten als typisierte Modelle, YAML-Definitionen, Workflows, versionierte Daten und Vault-Referenzen in einem .swamp/-Verzeichnis innerhalb eines Git-Repositorys speichert. Die Swamp-README nennt sechs Kernkonzepte: Modelle, die externe Systeme als Typen beschreiben; Definitionen, also YAML-Dateien, die eine konkrete Verwendung eines Modelltyps konfigurieren; Workflows; Daten; Vaults; und Tags.

Swamp macht den Prozess wiederholbar, nicht das Reasoning. Sobald die Schritte eines Agenten als Modelldefinitionen und Workflow-Datei gespeichert sind, führen spätere Läufe genau diese gespeicherten Schritte aus. Wenn der Agent sie jedoch erstellt oder bearbeitet, kann sein Output von Session zu Session variieren.

Swamp und MCP erfüllen unterschiedliche Aufgaben. MCP verbindet einen Agenten mit Tools, wie der Entwicklerleitfaden zum MCP-Ökosystem erläutert. Swamp speichert und führt die Automatisierung aus, die der Agent mit diesen Tools aufbaut – Sie können beides kombinieren. Swamp läuft auf Ihrem eigenen Rechner, und alle verwendeten Credentials stammen aus der Umgebung der Shell, die es startet.

Swamp für Ihr Harness einrichten

Installieren Sie das Binary mit dem offiziellen Skript und initialisieren Sie anschließend das Repository für Ihr Harness. Das offizielle Installationsskript unterstützt macOS und Linux; Release-Binaries werden zusätzlich für Windows veröffentlicht.

curl -fsSL https://swamp-club.com/install.sh | sh

swamp repo init                    # Claude Code (default)
swamp repo init --tool cursor      # or: opencode, codex

Claude Code liest die Swamp-Skills aus .claude/skills/ und die Anweisungen aus CLAUDE.md. Cursor verwendet .cursor/skills/ und .cursor/rules/swamp.mdc. OpenCode und Codex nutzen beide .agents/skills/ und AGENTS.md.

Swamp liefert die Skills im Binary mit und schreibt sie beim Ausführen von init ins Repository – so findet der Agent sie ohne zusätzliche Konfiguration. Shell-Completions sind über swamp completions <shell> verfügbar.

Ein Release-Check-Workflow von Anfang bis Ende

Ein Swamp-Workflow ist eine YAML-Datei, die Jobs als DAG anordnet, wobei jeder Step eine Methode einer Modelldefinition aufruft. Wie How Swamp Works erklärt, wartet jeder Job auf die Jobs, von denen er abhängt, und Steps innerhalb desselben Jobs laufen parallel, sofern keiner von einem anderen abhängt.

Normalerweise würden Sie den Agenten bitten, die Definitionen run-tests, build-artifact und smoke-test zu erstellen. Lesen Sie den resultierenden Workflow trotzdem, denn genau diese Datei geben Sie frei. Die folgende Struktur orientiert sich an der Workflow-Referenz. Die <method>-Platzhalter sind bewusst stehen geblieben: Ersetzen Sie sie durch die Methodennamen, die Ihre Definitionen tatsächlich bereitstellen.

id: <keep the generated id>
name: release-check
tags:
  purpose: release
jobs:
  - name: checks
    description: Run tests and build in parallel
    steps:
      - name: tests
        task:
          type: model_method
          modelIdOrName: run-tests
          methodName: <method>
      - name: build
        task:
          type: model_method
          modelIdOrName: build-artifact
          methodName: <method>
  - name: smoke
    dependsOn:
      - job: checks
        condition:
          type: succeeded
    steps:
      - name: smoke
        task:
          type: model_method
          modelIdOrName: smoke-test
          methodName: <method>
version: 1

Im Release-Check-Workflow laufen Tests und Build gleichzeitig. condition.type: succeeded hält den Smoke-Job zurück, bis beide erfolgreich sind. Prüfen Sie die Datei mit swamp workflow validate release-check und führen Sie sie dann aus:

swamp workflow run release-check
swamp workflow run release-check --tag env=staging
swamp data query 'attributes.ok == false'   # example query from the Swamp manual

swamp workflow run wartet, bis der Lauf abgeschlossen ist (Erfolg, Fehler oder Abbruch) oder an einem manual_approval-Gate pausiert. Ein erfolgreicher Lauf endet mit Exit-Code 0, alles andere mit einem Exit-Code ungleich 0 – CI kann also darauf gaten. Das Flag --tag überschreibt Tags zur Laufzeit. Jeder Lauf speichert seine Outputs als versionierte, nachträglich unveränderliche Daten, die Sie über Tags wiederfinden. Eine spätere Session kann also nachlesen, was passiert ist, statt es aus dem Chatverlauf zu rekonstruieren. Der data query-Ausdruck stammt aus dem Beispiel in How Swamp Works und muss an die Felder Ihres Modells angepasst werden.

Ein erfolgreicher Smoke-Step belegt nur, dass der Endpoint geantwortet hat. Er beweist nicht, dass die Seite gerendert wurde oder Nutzer einen Flow abschließen konnten. Erst durch das Replay von Sessions auf dem Staging-Build werden Frontend-Regressionen dieser Art sichtbar.

Denselben Workflow zwischen Harnesses übertragen

Wenn ein Team einen Swamp-Workflow über Harnesses hinweg nutzt, teilt es die Modell-, Definitions- und Workflow-Dateien. Das Skills-Verzeichnis jedes Harness steht in der .gitignore und wird von Swamp selbst geschrieben; mit swamp repo upgrade --tool <name> kann ein Entwickler das Harness wechseln oder mehrere parallel betreiben. Die README weist darauf hin, dass jedes Tool einen eigenen Skills-Ordner erhält, der nicht in Git landet.

Angenommen, das Repository wurde für Claude Code initialisiert und ein Teammitglied arbeitet mit Cursor. Das Agent-Harness ändert sich, die Workflow-Datei bleibt dieselbe:

# same checkout, teammate on Cursor
swamp repo upgrade --tool cursor
swamp workflow run release-check

swamp workflow run hängt nicht davon ab, welcher Agent den Befehl aufgerufen hat. Die Aufgabe des Agenten besteht im Schreiben und Bearbeiten von Definitionen – und dieser Teil variiert mit dem Harness. OpenCode und Codex teilen sich .agents/skills/ und AGENTS.md, beide Tools lesen also denselben Skills-Speicherort.

Standardmäßig legt Swamp Laufdaten wie Modelldaten, Workflow-Läufe, Outputs und Audit-Logs in .swamp/ ab. Teams, die denselben Zustand auf mehreren Rechnern benötigen, können auf ein anderes Datastore-Backend umsteigen, etwa einen gemeinsamen Dateisystempfad oder S3. Auch der Checkout ist portabel: Auf einer für agentisches Coding eingerichteten Remote-Maschine läuft derselbe Workflow, solange die Shell über die Credentials verfügt, die die Modelle benötigen. Mit --repo-dir oder SWAMP_REPO_DIR verweisen Sie Swamp auf ein Repository außerhalb des aktuellen Verzeichnisses.

Reifegrad und Grenzen von Swamp

Swamp ist ein junges Werkzeug. Es wird in den swamp-club-Repositories aktiv gepflegt und erscheint in kontinuierlichen, datumsbasierten Releases. Rechnen Sie mit Änderungen.

• Geschlossene Beiträge. Nur Mitarbeitende des Elder Swamp Club schreiben Code für Swamp. Pull Requests aus Forks werden automatisch geschlossen; Bugs und Feature-Ideen reichen Sie daher über swamp issue bug oder swamp issue feature ein, und die Maintainer setzen die akzeptierten Vorschläge um.
• Telemetrie. Swamp erfasst Nutzungstelemetrie, sofern Sie sie nicht deaktivieren. Sie können sie für einen einzelnen Befehl mit --no-telemetry abschalten, für eine Shell mit SWAMP_NO_TELEMETRY=1, für ein Repository mit telemetryDisabled: true in .swamp.yaml oder für alle Läufe auf Ihrem Rechner mit swamp config set telemetry.collection disabled, was die Einstellung in ~/.config/swamp/telemetry.yaml schreibt.
• Einsatzbereich. Ein einzeiliges Skript oder ein Cronjob braucht keine Modelle, keinen DAG und keine versionierten Daten. Swamp lohnt sich, wenn eine Aufgabe mehrere Systeme umfasst, eine Historie benötigt oder von einem Team gemeinsam genutzt wird.
• Extensions führen Code aus. Prüfen Sie Extensions von Drittanbietern, bevor Sie ihnen vertrauen.
• Lizenz. AGPL-3.0 mit der Swamp Extension and Definition Exception.

Ein deterministischer Runner wiederholt einen schlechten Workflow genauso zuverlässig wie einen guten. Assertions und menschliche Reviews bleiben weiterhin notwendig.

Fazit

Swamp bewahrt die Vorgehensweise, nicht das Denken des Agenten. Gespeicherte Definitionen und Workflows liefern bei jedem Lauf dieselben Schritte und dieselben Gates, während der Agent beim Schreiben oder Ändern weiterhin frei (und variabel) bleibt. Ein guter nächster Schritt: Wählen Sie einen Prozess, den Ihr Agent bereits gut beherrscht – etwa einen Release-Check oder einen Review-Durchlauf – und lassen Sie ihn diesen als Swamp-Workflow speichern. Prüfen Sie das YAML, committen Sie es und führen Sie es aus einem zweiten Harness aus, um sicherzustellen, dass es auch dort funktioniert.

FAQs

Wie führe ich einen Swamp-Workflow in GitHub Actions CI aus?

Verwenden Sie swamp-club/setup-swamp, die offizielle GitHub Action. Sie installiert Swamp über das offizielle Installationsskript und kann sich zusätzlich bei swamp.club anmelden, wenn Sie einen api-key-Input übergeben. Setzen Sie repo-init auf true, um nach der Installation swamp repo init auszuführen. Ein nachfolgender Step ruft swamp workflow run mit dem Workflow-Namen auf. Schlägt der Lauf fehl, endet der Befehl mit einem Exit-Code ungleich 0 und der Job schlägt fehl. Die Action befindet sich noch in einem frühen v0.1-Release.

Wo sollten Secrets für einen Swamp-Workflow gespeichert werden?

Legen Sie sie in einem Swamp-Vault ab und referenzieren Sie sie in Definitionen und Workflows über ihren Namen. Swamp ruft den tatsächlichen Wert erst in dem Moment ab, in dem ein Step ausgeführt wird. So bleibt er aus Ihren YAML-Dateien und Ihren .swamp-Daten heraus, und für den nächsten Lauf wird nichts zwischengespeichert. Der integrierte lokale Verschlüsselungs-Provider erfordert keine zusätzliche Einrichtung. Andere Vault-Provider speichern Secrets in externen Diensten wie AWS Secrets Manager, Azure Key Vault oder 1Password.

Benötigt ein Swamp-Workflow einen KI-Agenten, um zu laufen?

Nein. swamp workflow run ist ein gewöhnlicher CLI-Befehl, sodass ein Entwickler, ein CI-Job oder ein Skript einen gespeicherten Workflow ganz ohne Agent ausführen kann. Den Agenten benötigen Sie nur, um Modelle, Definitionen und Workflows zu erstellen oder zu bearbeiten. Für Läufe, die niemand manuell startet, kann swamp serve einen Workflow über einen Cron-Trigger ausführen. Ebenso kann es einen Workflow starten, wenn ein signierter Webhook von GitHub, Jira, Linear, Stripe, Slack oder einem generischen Endpoint eingeht.

Lässt sich Swamp unter Windows installieren?

Ja. Die Swamp-Releases auf der GitHub-Releases-Seite von swamp-club/swamp enthalten neben den macOS- und Linux-Builds ein Archiv swamp-windows-x86_64.zip mit der Datei swamp.exe. Der curl-Einzeiler leitet das Installationsskript an sh weiter und funktioniert daher nicht unter Windows. Windows-Nutzer laden das Release-Archiv herunter, entpacken swamp.exe und legen die Datei in einem Verzeichnis ab, das in ihrem PATH enthalten ist.