Prompt management, RAG, and agents with HazelJS

Source: Dev.to

One starter: typed prompt templates, a live registry, FileStore persistence, RAG, supervisor agents, and AI tasks—all driven by the same prompt system

Managing LLM prompts well is hard: you want versioning, overrides without redeploys, and a single place that RAG, agents, and plain AI tasks all read from. The HazelJS Prompt Starter shows how to do exactly that. Built on @hazeljs/prompts, @hazeljs/rag, and @hazeljs/agent, it gives you:

• a PromptRegistry with typed templates,
• FileStore persistence, and
• a REST API to inspect and override any prompt at runtime.

RAG answer synthesis, the supervisor agent, worker agents, and four AI tasks (welcome, summarize, sentiment, translate) all use that same registry. In this post we walk through what’s in the starter and how to use it.

Features

One server, one registry: change a prompt with PUT /api/prompts/:key, and the next RAG question, agent run, or AI task uses the new template.

Quick‑Start

git clone https://github.com/hazel-js/hazeljs-prompt-starter.git
cd hazeljs-prompt-starter
cp .env.example .env   # add OPENAI_API_KEY
npm install
npm run dev

The server runs at http://localhost:3000. Try listing prompts:

curl http://localhost:3000/api/prompts

Then override the RAG answer prompt and ask a question (see examples below).

Every prompt is identified by a key (e.g. rag:answer, agent:supervisor:system, app:summarize). The REST API lets you manage them without touching code.

Prompt Registry API

Example: Override the RAG answer prompt

curl -X PUT http://localhost:3000/api/prompts/rag%3Aanswer \
  -H "Content-Type: application/json" \
  -d '{
    "template": "Answer in one sentence.\nContext: {context}\nQuestion: {query}\nAnswer:",
    "metadata": { "version": "2.0.0", "description": "Concise one‑sentence answers" }
  }'

Example: Preview a prompt with variables

curl -X POST http://localhost:3000/api/prompts/app%3Asummarize/preview \
  -H "Content-Type: application/json" \
  -d '{ "variables": { "text": "HazelJS is a TypeScript framework.", "maxWords": "10" } }'

The RAG pipeline uses the rag:answer prompt from the registry. Override it via the Prompts API and the next /api/rag/ask call will use the new template.

RAG API

Ingest and ask

curl -X POST http://localhost:3000/api/rag/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "content": "HazelJS is a TypeScript backend framework built for scalability.", "source": "intro.txt" },
      { "content": "@hazeljs/prompts provides typed, overridable prompt templates.", "source": "prompts.txt" }
    ]
  }'

curl -X POST http://localhost:3000/api/rag/ask \
  -H "Content-Type: application/json" \
  -d '{ "question": "What is HazelJS?" }'

Workflow: Override rag:answer with PUT /api/prompts/rag%3Aanswer, then run the same question again — the answer style follows the new prompt.

Agent API

Example

curl -X POST http://localhost:3000/api/agent/run \
  -H "Content-Type: application/json" \
  -d '{ "task": "Research the benefits of RAG over fine‑tuning and analyse the trade‑offs." }'

The response includes supervisorSystemPrompt — the exact prompt used for the supervisor. Override agent:supervisor:system or agent:worker:researcher and run again to see different delegation and output styles.

AI Tasks API

Examples

curl -X POST http://localhost:3000/api/ai/task/welcome \
  -H "Content-Type: application/json" \
  -d '{ "name": "Alice", "topic": "prompt engineering" }'

curl -X POST http://localhost:3000/api/ai/task/summarize \
  -H "Content-Type: application/json" \
  -d '{ "text": "HazelJS makes building TypeScript back‑ends fast and type‑safe.", "maxWords": 15 }'

curl -X POST http://localhost:3000/api/ai/task/sentiment \
  -H "Content-Type: application/json" \
  -d '{ "text": "I love how easy it is to manage prompts with HazelJS!" }'

curl -X POST http://localhost:3000/api/ai/task/translate \
  -H "Content-Type: application/json" \
  -d '{ "text": "Hello, world!", "targetLanguage": "Spanish" }'

All four tasks pull their prompts from the same registry, so you can update any of them at runtime via the Prompt API.

Recap

• One registry → single source of truth for every prompt.
• Live REST API → edit, preview, version, and persist prompts without a redeploy.
• Typed templates → full TypeScript inference for safer prompt construction.
• FileStore → prompts survive server restarts.

Give it a spin, tweak prompts on the fly, and see how instantly the behavior of RAG, agents, and AI tasks changes!

API Examples

# Summarise a piece of text (max 30 words)
curl -X POST http://localhost:3000/api/ai/task/summarize \
  -H "Content-Type: application/json" \
  -d '{ "text": "HazelJS is a modular TypeScript framework...", "maxWords": "30" }'

# Get sentiment analysis
curl -X POST http://localhost:3000/api/ai/task/sentiment \
  -H "Content-Type: application/json" \
  -d '{ "text": "I love how easy HazelJS makes dependency injection!" }'

Prompt Registry Overview

Project Structure

src/
├── main.ts                     # Bootstrap + startup banner
├── app.module.ts               # Root HazelModule
├── prompts/                    # @hazeljs/prompts integration
│   ├── prompts.service.ts
│   ├── prompts.controller.ts
│   └── prompts.module.ts
├── rag/                        # @hazeljs/rag — reads rag:answer from registry
│   ├── rag.service.ts
│   ├── rag.controller.ts
│   └── rag.module.ts
├── agent/                      # @hazeljs/agent — supervisor + workers from registry
│   ├── agent.service.ts
│   ├── agent.controller.ts
│   ├── workers/researcher.agent.ts
│   ├── workers/analyst.agent.ts
│   └── agent.module.ts
├── ai/                         # AI tasks via registry prompts
│   ├── ai-task.service.ts
│   ├── ai-task.controller.ts
│   └── ai.module.ts
├── llm/                        # OpenAI LLM provider for agents
│   └── openai-llm.provider.ts
└── health/
    └── health.controller.ts   # Liveness + readiness

How It Works

• Prompt Registry – A single global PromptRegistry (backed by PromptTemplate and a FileStore) holds all prompt templates.
• Runtime Overrides – Prompts can be listed, previewed, and overridden via a REST API; changes are picked up instantly by RAG, agents, and AI tasks.
• Persistence – Overrides are persisted to ./data/prompts.json (or another store) and survive restarts.

Environment Variables

See the starter’s .env.example and README for the full list.

Extending the Store

For production you can replace the FileStore with a RedisStore (or any other backend) by adjusting the registry configuration inside PromptsService. The REST API and all consumers remain unchanged.

What the Starter Gives You

1. One Registry – PromptTemplate, PromptRegistry, and a pluggable store for typed, overridable prompts.
2. One REST API – List, preview, and override any prompt at runtime. All services (RAG, agents, AI tasks) react to changes instantly.
3. RAG, Agents, & AI Tasks – All read from the same registry, enabling behavior tuning without code changes.

Clone the repo, set OPENAI_API_KEY, and you have a single application that demonstrates prompt management, RAG, supervisor agents, and AI tasks in one place.

For more information about HazelJS and @hazeljs/prompts, visit hazeljs.com and the HazelJS GitHub repository.