Workflows

Ein Workflow ist eine unter einem Namen gespeicherte Ausführungsdefinition. Er enthält Prompt, Modell, Dateien, Verbindungen, Zeitlimit sowie die Shell- und Web-Einstellungen. Ihr Code startet ihn über den Namen und sendet nur, was sich von Ausführung zu Ausführung ändert.

{
  "workflow": "investigate-payment",
  "input": { "payment_id": "pay_123" },
  "max_cost_micros": 500000
}

Was gespeichert wird und was jede Ausführung sendet

Speichern Sie einen Workflow im Dashboard unter Workflows, mit PUT /v1/workflows/{name} oder mit ephemeral workflows save. JSON ist das Übertragungsformat; die CLI liest auch YAML. Namen beginnen mit einem Buchstaben oder einer Ziffer und dürfen Buchstaben, Ziffern, _, . und - enthalten, bis zu 128 Zeichen.

Gespeicherte Felder überschreiben

Jedes der Felder prompt, model, files, connections, timeout_seconds, shell und web in der Ausführungsanfrage ersetzt den gespeicherten Wert nur für diese Ausführung. Dateien und Verbindungen werden als ganze Sammlung ersetzt. Sie werden nie mit den gespeicherten zusammengeführt.

{
  "workflow": "investigate-payment",
  "input": { "payment_id": "pay_123" },
  "connections": {},
  "max_cost_micros": 500000
}

Ein leeres Objekt oder Array leert diese Sammlung für die Ausführung. Um eine einzelne Verbindung oder Datei zu ändern, senden Sie die vollständige Liste, die die Ausführung haben soll.

Wann Verweise aufgelöst werden

Ein Workflow verweist über Namen auf Dateien und gespeicherte Verbindungen. Ephemeral löst diese Namen beim Erstellen der Ausführung auf, und die Ausführung behält das Aufgelöste. Ein Dateiname wird zum neuesten Upload mit diesem Namen aufgelöst. Wenn Sie also eine neue Version von playbook.md hochladen, ändert sich, was die nächste Ausführung liest, ohne dass Sie den Workflow bearbeiten.

Existiert eine referenzierte Datei oder Verbindung nicht mehr, schlägt die Ausführungsanfrage mit 400 fehl und nennt den fehlenden Verweis. Es wird nichts in die Warteschlange gestellt und nichts berechnet.

Eingabe und Ausgabe beschreiben

Drei optionale Felder lassen einen Workflow sich selbst beschreiben, damit Personen, anderer Code und KI-Agents wissen, wie sie ihn aufrufen, ohne den Prompt zu lesen. description sagt in ein bis zwei Sätzen, was der Workflow tut und welche Eingabe er erwartet (bis zu 500 Zeichen). input_schema ist ein JSON Schema, dem die input der Ausführung entsprechen muss. output_schema ist ein JSON Schema, dem die Ausgabe der Ausführung entsprechen muss. Alle drei liefern GET /v1/workflows?detail=true und das MCP-Tool list_workflows; sie funktionieren auch bei einer Inline-Ausführung.

description: Current weather for a city. Input is a city name.
prompt: Look up the current weather for the city in the input and report it.
web: true
input_schema:
  type: object
  required: [city]
  properties:
    city: { type: string }
output_schema:
  type: object
  required: [city, temperature_c, summary]
  properties:
    city: { type: string }
    temperature_c: { type: number }
    summary: { type: string }

Die Eingabe wird geprüft, wenn eine Ausführung erstellt wird, ob über die API, die CLI, ein MCP-Tool oder einen Zeitplan. Passt sie nicht, schlägt die Anfrage mit 400 fehl und nennt jedes Problem als Pfad und Grund, etwa input.city: required. Nichts wird eingereiht und nichts berechnet. Die Eingabe eines Zeitplans wird beim Erstellen oder Ändern des Zeitplans geprüft und bei jedem Start erneut; ein Start, der nicht mehr passt, wird als letzter Fehler des Zeitplans festgehalten.

Die Ausgabe muss JSON sein, das zu output_schema passt. Der Agent erhält das Schema und soll nur das JSON antworten. Passt seine Antwort nicht, bekommt er die genauen Fehler und soll sie korrigieren, bis zu zweimal. Danach prüft Ephemeral die Ausgabe noch einmal: Passt sie, bleibt die Ausführung succeeded, mit dem JSON-Text als Ausgabe und ohne Codeblock darum. Passt sie nicht, endet die Ausführung mit failed und einem error wie output did not match output_schema: output.temperature_c: got string, want number; der Ausgabetext bleibt erhalten, damit Sie sehen, was der Agent geschrieben hat. Eine Ausführung mit Zero Data Retention behält keine Details im Fehler.

Schemas nutzen JSON Schema Draft 2020-12 (ein $schema, das Draft 7 oder älter nennt, funktioniert ebenfalls), je höchstens 32 KiB, und dürfen nur auf Definitionen innerhalb des Schemas verweisen, etwa #/$defs/address. Ein ungültiges Schema wird mit 400 abgelehnt, wenn der Workflow gespeichert oder die Ausführung erstellt wird.

Einen Workflow bearbeiten

Erneutes Speichern eines Workflows ersetzt ihn. Es gibt keinen Versionsverlauf. Vor der Änderung erstellte Ausführungen behalten die Definition, mit der sie erstellt wurden; um genau zu sehen, was eine Ausführung verwendet hat, lesen Sie ihre Definition.

Beim Lesen eines Workflows werden Verbindungszugangsdaten und URL-Geheimnisse entfernt. Wenn Sie ihn ohne diese Felder wieder speichern, bleiben die hinterlegten Zugangsdaten erhalten, solange der Authentifizierungstyp gleich bleibt.