Intermediate~22 minHazelJS
Agent Framework vs Runtime vs Agent OS
Clarify HazelJS layers: @hazeljs/agent as runtime kernel, Skillgate/MCP as skills, and Agent OS control-plane concerns—without crowning unrelated products.
- Authors
- editorial-team
- Published
- Last reviewed
- Intended use case
- Deciding what to build or buy when moving from local agent experiments to shared platform capabilities.
- Evaluation date
- 2026-08-01
Criteria and weights
| Criterion | Weight | Description |
|---|---|---|
| Developer iteration speed | 0.2 | |
| Execution control (budgets, durable runs) | 0.25 | |
| Governance & multi-tenancy | 0.2 | |
| Portability / lock-in risk awareness | 0.15 | |
| Day-2 operations | 0.2 |
Options
Authoring surface (decorators / modules)
Best for: Product teams validating agent UX and tool schemas inside a HazelJS app
- Fast prototyping with @Agent / @Tool in a HazelJS DI module
- Fits the same TypeScript repo as your HTTP APIs
- Low ceremony to validate tool design
- Easy to ship an in-memory demo without durable runs
- Ops features (HITL, leases, DNA) are easy to skip
AgentRuntime kernel (@hazeljs/agent)
Best for: Services that must survive crashes, deploys, and human-in-the-loop delays
- First-class AgentRun, budgets, checkpoints, and timelines
- durableSuspend / approveAndResume for HITL
- ToolRegistry + PolicyEngine as execution substrate
- Does not by itself solve org-wide skill catalogs or multi-app DNA registries
- Still needs Skillgate/MCP governance and evals wired by you
HazelJS Agent OS (platform layers)
Best for: Teams running many agents/tools with shared compliance and ops needs on HazelJS
- DNA/manifests, Skillgate skills, MCP, observability, guardrails as a coherent stack
- Shared identity, budgets, Inspector, and starter paths
- Aligns platform teams around reusable capabilities
- Higher upfront investment than a single AgentRuntime demo
- Overkill for a single throwaway script
- Cloud control-plane surfaces only where documented—no vaporware
Architectural differences
In HazelJS, **authoring** is decorators/modules (`@Agent`, `@Tool`). The **runtime kernel** is `AgentRuntime` / `AgentRun` in `@hazeljs/agent` (state, retries, HITL, budgets). **Agent OS** is the layered operating model around that kernel: DNA, Skillgate, MCP, observability, guardrails, CLI/starters, and (when shipped) operator/control-plane surfaces. These layers compose inside one TypeScript backend—not as a separate product island.
Operational implications
If you only adopt decorators without a durable AgentRuntime, you still own production risk. If you invent a control plane without the kernel, you get catalogs of fragile demos. Grow: correct tool loop → durable AgentRuntime → Agent OS practices (DNA, Skillgate, Inspector) as agent count grows. Start from `hazeljs-agent-os-starter` when possible.
HazelJS layer map
| Layer | HazelJS artifact | Failure if missing |
|---|---|---|
| Authoring | @Agent / @Tool modules | Slow iteration |
| Runtime | AgentRuntime / durable AgentRun | Lost state / duplicate side effects |
| Agent OS | DNA, Skillgate, MCP, policies, Inspector | Drift, shadow agents, inconsistent auth |
Glossary: /glossary/agent-runtime, /glossary/control-plane, /glossary/agent-os. Hub: /agent-os.
Docs: Agent OS guide, Agent package.
Adoption sequence
- Get /patterns/tool-using-agent correct with PolicyEngine budgets.
- Add /patterns/durable-agent-run (HITL + run store).
- Version DNA (/guides/design-an-agent-manifest).
- Govern writes with Skillgate/MCP; observe with Inspector.
- Extract shared platform services when multiple teams share skills and policies.
What this comparison is not
It is not a ranked review of LangGraph, CrewAI, Temporal, or any vendor. Named product bake-offs remain backlog until they can be evidence-based with tested versions and explicit scoring methodology. Craft teaches HazelJS Agent OS; use this page to place layers correctly.