kraftwerk: Deterministische Workflows für AI-Agenten

Inhalt

Was ist kraftwerk?
Warum feste Workflows statt freier Agenten?
Installation und erster Lauf
Einen eigenen Workflow bauen
Gates: Beweise statt Vertrauen
Script-Steps für alles Deterministische
Workflows vom Agenten schreiben lassen
Validieren, ausführen, nachvollziehen
Einsatz in CI und Automation
Workflows über Projekte hinweg teilen
Fazit

Was ist kraftwerk?

kraftwerk ist ein Open-Source-Framework von NETNODE, mit dem Sie AI-Agenten in feste, wiederholbare Workflows einspannen. Das Prinzip in einem Satz: Der Code besitzt den Ablauf, die Agenten arbeiten in klar begrenzten Phasen. Oder kürzer: "Agent proposes, code disposes."

Ein Workflow besteht aus einer YAML-Datei und ein paar Prompt-Dateien. Jede Phase startet einen kurzlebigen CLI-Prozess auf einem sogenannten Harness (Claude Code, Codex oder pi), lässt den Agenten seine Aufgabe erledigen und prüft danach das Ergebnis. Schlägt eine Prüfung fehl, geht der Fehler zurück in dieselbe Agenten-Session zur Korrektur. Kein Kaltstart, kein Raten.

Jeder Lauf hinterlässt ein vollständiges Event-Log (trace.jsonl) und endet mit einer Tabelle: Zeit, Tokens, Kosten pro Phase. Sie sehen also nicht nur, was herauskam, sondern auch, was es gekostet hat.

Das Paket heisst @netnodeag/kraftwerk auf npm und braucht keine Installation im Projekt: npx genügt.

Warum feste Workflows statt freier Agenten?

Wer AI-Agenten produktiv einsetzt, kennt das Problem: Derselbe Prompt liefert heute ein brauchbares Resultat und morgen etwas ganz anderes. Für einmalige Aufgaben ist das verkraftbar. Für Aufgaben, die jede Woche laufen sollen (Reports, Content-Produktion, Audits, Datenabgleiche), ist es ein Ausschlusskriterium.

kraftwerk löst das, indem es die Kontrolle umdreht. Nicht der Agent entscheidet, was als Nächstes passiert, sondern der Workflow. Der Agent bekommt pro Phase eine eng umrissene Aufgabe, definierte Werkzeuge und ein erwartetes Ergebnis in Form von Dateien. Der Code prüft nach jeder Phase, ob diese Dateien wirklich da sind und das Richtige enthalten.

Das Konzept steht in der Tradition von super-simple-software-factory: kleine, kontrollierte Agentenphasen statt eines grossen autonomen Agenten, der stundenlang vor sich hin arbeitet.

Für Ihr Projekt heisst das: Ein Workflow, der einmal funktioniert, funktioniert auch beim fünfzigsten Lauf. Und wenn er scheitert, sehen Sie im Trace genau, in welcher Phase und warum.

Installation und erster Lauf

Voraussetzung ist ein installiertes und eingeloggtes Claude Code (das Standard-Harness). Optional kommen Codex (via ChatGPT-Login) oder die pi-CLI für weitere Anbieter dazu. Dann:

cd ihr-projekt
npx @netnodeag/kraftwerk init
npx @netnodeag/kraftwerk run hello "Was ist kraftwerk?"

init legt drei Dinge an: eine kraftwerk.yml als Projektmarker, einen Ordner workflows/ mit einem Hello-Beispiel und ein output/-Verzeichnis für die Resultate (bereits in .gitignore). Ein package.json braucht es nicht. Ein Repository mit Workflow-Ordnern ist bereits ein vollständiger kraftwerk-Consumer.

Einen eigenen Workflow bauen

Ein Workflow ist ein Ordner unter workflows/ mit einer workflow.yml und Prompt-Dateien. Er wird automatisch erkannt, eine Registrierung gibt es nicht. So sieht ein Workflow aus, der aus einer Website eine Tagline schreibt:

workflows/tagline/
  workflow.yml
  prompts/analyze.md
  prompts/write.md

name: tagline
description: "Schreibt eine Tagline aus einer Website"
workspace: |
  Dateien: brand.md (Analyse), tagline.md (Resultat).
agents:
  analyst:
    model: haiku
    tools: [Read, Write, WebFetch]
    persona: |
      Du analysierst Marken anhand ihrer Website.
steps:
  - name: analyze
    agent: analyst
    prompt: prompts/analyze.md
    gates:
      - file_non_empty: brand.md
  - name: write
    agent: analyst
    prompt: prompts/write.md
    gates:
      - file_non_empty: tagline.md

Die wichtigsten Bausteine:

Agents definieren, wer arbeitet: Persona (System-Prompt), Modell, erlaubte Tools und das Harness (runs-on: claude | codex | pi). Ein Agent kann mehrere Phasen bedienen. Phasen auf demselben Harness teilen eine fortgesetzte Session, der Agent kennt also den bisherigen Verlauf.
Steps sind die Phasen. Jede Phase bekommt einen Prompt (eine Zeile = Dateipfad, mehrzeilig = Inline-Text) und Gates.
Prompts nutzen Platzhalter wie ${{ request }} (das CLI-Argument) und ${{ agent }}. Wichtig: Sagen Sie dem Agenten genau, welche Dateien er lesen und schreiben soll, relativ zum Run-Verzeichnis.

Eine Faustregel aus der Praxis: günstige Modelle überall dort, wo es um Fleissarbeit geht, teure Modelle nur dort, wo Urteilsvermögen zählt. Weil das Modell pro Agent konfiguriert wird, ist das eine Zeile YAML.

Gates: Beweise statt Vertrauen

Gates sind das Herzstück. Statt dem Agenten zu glauben, dass er fertig ist, prüft kraftwerk nach jeder Phase Dateibeweise:

file_non_empty: brand.md: die Datei existiert und ist nicht leer
contains: {file: report.md, text: "## Fazit"}: die Datei enthält einen bestimmten Text
slots_filled: vorgegebene Platzhalter wurden ausgefüllt

Schlägt ein Gate fehl, geht die Fehlermeldung zurück in dieselbe Agenten-Session, und der Agent korrigiert nach, begrenzt durch eine maximale Anzahl Versuche. Das ist der entscheidende Unterschied zu einem simplen Retry: Der Agent muss nicht von vorne beginnen, er sieht seinen eigenen Fehler und behebt ihn.

Zusätzlich beantwortet jede Phase einen typisierten JSON-Envelope, den die Engine automatisch an den Prompt anhängt und danach auswertet. In Ihren Prompts müssen Sie davon nichts erwähnen.

Script-Steps für alles Deterministische

Nicht alles braucht ein Sprachmodell. Daten abholen, Formate konvertieren, etwas messen: Das erledigt ein Shell-Script schneller und für null Rappen Tokenkosten. Dafür gibt es Script-Steps:

steps:
  - name: fetch
    run: scripts/fetch.sh

Das Script bekommt REQUEST, RUN_DIR und PHASE als Umgebungsvariablen und schreibt seine Resultate in dieselben Run-Dateien, mit denen die Agentenphasen arbeiten. Braucht ein Workflow Secrets, deklariert er sie mit requires: [MY_TOKEN]. Sie werden geprüft, bevor irgendetwas startet.

Workflows vom Agenten schreiben lassen

Sie müssen die YAML nicht von Hand schreiben. Der Befehl

npx @netnodeag/kraftwerk create "auditiere ein Repo und schreibe einen HTML-Report"

druckt einen in sich geschlossenen Bauauftrag: Schema-Beispiel, Gate-Regeln, Harness-Eigenheiten, eine Prüf-Leiter. Diesen Brief geben Sie Claude Code oder Codex, und der Agent baut den Workflow-Ordner, validiert ihn und macht einen Testlauf. Der Workflow-Autor ist damit selbst ein Agent, das Resultat aber wieder deterministisch ausführbar.

Validieren, ausführen, nachvollziehen

npx @netnodeag/kraftwerk validate   # Schema + Semantik, Exit 1 bei Fehlern
npx @netnodeag/kraftwerk run tagline "https://..."
npx @netnodeag/kraftwerk runs       # vergangene Läufe, runs show <id> für Details
npx @netnodeag/kraftwerk doctor     # Preflight: Harness-CLIs, Env-Variablen, Docker

Alle Artefakte und das trace.jsonl landen in output/<run>/. Die CLI funktioniert aus jedem Unterverzeichnis, sie wandert selbständig hoch bis zur kraftwerk.yml.

Einsatz in CI und Automation

Für Cron-Jobs, Pipelines und Webhooks gibt es einen Maschinenmodus:

KRAFTWERK_YES=1 npx @netnodeag/kraftwerk run tagline "https://..." --json > result.json

Das JSON-Resultat kommt auf stdout, alle Statusmeldungen landen auf stderr. Die Exit-Codes sind klar definiert: 0 für Erfolg, 2 für Konfigurationsfehler, 3 für einen fehlgeschlagenen Lauf. Damit lässt sich ein Agent-Workflow genauso in eine Pipeline hängen wie ein Testlauf oder ein Deployment.

Wer Läufe zusätzlich isolieren will, startet sie mit --sandbox in einem Docker-Container: Workflow-Ordner read-only gemountet, Resultate erscheinen live im eigenen output/.

Workflows über Projekte hinweg teilen

Workflows müssen nicht in jedem Projekt liegen. Mit --from führen Sie Workflows direkt aus einem Git-Repository aus:

npx @netnodeag/kraftwerk run --from github:NETNODEAG/workflows tagline "https://..."

Das Repository wird geklont und gecacht, der Workflow läuft lokal, die Artefakte landen in Ihrem output/. So pflegt ein Team eine zentrale Workflow-Bibliothek, ohne sie in jedes Projekt zu kopieren.

Fazit

kraftwerk beantwortet die Frage, wie aus AI-Experimenten verlässliche Bausteine werden: Der Ablauf gehört dem Code, der Agent arbeitet in begrenzten Phasen, und Datei-Gates prüfen jedes Ergebnis. Dazu kommen ein vollständiger Trace pro Lauf, eine Kostenübersicht und ein Maschinenmodus für CI.

Ein Beispiel aus unserem Alltag: Ein Report, der früher manuell mit einem Chat-Assistenten zusammengestellt wurde, läuft als kraftwerk-Workflow jeden Morgen um sieben, mit demselben Aufbau, geprüften Resultatdateien und einer Kostenzeile pro Lauf.

Die vollständige Referenz zu MCP-Servern, CLI-Grants und Sandbox-Läufen finden Sie im README des Pakets.

Lassen Sie uns darüber sprechen

Sie möchten wissen, wie deterministische Agent-Workflows Ihre wiederkehrenden Aufgaben übernehmen können? Wir beraten Sie gerne. Das erste Gespräch ist immer kostenlos.

Jetzt Kontakt aufnehmen