HazelJS · Evergreen hub

HazelJS Agent OS

Durable AI agents inside your TypeScript backend. The Agent Runtime (`@hazeljs/agent`) is the kernel; Agent OS is how you package DNA, govern writes with Skillgate, survive crashes with HITL, and declare desired state — in the same DI app as your APIs.

Flagship lab: production Agent Runtime Read Agent OS docs Build your first agent

Layered model

Keep these layers distinct. Collapsing them into one framework package often recreates demos that cannot be operated.

Control Plane
Registry, deployments, reconciliation, policy, observation
Agent DNA
Identity, model, skills, policy, permissions, SLOs
Agent Runtime
Plan, execute, critique, validate
Skill Gateway
APIs converted into governed agent capabilities
Durable Kernel
Runs, checkpoints, HITL, leases, state, recovery
Application / Backend
Business logic and integrations

Agent DNA is a declarative contract. Executable implementation remains in agent packages, skills, tools, services, or application code.

Conceptual model

Control plane holds desired state: which agents exist, which versions are deployed, which policies apply, and what the reconciler should make true. It does not execute tool loops.

Agent DNA is a declarative contract/manifest: identity, model preferences, skills, permissions, and SLOs. Executable behavior still lives in packages, skills, tools, services, or application code.

Agent runtime plans, executes, critiques, and validates within budgets. Skill gateway turns APIs into governed capabilities. Durable kernel owns runs, checkpoints, HITL suspension, leases, and recovery.

Example HazelJS Agent DNA / manifest

apiVersion: agent.dev/v1
kind: AgentDefinition
metadata:
  name: incident-triage
  version: "1.2.0"
spec:
  identity:
    purpose: "Triage production incidents with bounded tool use"
  model:
    preferred: "provider/model"
    fallback: ["provider/model-small"]
  skills:
    - id: get_incident
      mode: read
    - id: search_changes
      mode: read
    - id: page_oncall
      mode: write
      approval: required
  policy:
    maxSteps: 8
    maxToolCalls: 12
    budgets:
      tokens: 80000
      usd: 2.00
  slos:
    p95LatencyMs: 45000
    successRate: 0.95

Lifecycle walkthrough

Submit Agent DNA / deployment desired state to the control plane registry.
Reconciler compares desired vs observed state and schedules/updates deployments.
Runtime starts an AgentRun, loads DNA-bound skills through the skill gateway, and executes under policy.
Durable kernel checkpoints steps; HITL gates suspend write actions until approved.
Observation streams (traces, cost, outcomes) feed the control plane for health and policy decisions.

HazelJS package map

@hazeljs/agent — AgentRuntime, AgentRun, HITL, budgets, DNA, timelines
@hazeljs/skillgate — curated REST → governed skills / tools
@hazeljs/mcp — MCP host/server integration
@hazeljs/observability + Inspector — traces and run timelines
@hazeljs/guardrails — policy and safety edges

Related learning

Start building

Prefer official starters over greenfield scaffolding. Wire AgentRuntime into the same DI container as your HTTP modules.

hazeljs-agent-os-starter — durable AgentRun + HITL baseline
hazeljs-meridian-ops — flagship F1–F22 reference app (Store, platform, Skillgate, multi-agent)
Skillgate / MCP starters — governed tools and external skills
Craft guide: design a production Agent Runtime
Craft guide: build your first tool-using agent

Agentic Craft is the educational field guide for building production agents with HazelJS. Examples, patterns, and learning tracks use the HazelJS Agent OS stack (@hazeljs/agent, Skillgate, MCP, memory, observability, and related packages).