Project 6: Workflow-First Orchestrator
Quick Reference
| Attribute | Value |
|---|---|
| Difficulty | 4 |
| Time | 2-3 weeks |
| Main Stack | jido + strategy-based workflows + req_llm |
| Alternatives | One-shot function pipelines |
| Why Now | Most real systems need reliable multi-step orchestration |
What You Will Build
An orchestrator that coordinates multiple agents and tool calls using explicit workflows: intake -> plan -> execute -> verify -> summarize.
Real World Outcome
$ mix run -e "OrchestratorDemo.execute(\"release-notes\")"
[info] orchestrator=release-orch-1
[info] step=collect_input result=ok
[info] step=extract_requirements result=ok
[info] step=draft_notes result=ok
[info] step=peer_review result=ok
[info] step=publish_draft result=ok
[info] completion=ok elapsed_ms=4300
Expected artifact:
- structured log of step transitions
- one final artifact with deterministic step states and evidence map
The Core Question You Are Answering
“How do we keep agentic workflows composable when each action can branch, fail, and trigger compensating steps?”
Why This Project Matters
Jido emphasizes state + directive separation, which is ideal for workflow engines. A workflow project makes that explicit: planning is separate from execution and effects are explicit directives from each step.
Architecture Diagram
+-------------------------+
| Workflow Definition |
| - steps graph |
| - transitions |
+------------+------------+
|
v
+----------------------+
| Orchestrator Agent |
| state: active_step |
| state: checkpoint |
+----------+-----------+
|
+-------------------+-------------------+
| | |
v v v
+----------+ +--------------+ +--------------+
| Worker A | | Worker B | | Worker C |
| (extract)| | (transform) | | (review) |
+----+-----+ +------+-------+ +------+-------+
| | |
+--------+------------+--------------------+
|
v
+------------------------+
| Directive Aggregator |
| validation + retries |
| emits next action set |
+-----------+------------+
|
v
+---------------+
| Final Artifact|
+---------------+
Deep Dive Steps
1. Define Workflow as Data
Create deterministic workflow map:
- step name
- input requirements
- success condition
- failure handler path
2. Implement Step Actions
Each step is a Jido action module:
- pure transition
- output directive list
- optional nested agent invocation
3. Add Routing Rules
Rules should encode:
on_success,on_retry,on_fail- timeouts and retry windows
- idempotency markers
4. Add LLM Assistance as a Step
Use req_llm as one action source:
- text refinement
- extraction summaries
- policy-safety checks
5. Persistence and Replay
Persist:
- step events
- transition decisions
- failure reasons Allow replay from checkpoint for incident analysis.
Concepts You Must Understand First
- Workflow graphs
- DAG vs cyclic flow and explicit guards.
- Transition semantics
- What transitions are terminal?
- Directive propagation
- Keep effect execution isolated from state update.
- LLM step contracts
- Bound response size, schema, and confidence.
Questions to Guide Your Design
- Determinism
- How do you ensure same input leads to same transitions?
- Compensation
- Which steps need rollback or undo equivalents?
- Concurrency
- Can steps be parallel and still replayable?
Thinking Exercise
Sketch a workflow for “create support playbook entry”:
- Intake issue
- Classify urgency
- Draft action items
- Ask review agent
- Publish
Mark where each transition can fail and what fallback path you choose.
Interview Questions They Will Ask
- “How do FSM-style workflows differ from plain action chains?”
- “How do you prevent hidden side effects during step planning?”
- “Where does retry policy live in a jido architecture?”
- “How do you attach evidence for each step?”
- “How do you combine deterministic workflows with nondeterministic LLM responses?”
Hints in Layers
Hint 1: Start with 4-step workflow Avoid overbuilding before state model is stable.
Hint 2: Add explicit step schemas Each step should declare required and optional outputs.
Hint 3: Keep transitions pure Transition function decides next step only.
Hint 4: Test failure routes first Write the failure tests before complex success path implementation.
Common Pitfalls and Debugging
- Problem: Workflow gets stuck in loop.
- Why: no terminal transition for one state.
- Fix: add explicit max step/guard for loops.
- Quick test: fuzz 100 action histories and assert bounded transitions.
- Problem: LLM action changes order unpredictably.
- Why: unconstrained extraction output.
- Fix: contract outputs and explicit parser validation.
- Quick test: rerun same seed and compare step trace.
- Problem: Replay diverges from runtime result.
- Why: missing timestamp-dependent transitions.
- Fix: keep external dependencies explicit in context and snapshots.
- Quick test: deterministic replay against stored transitions.
Books That Will Help
| Topic | Book | Chapter |
|---|---|---|
| Workflow design | Designing Distributed Systems | Saga and workflow patterns |
| Elixir concurrency | The Little Elixir & OTP Guidebook | Supervisors and event flow |
Definition of Done
- Workflow transitions are defined as declarative data
- each step has explicit success/failure policy
- req_llm-powered steps are schema-constrained
- failure traces and replay logs are stored
- end-to-end run completes deterministically in normal paths
References
- https://hexdocs.pm/jido/2.0.0-rc.4/readme.html
- https://hexdocs.pm/jido/2.0.0-rc.4/readme.html#The%20
cmd/2%20Contract