When Not to Use an Agent

Direct answer

Default left on the HazelJS spectrum:

single @hazeljs/ai call → @hazeljs/flow / saga → bounded AgentRuntime → open tool loop

Use AgentRuntime only when the next action must depend on unpredictable observations and you can operate budgets, tool contracts, and stop reasons.

Related: /compare/prompt-vs-workflow-vs-graph-vs-agent-loop, /patterns/augmented-llm.

Section 1 — Why “not yet” is a skill

Agent frameworks feel exciting. Shipping the wrong shape feels expensive later: cost spikes, duplicate refunds, and on-call pages nobody can debug.

For beginners, the winning move is often: prove the product value with a prompt or flow, then introduce autonomy for the pocket that actually needs it.

Section 2 — Decision table (print this)

Section 3 — Premature agent smells (with explanations)

1. Scripted stages dressed as tools

If every successful run calls tools A → B → C in the same order, that is a workflow. Encoding it as an open agent adds variance without buying flexibility.

2. Chat UI = agent

A controller that streams completions is a chatbot. Calling it an agent does not add AgentRuntime, budgets, or tool validation.

3. No stop condition

If you cannot name maxSteps, a budget, or a done check, you are not ready to ship autonomy. You are ready to write the one-pager from lesson 1.

4. Write tools without idempotency

Retries and resume will happen. Fix the adapter first (/patterns/idempotent-tool-execution) before giving the model a refund tool.

5. Ops unreadiness

No Inspector timeline, no owner, no kill switch → keep read-only or human-driven. Autonomy without ops is a demo with prod credentials.

Section 4 — When an agent is justified

Look for observation-driven branching:

• Ticket triage that searches, compares, then proposes a write
• Incident investigation across logs + changes + runbooks
• Research where retrieval results change the next query
• Support that must look up order state before mutating

Even then:

1. Start read-only
2. Keep maxSteps ≤ 8
3. Escalate autonomy only after describeAgent goldens pass

Section 5 — Cost of saying yes too early

Workflows are boring and operable. Prefer boring until the product demands observation-driven branching.

Section 6 — Practical exercise (bring to design review)

For one backlog feature, fill:

1. Goal (one sentence) + done check
2. Path uncertainty — low / medium / high
3. Side-effect class — none / reversible / irreversible
4. Chosen HazelJS structure — ai / flow / agent / hybrid
5. Why the left option fails — one paragraph

If you cannot explain why the left option fails, stay left.

Section 7 — Conversation starters (use with your team)

• “Is the path known enough for a flow graph?”
• “What is the stop reason we will log?”
• “Which tool is irreversible, and who approves it?”
• “What golden tasks must pass before we expand tools?”

Checkpoint

• You default left unless uncertainty is real
• You can name at least three premature-agent smells
• Your feature one-pager chooses a structure with a reason

What to do next

Open the runtime kernel model: /learn/agent-foundations/agent-runtime-mental-model