DEV Community

Cover image for Building Production-Ready AI Agents in typescript with HazelJS
Nisa Fatima
Nisa Fatima

Posted on

Building Production-Ready AI Agents in typescript with HazelJS

#tutorial #agents #ai #typescript

AI agents are easy to demo but harder to ship.

A real agent system needs more than a prompt and a few tools. It needs clear responsibilities, safe tool execution, retrieval, observability, approvals, and tests.

To demonstrate these best practices, we built an AI Support Operations Desk with HazelJS.

The project includes:

  • TriageAgent for classifying customer requests
  • KnowledgeAgent for RAG-based policy lookup
  • ActionAgent for order, ticket, and refund tools
  • SupportOrchestratorAgent for delegation
  • Supervisor routing across specialist agents
  • Guardrails for safer input/output handling
  • Human approval for refunds
  • Runtime metrics, traces, and health checks
  • Golden evals with @hazeljs/eval

Why a Support Desk?

A support request often requires multiple steps:

Customer CUST-1001 asks where order ORD-1001 is and whether it can still be refunded.

To handle this safely, an agent system must:

  • Understand the intent
  • Check the order
  • Retrieve refund policy
  • Decide whether approval is required
  • Call the right tool
  • Return a safe response

That makes support operations a strong example for production-ready agents.

1. Use Focused Agents

Avoid one giant agent that does everything.

In this project, each agent has one responsibility:

  • TriageAgent classifies the request
  • KnowledgeAgent retrieves policy context
  • ActionAgent performs support actions
  • SupportOrchestratorAgent coordinates the flow

Example:

@Agent({
  name: 'TriageAgent',
  description: 'Classifies support requests by intent, urgency, safety risk, and next best worker.',
  systemPrompt:
    'You are a support triage specialist. Classify the request before any action is taken.',
})
@Service()
export class TriageAgent {
  @Tool({
    name: 'classifySupportIntent',
    description: 'Classify a customer support message.',
  })
  async classifySupportIntent(input: { message: string; customerId?: string }) {
    // classification logic
  }
}
Enter fullscreen mode Exit fullscreen mode

This keeps the system easier to test, debug, and extend.

2. Keep Tools Narrow

Tools should be specific and auditable.

Instead of a broad tool like:

executeCustomerRequest(input: string)
Enter fullscreen mode Exit fullscreen mode

use focused tools:

@Tool({
  name: 'lookupOrder',
  description: 'Look up order status, shipment details, refund eligibility, and amount.',
})
async lookupOrder(input: { orderId: string }) {
  // order lookup
}
Enter fullscreen mode Exit fullscreen mode

The ActionAgent exposes separate tools:

  • lookupOrder
  • createSupportTicket
  • requestRefundApproval

This makes every agent action visible in the trace.

3. Require Approval for Sensitive Actions

Refunds should not happen silently.

HazelJS tools can require approval:

@Tool({
  name: 'requestRefundApproval',
  description: 'Queue an eligible refund for human approval.',
  requiresApproval: true,
  policy: 'refunds_over_100_require_human_approval',
})
async requestRefundApproval(input: {
  orderId: string;
  amount: number;
  reason: string;
}) {
  // refund request
}
Enter fullscreen mode Exit fullscreen mode

The agent can prepare the refund, but HazelJS pauses execution until a human approves it.

That is the right model for high-risk actions.

4. Use RAG for Policy Knowledge

Support agents should not guess policies.

The KnowledgeAgent uses HazelJS RAG:

import { MemoryVectorStore, RAGPipeline, RetrievalStrategy } from '@hazeljs/rag';
Enter fullscreen mode Exit fullscreen mode

The app builds a small support knowledge base and exposes it as a tool:

@Tool({
  name: 'searchKnowledgeBase',
  description: 'Search support policies, runbooks, and response macros.',
})
async searchKnowledgeBase(input: { query: string; topK?: number }) {
  return this.knowledgeBase.answer(input.query, input.topK ?? 3);
}
Enter fullscreen mode Exit fullscreen mode

This grounds answers in known policy documents.

5. Delegate Between Agents

HazelJS supports @Delegate, which lets one agent call another agent as a tool.

@Delegate({
  agent: 'TriageAgent',
  description: 'Classify support request intent, urgency, and safety risk.',
  inputField: 'input',
})
async triageCustomerRequest(input: string): Promise<string> {
  return '';
}
Enter fullscreen mode Exit fullscreen mode

The orchestrator delegates to:

  • TriageAgent
  • KnowledgeAgent
  • ActionAgent

This keeps prompts and responsibilities clean.

6. Use Supervisor Routing

Some workflows are dynamic. A request may need triage, knowledge lookup, or action.

HazelJS can create a supervisor:

const supervisor = runtime.createSupervisor({
  name: 'support-ops-supervisor',
  workers: ['TriageAgent', 'KnowledgeAgent', 'ActionAgent'],
  maxRounds: 4,
  systemPrompt:
    'Route classification tasks to TriageAgent, policy questions to KnowledgeAgent, and order, ticket, or refund actions to ActionAgent.',
});
Enter fullscreen mode Exit fullscreen mode

The supervisor decides which worker should handle the next step.

Example response:

{
  "rounds": [
    {
      "round": 1,
      "worker": "ActionAgent",
      "action": "delegate"
    },
    {
      "round": 2,
      "worker": "supervisor",
      "action": "finish"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

7. Enable Production Runtime Features

The app configures the HazelJS agent runtime like this:

AgentModule.forRoot({
  runtime: {
    defaultMaxSteps: 8,
    defaultTimeout: 15000,
    enableObservability: true,
    enableMetrics: true,
    enableRetry: true,
    enableCircuitBreaker: true,
    rateLimitPerMinute: 120,
  },
})
Enter fullscreen mode Exit fullscreen mode

These features help prevent common production problems:

  • Infinite loops
  • Hanging executions
  • Provider failures
  • Rate spikes
  • Invisible errors

8. Add Guardrails

The app enables HazelJS guardrails:

GuardrailsModule.forRoot({
  redactPIIByDefault: true,
  blockInjectionByDefault: true,
  blockToxicityByDefault: true,
})
Enter fullscreen mode Exit fullscreen mode

Guardrails help with:

  • PII redaction
  • Prompt injection detection
  • Toxicity blocking
  • Safer tool input/output handling

Prompts are useful, but guardrails give you enforceable protection.

9. Expose Traces

The support API returns execution steps:

{
  "steps": [
    {
      "step": 1,
      "state": "using_tool",
      "tool": "lookupOrder",
      "toolInput": {
        "orderId": "ORD-1001"
      }
    },
    {
      "step": 2,
      "state": "using_tool",
      "tool": "requestRefundApproval"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

This makes debugging much easier.

You can see which tool was called, what input was passed, and what the tool returned.

The project also exposes:

GET /support/runtime
Enter fullscreen mode Exit fullscreen mode

This shows registered agents, tools, metrics, health, rate limiter status, and circuit breaker state.

10. Test with Evals

The project includes golden evals with @hazeljs/eval.

Example case:

{
  "id": "action-approved-refund",
  "input": "Customer CUST-1001 asks to refund order ORD-1001.",
  "expectedOutput": "Refund workflow complete",
  "expectedToolCalls": ["lookupOrder", "requestRefundApproval"]
}
Enter fullscreen mode Exit fullscreen mode

The eval runner checks both:

  • Final output
  • Tool trajectory

That matters because an agent can say the right thing while calling the wrong tools.

Run evals:

npm run eval
Enter fullscreen mode Exit fullscreen mode

Expected result:

[hazeljs/eval] support-ops-desk@2026.05 avg=1.000 passed=true
Enter fullscreen mode Exit fullscreen mode

Running the Demo

Install dependencies:

npm install --legacy-peer-deps
Enter fullscreen mode Exit fullscreen mode

Run evals:

npm run eval
Enter fullscreen mode Exit fullscreen mode

Start the app:

npm run dev
Enter fullscreen mode Exit fullscreen mode

Try the supervisor endpoint:

curl -s -X POST http://localhost:3010/support/supervisor \
  -H 'content-type: application/json' \
  -d '{"message":"Customer CUST-1001 asks where order ORD-1001 is and whether it can still be refunded.","userId":"cust-1001","autoApprove":true}'
Enter fullscreen mode Exit fullscreen mode

Open the HazelJS inspector:

http://localhost:3010/__hazel
Enter fullscreen mode Exit fullscreen mode

Why the Demo Uses a Local Provider

The project uses a deterministic local LLM provider so anyone can run it without an API key.

That makes the demo:

  • Easy to install
  • Free to run
  • Stable for screenshots
  • Reliable for evals

In production, you can replace it with HazelJS AI provider integration for OpenAI, Anthropic, Gemini, Cohere, or Ollama.

Final Thoughts

Production agents need structure.

The most important patterns are:

  • Split work across focused agents
  • Keep tools narrow
  • Require approval for sensitive actions
  • Use RAG for domain knowledge
  • Delegate between specialists
  • Use supervisor routing
  • Enable guardrails and observability
  • Test behavior with evals

HazelJS makes these patterns feel like normal backend engineering, not agent glue code.
Github repo: support-ops-desk

Top comments (0)