Bounded Runs, Budgets, and Stop Reasons

Direct answer

An agent without a budget is a cost and safety incident waiting to happen. In HazelJS, hard stops live on the runtime and agent config, not only in the system prompt.

Why beginners get burned

1. The model retries a failing tool forever.
2. A bad observation causes “try again” loops that spend the monthly API budget overnight.
3. Ops sees “failed” with no reason — cannot tune autonomy.

Step 1Set two nested limits

@Agent({
  name: 'ops-desk',
  description: 'Read-only order status desk',
  systemPrompt: 'Use lookupOrder. Stop when you can answer.',
  maxSteps: 6, // inner think→act ceiling
})
export class OpsDeskAgent { /* … */ }

const result = await runtime.execute(
  'ops-desk',
  'What is the status of ORD-1001?',
  {
    loop: {
      maxIterations: 3, // outer plan→execute→critique→validate passes
      stages: ['plan', 'execute', 'critique', 'validate'],
    },
  }
);

Start low (maxSteps 4–8). Raise only when golden tests show the agent needs more room.

Step 2Later production knobs (preview)

You will meet these again in the checklist lesson. Know they exist:

Do not enable all of them on day one. Learn the simple caps first.

Step 3Always persist why it stopped

Operators need a stop reason such as:

• success / completed
• max steps reached
• budget exhausted
• policy denied
• cancelled
• suspended (waiting for human)

If your starter only logs the final string, add timeline / run store wiring (lesson 7) before you invite real traffic.

Step 4Exercise: force a stop

Temporarily set maxSteps: 1 and ask a goal that needs a tool. Confirm the run stops predictably and you can see that in logs. Then restore a sane budget.

Checkpoint

• maxSteps and loop.maxIterations are set consciously (not copy-paste leftovers)
• You can explain the difference between prompt advice and runtime caps
• You know which stop reasons you will log in production

What to do next

Keep observations small: /learn/agentic-development/context-windows-as-scarce-resources