Graphs Examples

Two runnable examples demonstrate the Graph state-machine workflow construct using deterministic handler tasks (no LLM required, completely offline). The same patterns work with AI-backed tasks — replace the handlers with descriptions and provide a chatLanguageModel(...) on the ensemble.

Tool router with back-edges

A tool-routing state machine: an analyze state inspects input and routes to one of two tool states; each tool returns to analyze; eventually analyze terminates. Demonstrates conditional edges, unconditional fallback, back-edges, and the per-step onGraphStateCompleted callback.

./gradlew :agentensemble-examples:runGraphRouter

Source: GraphRouterExample.java.

Sample output (truncated):

Step 1/20: analyze → toolA
Step 2/20: toolA → analyze
Step 3/20: analyze → toolB
Step 4/20: toolB → analyze
Step 5/20: analyze → toolA
Step 6/20: toolA → analyze
Step 7/20: analyze → __END__
Termination: terminal
Total steps: 7
Path: [analyze, toolA, analyze, toolB, analyze, toolA, analyze]

Selective feedback

A quality-gated publishing pipeline: research → write → critique → publish, where critique can route back to write on REJECT without re-running research. Demonstrates the pattern Loop cannot cleanly express — back-edges that target a specific upstream state rather than re-iterating the whole body.

./gradlew :agentensemble-examples:runGraphRetryWithFallback

Source: GraphRetryWithFallbackExample.java.

Notice in the output that research runs exactly once even though write runs three times — the back-edge from critique targets write specifically, not research.

See also

• Graphs guide — full reference for routing, validation, termination, state revisits, and visualisation.
• Loops examples — bounded iteration patterns; useful for the simpler reflection / retry-until-valid use cases that don’t need state-machine routing.