DSL Primitives

This page describes the previously published legacy APIs. For the 0.14.0 typed executable-DSL milestone, its supported capabilities and recovery limits, see Agent Workflow. Durable loops, timers and Workflow Journal projection are deferred.

Two Entry Points

// Named shortcuts — intent obvious from the first word
Workflow.sequential("pipeline").step(a).then(b).then(c).run(input);
Workflow.loop("refine").step(refineStep).times(5).run(draft);
Workflow.parallel("gather").step(review, audit, ciCheck).run(event);

// Full DSL — for gates, branches, decisions, error paths
Workflow.define("complex-flow")
    .step(fetch)
    .then(analyze)
    .gate(judgeGate).onPass(approve).onFail(revise).end()
    .run(event);

// Supervisor — LLM autonomously delegates to sub-agents
Workflow.supervisor("delegate", routingClient)
    .agents(codeReview, securityAudit, docUpdate)
    .until(result -> result.score() >= 0.9)
    .run(event);

Both surfaces produce a WorkflowGraph and support .run(input).

The Primitives

Sequential

Chain steps — output flows forward:

Workflow.define("pipeline")
    .step(write)
    .then(editForAudience)
    .then(editForStyle)
    .run(input);

Branch (predicate routing)

Route based on output:

Workflow.define("router")
    .step(classify)
    .branch(output -> "medical".equals(output))
        .then(medicalExpert)
        .otherwise(legalExpert)
    .run("I broke my leg");

Loop (while-do)

Exit condition checked before body:

Workflow.loop("refine")
    .step(refineStep)
    .until(result -> result.score() >= 0.8)
    .run(draft);

Loop (do-while / repeatUntilOutput)

Body runs first, exit condition reads actual output:

Workflow.define("score-loop")
    .repeatUntilOutput(score -> score instanceof Double d && d >= 0.8)
        .step(editor)
        .step(scorer)
    .end()
    .run(initialInput);

Gather (homogeneous fan-out)

Run steps concurrently, collect all results into a List<Object> that becomes the input to the next step. Use when all branches produce the same type and downstream needs everything together:

List<Object> results = (List<Object>) Workflow.define("gather")
    .gather(findMeals, findMovies)
    .run("romantic");

Chain directly into a join step:

String summary = (String) Workflow.<String, Object>define("parallel-review")
    .gather(reviewStep, auditStep)
    .then(Step.named("summarize", (ctx, in) -> {
        List<Object> parts = (List<Object>) in;
        return String.join("+", parts.stream().map(Object::toString).toList());
    }))
    .run("input");

Parallel (enrichment fan-out)

Run steps concurrently; the join passes the fork input through unchanged. Each branch writes its output to a named context key (Steps.outputOf(branchName)). Use when branches produce different types and downstream reads from context:

Step<String, String> reviewStep = Step.named("review", (ctx, in) -> "review-done");
Step<String, String> auditStep  = Step.named("audit",  (ctx, in) -> "audit-done");

Workflow.<String, Object>define("parallel-review")
    .parallel(reviewStep, auditStep)
    .then(Step.named("report", (ctx, in) -> {
        // in == fork input ("pr-123"), unchanged
        String reviewResult = ctx.get(Steps.outputOf("review")).orElseThrow();
        String auditResult  = ctx.get(Steps.outputOf("audit")).orElseThrow();
        return reviewResult + " | " + auditResult;
    }))
    .run("pr-123");

Parallel (dynamic fan-out)

Fan-out determined at runtime:

Workflow.define("batch")
    .parallel(
        ctx -> loadItems(),                    // items supplier
        item -> Step.named("process", (c, i) -> processItem(i))  // step factory
    )
    .run(null);

Decision (LLM-routed)

LLM picks which step to run:

Workflow.define("decision-router")
    .decision(chat)
        .option("summarize", summarizeStep)
        .option("translate", translateStep)
    .end()
    .run("The quick brown fox...");

Gate (quality checkpoint)

Approve, reject, or retry with feedback:

Workflow.define("gated-pipeline")
    .step(generate)
    .gate(new JudgeGate(jury, 0.8))
        .onPass(approve)
        .onFail(revise)
        .withReflector(reflectorStep)   // transforms verdict → feedback
        .maxRetries(3)
    .end()
    .run(input);

On failure, the full Verdict (score, reasoning, per-judge judgments) is written to AgentContext under JUDGE_VERDICT for the retry step to consume.

Supervisor (autonomous delegation)

LLM picks sub-agents each iteration:

Workflow.supervisor("text-improver", chat)
    .agents(review, edit, format)
    .until(ctx -> ctx.get(AgentContext.ITERATION_COUNT).orElse(0) >= 3)
    .run(roughDraft);

Error Recovery

Route exceptions to recovery steps:

Workflow.define("resilient")
    .step(riskyStep)
        .onError(TimeoutException.class, retryWithBackoff)
    .then(finalStep)
    .run(input);

BackTo (cyclic back-edge)

Jump back to an earlier step when a condition is met — a lightweight escape hatch for retry patterns:

Workflow.define("rebase-loop")
    .step(rebase)
    .step(runTests)
    .backTo("rebase", result -> !"PASS".equals(result))
    .step(merge)
    .run(branch);

backTo creates an EdgeCondition.BackEdge in the graph IR — a real edge, visible in traces. The next .step() chains from the same node (not the back-edge target), so merge runs when the predicate returns false. Use RunOptions.maxIterations() as a circuit breaker to prevent infinite loops:

.run(input, RunOptions.maxIterations(10));

When to use backTo vs repeatUntil: repeatUntil creates structured loop nodes (entry → body → check → exit). backTo is a single edge — no extra nodes, no loop wrapper. Use it when you need a quick “retry this section” without the overhead of a full loop construct.

Terminate

Exit early from anywhere:

Steps.terminate(WorkflowStatus.FAILED, "Quality below threshold")

Step Types

Steps are the atomic unit. Each wraps a different kind of execution:

Step Type	What It Wraps	Execution Time
`Step.named("n", lambda)`	Any lambda	Depends
`ChatClientStep.of(chat, template)`	Single Spring AI call	Seconds
`ClaudeStep.of(template)`	Full Claude CLI agent session	Minutes
`AgentClientStep.of(client, template)`	AgentClient abstraction	Minutes
`A2AStep.of(url)`	Remote A2A agent	Minutes
`Steps.of(fn)`	Pure deterministic function	Milliseconds
`Steps.retrying(n, step)`	Retry wrapper	Per attempt
`Steps.outputOf("step-name")`	Read prior step’s output	Instant

The key differentiator: ClaudeStep runs a full agentic loop internally — many turns, many tool calls, minutes of execution. The workflow sees it as one step. This is the opposite of frameworks where each LLM API call is a separate workflow activity.

Composability

Workflows implement Step<I, O>. Nest them freely:

var inner = Workflow.<String, String>define("inner")
    .step(analyze).then(classify).build();

Workflow.define("outer")
    .step(inner)        // workflow-as-step
    .then(report)
    .run(input);

RunOptions

Runtime constraints — not DSL verbs, hints to the executor:

Workflow.define("bounded")
    .step(expensiveStep)
    .run(input, RunOptions.maxCost(5.0)
        .withMaxIterations(50)
        .withMaxDuration(Duration.ofMinutes(10)));

The Graph IR

Every primitive compiles to real nodes and typed edges — not opaque lambdas:

A branch is 4 nodes (gateway → then-step, else-step → join) + 4 edges
A loop has a back-edge from body to entry
A parallel has fork and join nodes with BranchIndex edges

This makes workflows inspectable, traceable, and replayable. The TraceRecorder sees every transition; Markov analysis works on the edge data.

WorkflowGraph<String, String> graph = Workflow.define("my-flow")
    .step(a).then(b).compile();

graph.nodes()     // List<WorkflowNode> — sealed interface
graph.edges()     // List<WorkflowEdge> — typed conditions

Getting Started

Install, first workflow, four-layer architecture

Complete Examples

8 runnable integration tests validated against GPT-4.1

Projects

AgentWorks

Supporting Projects

Migration

Explorations

Older / Inactive Projects

Two Entry Points

The Primitives

Sequential

Branch (predicate routing)

Loop (while-do)

Loop (do-while / repeatUntilOutput)

Gather (homogeneous fan-out)

Parallel (enrichment fan-out)

Parallel (dynamic fan-out)

Decision (LLM-routed)

Gate (quality checkpoint)

Supervisor (autonomous delegation)

Error Recovery

BackTo (cyclic back-edge)

Terminate

Step Types

Composability

RunOptions

The Graph IR

Getting Started

Complete Examples

​Two Entry Points

​The Primitives

​Sequential

​Branch (predicate routing)

​Loop (while-do)

​Loop (do-while / repeatUntilOutput)

​Gather (homogeneous fan-out)

​Parallel (enrichment fan-out)

​Parallel (dynamic fan-out)

​Decision (LLM-routed)

​Gate (quality checkpoint)

​Supervisor (autonomous delegation)

​Error Recovery

​BackTo (cyclic back-edge)

​Terminate

​Step Types

​Composability

​RunOptions

​The Graph IR

​Related

Getting Started

Complete Examples

Two Entry Points

The Primitives

Sequential

Branch (predicate routing)

Loop (while-do)

Loop (do-while / repeatUntilOutput)

Gather (homogeneous fan-out)

Parallel (enrichment fan-out)

Parallel (dynamic fan-out)

Decision (LLM-routed)

Gate (quality checkpoint)

Supervisor (autonomous delegation)

Error Recovery

BackTo (cyclic back-edge)

Terminate

Step Types

Composability

RunOptions

The Graph IR

Related