Support Agent Guide (HCEL)

Learn how to build an AI Customer Support Representative (CSR) that can run in multiple modes:

Runtime agent execution (/api/csr/chat)
HCEL with memory recall (/api/csr/chat/hcel + variant: "memory")
HCEL pipeline orchestration (/api/csr/chat/hcel + variant: "pipeline")

If you're new to HCEL, read HCEL Guide first.

Example repository

Github: hazeljs-csr-agent

What is the CSR example?

The CSR example is a small HazelJS server that exposes a Customer Support Representative agent over:

REST
- POST /api/csr/chat
- POST /api/csr/chat/hcel
- POST /api/csr/chat/stream
- POST /api/csr/memory/seed
- POST /api/csr/ingest
- POST /api/csr/approve
SSE streaming: POST /api/csr/chat/stream
WebSocket: ws://localhost:3001/csr

Its purpose is to demonstrate an end-to-end AI backend feature with:

Agent tools (@Tool) like lookupOrder, checkInventory, processRefund
RAG ingestion for support documents (/api/csr/ingest)
HCEL memory integration via @hazeljs/memory (.memory(), .memoryRecall())
HCEL orchestration via .agentPipeline(...)
Approval workflow for sensitive tools (requiresApproval: true)

Code map (where to look)

csr.agent.ts: agent + tools.
csr.service.ts: HazelAI setup, memory store initialization, chat modes.
csr.controller.ts: REST endpoints (including HCEL and memory seed).
csr.gateway.ts: WebSocket endpoint with optional HCEL variant.

How to run (for newbies)

From the repo root:

cd hazeljs-csr-agent
npm install

Set your provider key (minimum required for the demo):

export OPENAI_API_KEY="your-key"

Start the server:

npm run dev

Then use:

Swagger UI: http://localhost:3000/swagger
Health check: GET http://localhost:3000/api/csr/health

API modes

1) Runtime chat (default)

POST /api/csr/chat executes csr-agent on the runtime directly.

const result = await runtime.execute('csr-agent', message, {
  sessionId,
  userId,
  loop: { maxIterations: 8, successScore: 95 },
});

Optional: subscribe to state while the agent runs:

runtime.onState('planning', () => console.log('planning…'));
runtime.onStateChange((e) => console.log(e.from, '→', e.to));

For CI regression suites, see @hazeljs/testing (describeAgent). Live timelines: Inspector. Full Agent OS (policies, contracts, DNA, twin): Agent OS guide and the Nordhelm starter (hazeljs-agent-os-starter).

2) HCEL chat with memory recall

POST /api/csr/chat/hcel with variant: "memory":

const result = await ai.hazel
  .memory(memoryService)
  .context({ sessionId, userId })
  .memoryRecall({
    category: [MemoryCategory.PREFERENCE, MemoryCategory.EPISODIC],
    limit: 12,
    header: 'Known customer context (from @hazeljs/memory):',
  })
  .agent('csr-agent')
  .execute(message);

Response includes mode: "hcel-memory".

3) HCEL chat with pipeline orchestration

POST /api/csr/chat/hcel with variant: "pipeline":

const graph = await ai.hazel
  .context({ sessionId, userId })
  .agentPipeline({
    pipelineId: 'csr-example-linear',
    agents: ['csr-agent'],
  })
  .execute(message);

Response is mapped from graph output and includes mode: "hcel-pipeline".

Memory demo flow (`@hazeljs/memory`)

The example includes a helper endpoint to seed memory and make recall obvious:

POST /api/csr/memory/seed with { userId, value, sessionId? }
POST /api/csr/chat/hcel with variant: "memory" and the same userId

This demonstrates:

createMemoryStore({ type: 'in-memory' })
new MemoryService(store) + await memory.initialize()
HCEL .memory(...).memoryRecall(...)

Tooling and approvals

csr-agent includes tools such as:

lookupOrder
checkInventory
processRefund (approval required)
updateShippingAddress (approval required)
createTicket
searchKnowledgeBase

Approve/reject pending actions through:

POST /api/csr/approve

Try it locally (REST + HCEL + SSE)

1) Ingest a document (seed your knowledge base)

curl -X POST http://localhost:3000/api/csr/ingest \
  -H "Content-Type: application/json" \
  -d '{"title":"Refund Policy","content":"Refunds are available within 30 days..."}'

2) Chat (sync)

curl -X POST http://localhost:3000/api/csr/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"What is the status of order ORD-12345?","sessionId":"customer-1","userId":"u-1"}'

3) Seed memory for HCEL recall demo

curl -X POST http://localhost:3000/api/csr/memory/seed \
  -H "Content-Type: application/json" \
  -d '{"userId":"u-1","sessionId":"customer-1","value":"Customer prefers email updates and express shipping"}'

4) Chat via HCEL memory variant

curl -X POST http://localhost:3000/api/csr/chat/hcel \
  -H "Content-Type: application/json" \
  -d '{"message":"Summarize how I prefer to be contacted and shipped.","sessionId":"customer-1","userId":"u-1","variant":"memory"}'

5) Chat via HCEL pipeline variant

curl -X POST http://localhost:3000/api/csr/chat/hcel \
  -H "Content-Type: application/json" \
  -d '{"message":"What is the status of order ORD-12345?","sessionId":"customer-1","userId":"u-1","variant":"pipeline"}'

6) Chat (streaming via SSE)

curl -N -X POST http://localhost:3000/api/csr/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message":"Summarize my issue: package arrived damaged","sessionId":"customer-1","userId":"u-1"}'

Postman (easiest for beginners)

The CSR example ships with a Postman collection. Import and run:

hazeljs-csr-agent.postman_collection.json
hazeljs-csr-agent.postman_environment.json

Recommended order:

Health → Memory seed → Chat HCEL (memory) → Chat HCEL (pipeline) → Ingest → Chat → Stream → Approve

Next Steps

Read HCEL Guide for all operations (agentPipeline, memoryRecall, etc.).
Read Memory Guide for storage and retrieval patterns.
Explore Agentic RAG for advanced retrieval strategies.
Learn about Distributed Sagas to handle multi-stage support transactions.
Check out PDF-to-Audio for accessible support documentation.