Foundation~20 minHazelJS
Prompt vs Workflow vs Graph vs Agent Loop
Choose among prompt, HazelJS flow/graph, and @hazeljs/agent loops—criteria-weighted, HazelJS-centered.
- Authors
- editorial-team
- Published
- Last reviewed
- Intended use case
- Choosing a control structure for a new LLM-powered capability when path uncertainty, side effects, and ops maturity vary.
- Evaluation date
- 2026-08-01
Criteria and weights
| Criterion | Weight | Description |
|---|---|---|
| Fit for path uncertainty | 0.25 | How well the structure handles unknown branching at design time |
| Cost/latency predictability | 0.2 | Variance in runtime and spend |
| Auditability & testability | 0.2 | |
| Side-effect governance | 0.2 | Ease of gating, idempotency, and recovery |
| Operational complexity (lower is better conceptually) | 0.15 | Day-2 burden relative to benefit |
Options
Single prompt / @hazeljs/ai call
Best for: Classification, extraction, drafting, and grounded Q&A with at most a small fixed tool budget
- Minimal moving parts in a HazelJS DI service
- Easiest latency and cost bounding
- Straightforward unit testing of inputs/outputs
- Poor fit when many adaptive tool steps are required
- Hidden multi-tool retries can accidentally become an unmanaged loop
Deterministic workflow (@hazeljs/flow / saga)
Best for: Known multi-stage business processes with optional LLM enrichment at nodes
- Explicit stages and contracts in the same DI app
- Mature retry/compensation patterns
- Strong audit story for compliance
- Painful when branches explode into unmaintainable graphs
- LLM nodes can become opaque if overused
Typed graph / state machine (flow graph)
Best for: Product flows with known states plus selective adaptive pockets
- First-class branching and state
- Better visualization and edge testing than ad-hoc code
- Can embed a bounded AgentRuntime node for messy subgraphs
- Graph sprawl if used as a dumping ground for prompts
- Still needs PolicyEngine budgets and Skillgate for autonomous nodes
AgentRuntime loop (@hazeljs/agent)
Best for: Branchy tool use under uncertainty when the team can operate budgets, Inspector timelines, and approvals
- Best coverage when next actions depend on observations
- Natural fit for investigation-style tasks with ToolRegistry
- Composes with flow as a node or as a caller of playbooks
- Highest variance in cost/latency
- Requires durable runs, HITL, evals, and policy to be production-safe
Architectural differences
In HazelJS these options differ by **who owns control flow**. A single `@hazeljs/ai` call leaves control in one model invocation. `@hazeljs/flow` (and saga) encode control in designer-specified edges. `AgentRuntime` in `@hazeljs/agent` hands step selection to a model under PolicyEngine budgets, ToolRegistry/Skillgate/MCP tools, and optional durableSuspend. Graphs are not automatically agents; agent loops are not automatically graphs—though a flow graph can host a bounded AgentRuntime node.
Operational implications
Moving toward AgentRuntime increases the need for checkpoints, idempotent tools, HITL gates, eval harnesses, and cost controls. Prefer the leftmost HazelJS structure that still handles your uncertainty—then harden with Agent OS practices (DNA, Inspector, run stores).
How to use this comparison (HazelJS)
Do not pick AgentRuntime because it sounds advanced. Score your use case against the criteria, then choose the simplest HazelJS control structure that fits path uncertainty and risk.
| Choice | Prefer in HazelJS |
|---|---|
| Prompt | @hazeljs/ai (or thin controller) |
| Workflow / graph | @hazeljs/flow / saga |
| Agent loop | @hazeljs/agent AgentRuntime + ToolRegistry |
Related reading: /learn/agent-foundations/agent-vs-workflow-vs-chatbot, /patterns/tool-using-agent, /patterns/augmented-llm, /agent-os.
Practical decision rule
- If a single augmented call works → stop at
@hazeljs/ai. - If stages are stable →
@hazeljs/flow/ saga. - If only a subgraph is messy → AgentRuntime node inside a flow graph.
- If the whole task is observation-driven → AgentRuntime with budgets, Skillgate/MCP tools, and evals.
Hybrids
Production HazelJS systems often combine options: a flow invokes AgentRuntime for research, then returns to deterministic notification steps. Treat hybrids as a feature, not a failure to choose.
Sources
- HazelJS Agent OS guide — Primary stack map for runtime vs workflow layers
- HazelJS Agent package — AgentRuntime / AgentRun APIs
- Building effective agents — Argues for simplest effective architecture; engineering context only