ACAgentic Craft

Advanced~25 minHazelJS

Production Agent Runtime Blueprint

Reference architecture for a HazelJS production Agent Runtime: App code, DNA, Store, platform desired state, and AgentRuntime execute — as taught by Meridian Ops.

Authors
editorial-team
Published
Last reviewed

Problem

Teams assemble Agent OS pieces ad hoc and confuse DNA smoke, platform apply, and product execute.

Context

A TypeScript backend that must ship agents with HITL, versioned contracts, and operable timelines — not a demo chat loop.

Forces and constraints

  • Agents must live beside APIs in one DI process for auth and observability
  • Contracts (DNA) must version independently from tool implementations
  • Irreversible writes need durable HITL, not prompt hope
  • Operators need desired-state and live-run views that are not the same artifact
  • CLI smoke must never be mistaken for production side effects

Recommended design

Separate five concerns: (1) App `@Agent`/`@Tool`/Skillgate implementations, (2) DNA marketplace packages, (3) Store publish/materialize/lock, (4) platform Definition/Deployment desired state, (5) AgentRuntime execute with durable runs, policies, Inspector. Overlay applies prompt/policies only. Use Meridian Ops as the runnable reference.

Failure modes

  • Treating hazel agent run stubs as product verification
  • Expecting platform apply to restart or deploy the Node app
  • DNA overlay inventing tools that were never registered in TypeScript
  • Auto-approving irreversible tools in production because the demo default did
  • Copying Meridian's in-memory commerce store into prod unchanged

Security considerations

  • requiresApproval + durableSuspend for irreversible tools
  • PolicyEngine deny / require_approval beyond system prompts
  • Skillgate include/deny — do not expose /internal or admin by accident
  • Least-privilege tool surfaces per agent DNA package

Observability signals

  • Inspector /__hazel and timeline stores keyed by executionId
  • Platform events.jsonl for desired-state audit
  • Persist stop reasons on every run

Evaluation approach

describeAgent goldens on specialist paths; smoke CLI only for DNA sanity; product suites hit HTTP execute routes.

Trade-offs

  • Full Meridian-shaped runtime increases day-2 ops vs a thin starter
  • Local platform (v1alpha1) is enough to learn; Cloud/K8s are optional later
  • Multi-DNA clarity costs more packaging discipline

Sources

Related patterns