Workflow-YAML-Referenz

Ein Workflow ist ein gerichteter Graph aus typisierten Knoten, die durch Kanten verbunden sind, im visuellen Builder erstellt und als YAML serialisiert. Die kanonische Form wird durch ein einzelnes JSON-Schema definiert, das aus derselben Zod-Quelle generiert wird, gegen die die Web-App validiert (web/src/lib/api-schemas-workflow.ts). Dokument, Editor und Laufzeit können daher nie voneinander abweichen.

Editor-Validierung

Jeder aus dem Builder exportierte Workflow beginnt mit einer Modeline, die den yaml-language-server deines Editors auf das Schema zeigt und so Inline-Validierung sowie Autovervollständigung für Knotenarten bietet:

# yaml-language-server: $schema=https://supacloud.run/schemas/workflow.json
name: nightly-triage
nodes:
  - key: classify
    kind: llm_classify
    config: {}
edges: []

Hinweis

Das Schema wird aus Zod neu generiert; die eingecheckte Kopie wird in CI auf Abweichungen geprüft und stimmt daher immer mit dem laufenden Validator überein. Das config-Feld pro Knoten ist derzeit ein offenes Objekt; knotenspezifische Teilschemata folgen in einem späteren Schritt.

Felder auf oberster Ebene

Feld	Typ	Hinweise
name	string	Name des Workflows.
project_id	string	Das zugehörige Projekt.
nodes	array	Der typisierte Knotengraph (die V8-Builder-Oberfläche).
edges	array	Verbindungen zwischen Knoten, jeweils über source/target-Schlüssel.
steps	array	Die v1-agenten-seitige Schritt-Ansicht, für Rückwärtskompatibilität beibehalten.
max_concurrent_runs	integer | null	Begrenzt gleichzeitige Runs; null = unbegrenzt.

Knoten

Feld	Typ	Hinweise
key	string	Eindeutiger Knotenschlüssel (von Kanten referenziert).
kind	enum	Eine der unten aufgeführten Knotenarten.
config	object	Knotenart-spezifische Konfiguration (derzeit offenes Objekt).
position	{ x, y }	Canvas-Koordinaten im Builder.

Kante

Feld	Typ	Hinweise
source	string	key des Quellknotens.
target	string	key des Zielknotens.
source_handle	string	Welcher Ausgangs-Handle die Kante verlässt (Standard out; Gates verwenden Branch-Handles).

Knotenarten

Art	Zweck
agent	Führt einen KI-Coding-Agenten mit einem Prompt aus.
gate	Verzweigt anhand eines Prädikats auf verschiedene Ausgangs-Handles.
human	Hält an und wartet auf eine menschliche Entscheidung oder Eingabe.
end	Terminalknoten.
code	Führt ein Bash/Python/TypeScript/Go/Rust/C#-Snippet aus (Standard: Bash). Ungebunden: hermetischer Container, kein Netzwerk/DB. Ein Python/TypeScript-Node kann resource_bindings deklarieren, um in der berechtigungsgeführten Sandbox mit geprüftem Egress + host-vermitteltem, abgesichertem DB-Aufruf zu laufen (ADR 0058).
db_query	Liest aus einer gebundenen PostgreSQL-Ressource.
db_execute	Schreibt in eine gebundene PostgreSQL-Ressource.
http_request	Führt einen ausgehenden HTTP-Aufruf durch (SSRF-geschützt, IP-gebunden).
transform	Formt Daten zwischen Knoten um.
notify_telegram	Sendet eine Telegram-Nachricht.
notify_email	Sendet eine E-Mail.
notify_webhook	Sendet einen POST-Request an einen Webhook.
notify_discord	Sendet eine Discord-Nachricht.
loop	Iteriert über eine Sammlung.
wait_event	Hält an, bis ein externes Ereignis eintrifft.
llm_classify	Klassifiziert Eingaben mit einem LLM.
imap_ack	Bestätigt eine IMAP-Nachricht.
app	Ruft eine bereitgestellte App auf.
connector	Führt einen Marketplace-Connector-Knoten aus.

Ergebnisse vorgelagerter Knoten gelangen über SC_NODE_INPUTS an einen Knoten; ein Trigger-Payload über SC_TRIGGER_CONTEXT. Wie du einen Workflow im visuellen Builder erstellst, zeigt das Tutorial „Deinen ersten Workflow erstellen“.