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")

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,
});

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:

1. POST /api/csr/memory/seed with { userId, value, sessionId? }
2. 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.