Foundation~245 minHazelJS
Agentic Development
Beginner end-to-end HazelJS course: scaffold Ops Desk, tool loop, budgets, context hygiene, HITL writes, golden tests, observability, CLI, and go-live checklist.
- Authors
- editorial-team
- Published
- Last reviewed
Course promise
A full beginner path to build production-minded agents on HazelJS — not a pile of disconnected tips.
You ship one continuous project: Ops Desk, which looks up order ORD-1001, then grows budgets, context hygiene, human-approved refunds, golden tests, observability, and a launch checklist.
Who this is for
- Engineers new to agentic AI who already know TypeScript basics
- People who finished Agent Foundations and want to build
- Teams standardizing on
@hazeljs/agent/ Agent OS
How to take the course
- Follow lessons in order — each checkpoint unlocks the next.
- Prefer
createMockLlmProvideruntil tools behave; then swap a real@hazeljs/aiprovider. - Keep a sticky note with goal / done / non-goals for Ops Desk.
- Use the companion guide /guides/build-your-first-tool-using-agent when you want a single long lab session.
Lesson map
| # | Lesson | You leave with |
|---|---|---|
| 01 | Scaffold | Runnable project + mock runtime |
| 02 | Tool loop | @Agent + lookupOrder + execute |
| 03 | Budgets | maxSteps / stop reasons |
| 04 | Context | Truncated, structured observations |
| 05 | HITL writes | processRefund + approval path |
| 06 | Golden tests | describeAgent CI gate |
| 07 | Observability | Timeline / executionId runbook |
| 08 | CLI ops | doctor / logs / stub vs app execute |
| 09 | Checklist | Go/no-go for production |
Docs anchors: Agent package, Agent OS.
Learning outcomes
- Scaffold and run a HazelJS AgentRuntime project with a mock or real LLM
- Build a read-first Ops Desk with budgets, truncated observations, and approved writes
- Add describeAgent goldens, timelines, CLI ops, and a production go/no-go checklist
Lessons
- 01Scaffold Your First HazelJS AgentSet up a runnable HazelJS project, install packages, choose mock vs real LLM, and verify the environment before writing tools.
- 02Tool-Using Agent LoopBuild a read-only Ops Desk: @Agent + @Tool, register on AgentRuntime, execute a goal, and follow one full think→act→observe cycle.
- 03Bounded Runs, Budgets, and Stop ReasonsMake Ops Desk safe to run: maxSteps, loop.maxIterations, reading stop reasons, and why prompts alone cannot cap cost.
- 04Context Windows as Scarce ResourcesTreat every tool observation as a budgeted input: truncate, structure, redact, and turn memory/RAG on only when the job needs it.
- 05Safe Writes, Approvals, and HITLAdd a refund tool the right way: side-effect classes, requiresApproval, PolicyEngine, and durableSuspend so humans can approve without hanging workers.
- 06Golden Tests with describeAgentProtect Ops Desk with @hazeljs/testing: expectTools, forbidden tools, and a tiny CI gate before you change prompts.
- 07Observability Signals for Agent DecisionsDebug Ops Desk with timelines and traces: executionId, tool calls, stop reasons, cost, and HITL waits on HazelJS.
- 08Hazel CLI Agent OpsUse hazel agent doctor, run, logs, and runs — and know DNA smoke stubs are not the same as app runtime.execute.
- 09From Demo to Production ChecklistCapstone: promote Ops Desk using Agent OS gates — HITL, budgets, durable stores, policies, tests, Inspector, DNA, and ownership.
Capstone: Ops Desk v1: read-only status lookups in an internal audience, refunds behind approval, describeAgent green in CI, timeline runbook signed off.