Typed Workflow Tutorial

This tutorial uses the 0.14.0 executable DSL and deterministic Java Steps. It makes no provider calls and needs no API key. 0.14.0 is available on Maven Central. Durable loops, waits/timers and committed-event Journal projection are unavailable in this milestone.

Run the progression

Clone the example repository (main). With Java 21, run the parentless module:

./mvnw -f executable-dsl/pom.xml compile exec:java -Dexec.args=/tmp/workflow-tutorial

Maven resolves Agent Workflow 0.14.0 and Agent Judge 0.18.0 from Maven Central. Run the command again with the same directory to reuse committed results. The program asserts every expected result, all four Verdict routes, and the thrown-evaluation failure. The eight older provider comparison modules stay separate from this build.

1. Two sequential Steps

The request is the root value. Fetch produces a Diff; WriteReport needs both the request and that diff. Its record input declares those dependencies directly.

public record Request(String repository, int number) {}
public record Diff(String revision, String text) {}
public record ReportInput(Request request, Diff diff) {}
public record Report(String text) {}

var fetch = new Fetch("revision-17");
var report = new WriteReport();
var workflow = Workflows.define("sequential-review")
    .then(fetch).then(report).terminate(SUCCEEDED).build();

public static final class Fetch implements Step<Request, Diff> {
    private final String revision;
    public Fetch(String revision) { this.revision = revision; }
    public Diff execute(StepContext context, Request input) {
        return new Diff(revision, "Add coverage");
    }
}
public static final class WriteReport implements Step<ReportInput, Report> {
    public Report execute(StepContext context, ReportInput input) {
        return new Report(input.request().repository() + "#" + input.request().number()
            + " " + input.diff().revision());
    }
}

The compiler assembles ReportInput from legally visible typed values. You do not write bindings, casts, context keys or explicit builder type arguments. See the complete Sequential.java.

2. Reuse a nested workflow

The child receives a Diff and returns an Assessment. The caller keeps its earlier Request; the child exposes its declared result.

public record Request(String repository) {}
public record Diff(String text) {}
public record Assessment(boolean acceptable) {}
public record ReportInput(Request request, Assessment assessment) {}
public record Report(String repository, boolean acceptable) {}

var assess = new Assess("TODO");
var reusable = Workflows.define("assess-diff")
    .then(assess).terminate(SUCCEEDED).build();
var workflow = Workflows.define("nested-review")
    .then(fetch).subWorkflow("quality", reusable)
    .then(report).terminate(SUCCEEDED).build();

Register the same assess instance used to define the child. The definition reuses composition; constructor injection supplies the implementation. See Nested.java.

3. Route exhaustively on an enum

Choose implements Step<Request, Route>. The enum controls routing; each review still receives the request. Both arms return a Report, so the workflow can terminate after the choice.

public record Request(boolean documentationOnly) {}
public enum Route { QUICK, FULL }
public record Report(String text) {}

var workflow = Workflows.define("enum-review")
    .decision("review-depth", choose)
        .when(Route.QUICK).then(quick)
        .when(Route.FULL).then(full)
    .end().terminate(SUCCEEDED).build();

Every enum constant needs exactly one arm. end() closes the choice; terminate(SUCCEEDED) declares execution completion. See EnumDecision.java.

4. Route a native Verdict

Assess implements Step<Request, Verdict> and invokes a native Judge Jury. This fixture chooses deterministic judgments through its request; production Steps would supply their actual evidence. The branch receives the complete assessment, its selected conclusion and the original request.

public record Request(Verdict.Conclusion fixture, boolean throwFailure) {}
public record ReviewInput(Request request, Verdict assessment, Verdict.Conclusion conclusion) {}
public record Report(String heading, Verdict.Conclusion conclusion, List<String> evidence) {}

var workflow = Workflows.define("native-review")
    .verdict("quality", assess)
        .when(PASS).then(passed)
        .when(FAIL).then(failed)
        .when(INCONCLUSIVE).then(inconclusive)
        .when(NOT_APPLICABLE).then(excluded)
    .end().terminate(SUCCEEDED).build();

FAIL is a valid negative assessment, and this workflow successfully returns a changes-requested report. The fixture’s INCONCLUSIVE assessment retains both ERROR: Scanner unavailable and ABSTAIN: No evidence. A thrown evaluation ends with ASSESSMENT_FAILED; an unusable Verdict ends with ASSESSMENT_INVALID. Neither failure invents an INCONCLUSIVE assessment. The accepted assessment, selected route and exact first executable branch input commit together. See NativeVerdict.java.

5. Parallel assessments and a typed report

AssessQuality takes Diff; AssessBackport takes BackportInput assembled from the request and diff. Their distinct output records declare distinct report roles.

public record Request(String repository) {}
public record Diff(String revision) {}
public record Quality(boolean acceptable) {}
public record Backport(boolean suitable) {}
public record BackportInput(Request request, Diff diff) {}
public record ReportInput(Request request, Quality quality, Backport backport) {}
public record Report(String repository, boolean acceptable, boolean suitable) {}

var workflow = Workflows.define("parallel-review")
    .then(fetch).parallel("assessments").allSuccessful()
        .branch("quality").then(quality)
        .branch("backport").then(backport)
    .end().then(report).terminate(SUCCEEDED).build();

Branches see their own work and the outer values saved when the group opens. They cannot read sibling-private values. The join publishes completed branch results for the report’s typed input. A returned Quality(false) is a value; an execution failure prevents the successful join. Admitted work settles before failure is reported. See ParallelAssessments.java.

6. Discover files and fan out at runtime

DiscoverFiles implements Step<ReviewRequest, List<FilePatch>>. ReviewFile implements Step<FilePatch, FileReview>. WriteReport receives the ordered review results and earlier request.

public record ReviewRequest(String revision) {}
public record FilePatch(String path, String diff) {}
public record FileReview(String path, boolean acceptable) {}
public record ReportInput(ReviewRequest request, List<FileReview> reviews) {}
public record Report(String revision, List<FileReview> reviews) {}

var workflow = Workflows.define("review-changed-files")
    .then(discoverFiles)
    .forEach("files").maxItems(40).maxInFlight(4).allSuccessful()
        .then(reviewFile)
    .end().then(writeReport).terminate(SUCCEEDED).build();

maxItems refuses oversized input before item effects; it never truncates. The durable manifest fixes membership and order before item work starts. Each occurrence has a distinct index identity, even when two values are equal. maxInFlight limits admitted, unsettled item bodies; an item waiting for descendants keeps its occupancy. Physical Step capacity is a separate runtime setting. Completion order never changes the returned list order; empty input returns an empty list. No successful join can omit a failed item’s result. See FanOut.java.

Register objects and configure execution

The definition contains authored Steps and control flow. The registry names the supplied Step objects; runtime configuration chooses physical capacity and deployment compatibility.

var registry = StepRegistry.of(Map.of("fetch", fetch, "report", report));
var deployment = new ExecutionCompatibility("review-app", "review-app-build-17",
    Map.of("fixture", "deterministic"));
var policy = new ExecutionPolicy(3, 32, 10_000, 2);
try (var runtime = DurableWorkflows.open(directory, registry, deployment, policy)) {
    var run = runtime.start(workflow, "pr-42", new Request("widgets", 42));
    var completed = runtime.resume(run.runId(), workflow);
    var result = runtime.result(run.runId(), workflow);
}

The map above holds registration or compatibility metadata, never business values. StepContext supplies run, invocation and attempt metadata. The tutorial harness ExampleRunner.java asserts expected results without casting or choosing an execution path. For store compatibility and unresolved-effect limits, read Durability. Sequence.build() is available starting in 0.14.0 for a parent ending in an always-failing/cancelling child; see the API reference.

Projects

AgentWorks

Supporting Projects

Migration

Explorations

Older / Inactive Projects

Run the progression

1. Two sequential Steps

2. Reuse a nested workflow

3. Route exhaustively on an enum

4. Route a native Verdict

5. Parallel assessments and a typed report

6. Discover files and fan out at runtime

Register objects and configure execution

​Run the progression

​1. Two sequential Steps

​2. Reuse a nested workflow

​3. Route exhaustively on an enum

​4. Route a native Verdict

​5. Parallel assessments and a typed report

​6. Discover files and fan out at runtime

​Register objects and configure execution

Run the progression

1. Two sequential Steps

2. Reuse a nested workflow

3. Route exhaustively on an enum

4. Route a native Verdict

5. Parallel assessments and a typed report

6. Discover files and fan out at runtime

Register objects and configure execution