Free Trial
Documentation menu

Workflows & steps

A workflow is the explicit, declarative form of a Jetty job. You define one in JSON rather than code, which is what makes workflows easy to generate, edit, and run dynamically, and how a no-code surface or an agent can assemble a pipeline on the fly.

The three keys

Every workflow is an object with exactly three keys:

  • init_params — the inputs to the run. Whatever you pass in lands here.
  • step_configs — a map of named steps. Each entry names an activity (the kind of work it does) plus the config that activity needs.
  • steps — the ordered list of step names to run.

A minimal example

{
  "init_params": { "user_prompt": "Explain quantum computing simply" },
  "step_configs": {
    "analyze": { "activity": "litellm_chat", "model": "gpt-4", "prompt_path": "init_params.user_prompt" }
  },
  "steps": ["analyze"]
}

One input, one step, one entry in the run order. The analyze step runs the litellm_chat activity and pulls its prompt from init_params.user_prompt.

Steps run activities

A step is an instance of an activity: the unit of work. Activities are things like litellm_chat (call an LLM), simple_judge (score an output against a rubric), or replicate_text2image (generate an image). The full catalog is the step library. Browse it in the step reference.

The same activity can appear many times under different step names — three litellm_chat steps with different models, for instance, are just three entries in step_configs.

Data flows through path expressions

Steps don't share variables. They read each other's data through path expressions: dot-notation strings that point at a value somewhere in the run. A step config field ending in _path takes a path instead of a literal value.

  • Read an input: init_params.prompt
  • Read another step's output: analyze.outputs.result.text
  • Index into an array: images[0].path
  • Fan across an array: results[*].score
  • Cross-workflow references resolve the same way.

So prompt_path: "init_params.user_prompt" means “use the value found at that path as this step's prompt.” Wire a later step to an earlier one by pointing its *_path at earlier_step.outputs.…, and the run order in steps guarantees the source has produced its output first.

Workflows and runbooks

Workflows and runbooks are two ways to describe the same kind of multi-step job:

  • A runbook is the agentic, markdown form. You write the goal and the guardrails in prose, and an agent figures out the steps as it goes.
  • A workflow is the explicit, declarative DAG. You spell out every step and every connection up front.

The two live side by side. Many runbooks compile down to workflow steps, or run alongside them, so you can start in prose and pin the parts you want to be deterministic into explicit steps.

Seeing the graph

Because the wiring is just paths between steps, Jetty can render any workflow as a dependency graph. The Workflow visualization in the app draws each step as a node and each path reference as an edge, so you can see the DAG before you run it and trace how data moved after.

Next: browse the full activity catalog in the step reference, or see complete workflows wired end to end in examples.