Scaffold Your First HazelJS Agent

What you will build in this track

Across these lessons you build one Ops Desk agent on HazelJS:

1. Look up order ORD-1001 with a read-only tool
2. Bound the run so it cannot loop forever
3. Keep tool results small and safe for the model
4. Add a refund tool that requires human approval
5. Lock behavior with describeAgent tests
6. Watch runs in timelines / CLI
7. Promote with a production checklist

You do not need prior agent frameworks. You do need basic TypeScript and Node.

Docs: Agent package, Agent OS. Companion hands-on guide: /guides/build-your-first-tool-using-agent.

Step 1Pick a project path

Both are valid. This course shows the script path so every line is visible. Map the same code into AgentModule.forRoot later when you join a real HazelJS app.

Step 2Install packages

npm install @hazeljs/agent @hazeljs/core @hazeljs/ai
# later lessons:
# npm install @hazeljs/testing

Enable TypeScript decorators (HazelJS agents use @Agent / @Tool):

// tsconfig.json (excerpt)
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strict": true,
    "esModuleInterop": true,
    "moduleResolution": "bundler",
    "target": "ES2022"
  }
}

Step 3Start with a mock LLM

For learning, use createMockLlmProvider so you can wire the runtime without burning tokens. Swap to OpenAIProvider (or another @hazeljs/ai provider) when the tools work.

import {
  AgentRuntime,
  createMockLlmProvider,
} from '@hazeljs/agent';

const llm = createMockLlmProvider(
  'Learning mode: replace with OpenAIProvider when tools are ready.'
);

const runtime = new AgentRuntime({
  llmProvider: llm,
  enableRetry: false,
  enableCircuitBreaker: false,
});

console.log('Runtime ready');

Run it. If this prints without errors, your install and decorator config are fine.

Step 4Know the three pieces you will write next

The model never calls your APIs. It only proposes tool names + args. AgentRuntime validates and executes.

Common setup mistakes

1. Decorators off — @Agent silently does nothing useful without experimentalDecorators.
2. Wrong agent name — execute('OpsDesk', …) must match @Agent({ name }).
3. Starting with write tools — begin read-only; add refunds only after lesson 5.
4. Treating CLI DNA smoke as the app — hazel agent run stubs tools; your app execute is the source of truth (covered later).

Checkpoint

Before the next lesson you should have:

• A TypeScript project with @hazeljs/agent installed
• Decorators enabled
• A file that constructs AgentRuntime with a mock LLM

What to do next

Define the agent and first tool: /learn/agentic-development/tool-using-agent-loop