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:
TriageAgentfor classifying customer requests
KnowledgeAgentfor RAG-based policy lookup
ActionAgentfor order, ticket, and refund tools
SupportOrchestratorAgentfor 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:
TriageAgentclassifies the request
KnowledgeAgentretrieves policy context
ActionAgentperforms support actions
SupportOrchestratorAgentcoordinates 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
}
}
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)
use focused tools:
@Tool({
name: 'lookupOrder',
description: 'Look up order status, shipment details, refund eligibility, and amount.',
})
async lookupOrder(input: { orderId: string }) {
// order lookup
}
The ActionAgent exposes separate tools:
lookupOrdercreateSupportTicketrequestRefundApproval
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
}
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';
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);
}
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 '';
}
The orchestrator delegates to:
TriageAgentKnowledgeAgentActionAgent
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.',
});
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"
}
]
}
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,
},
})
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,
})
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"
}
]
}
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
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"]
}
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
Expected result:
Running the Demo
Install dependencies:
npm install --legacy-peer-deps
Run evals:
npm run eval
Start the app:
npm run dev
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}'
Open the HazelJS inspector:
http://localhost:3010/__hazel
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
SOCIAL SHARE CARD GENERATOR