프롬프트 관리, RAG, 및 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

LLM 프롬프트를 잘 관리하는 것은 어렵습니다. 버전 관리, 재배포 없이 오버라이드, 그리고 RAG, 에이전트, 일반 AI 작업이 모두 읽을 수 있는 단일 장소가 필요합니다. HazelJS Prompt Starter는 바로 그 방법을 보여줍니다. @hazeljs/prompts, @hazeljs/rag, @hazeljs/agent 위에 구축되었으며 다음을 제공합니다:

• 타입이 지정된 템플릿을 갖춘 PromptRegistry,
• FileStore 영속성, 그리고
• 런타임에 언제든지 프롬프트를 확인하고 오버라이드할 수 있는 REST API.

RAG 응답 합성, 슈퍼바이저 에이전트, 워커 에이전트, 그리고 네 가지 AI 작업(환영, 요약, 감성 분석, 번역) 모두 같은 레지스트리를 사용합니다. 이 글에서는 스타터에 포함된 내용과 사용 방법을 단계별로 살펴봅니다.

Features

One server, one registry: PUT /api/prompts/:key 로 프롬프트를 변경하면 다음 RAG 질문, 에이전트 실행, 또는 AI 작업이 새로운 템플릿을 사용합니다.

빠른 시작

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

서버는 http://localhost:3000에서 실행됩니다. 프롬프트 목록을 확인해 보세요:

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

그런 다음 RAG 답변 프롬프트를 재정의하고 질문을 해보세요 (아래 예시 참고).
모든 프롬프트는 키로 식별됩니다 (예: rag:answer, agent:supervisor:system, app:summarize). REST API를 사용하면 코드를 수정하지 않고도 프롬프트를 관리할 수 있습니다.

Prompt Registry API

예시: RAG 답변 프롬프트 재정의

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" }
  }'

예시: 변수를 사용해 프롬프트 미리 보기

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" } }'

RAG 파이프라인은 레지스트리의 rag:answer 프롬프트를 사용합니다. Prompts API를 통해 이를 재정의하면 다음 /api/rag/ask 호출에서 새 템플릿이 사용됩니다.

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: rag:answer를 PUT /api/prompts/rag%3Aanswer로 오버라이드한 뒤, 같은 질문을 다시 실행하면 — 답변 스타일이 새로운 프롬프트를 따릅니다.

Agent API

예시

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." }'

응답에는 supervisorSystemPrompt가 포함됩니다 — 슈퍼바이저에 사용된 정확한 프롬프트입니다. agent:supervisor:system 또는 agent:worker:researcher를 재정의하고 다시 실행하면 다른 위임 및 출력 스타일을 확인할 수 있습니다.

AI 작업 API

예시

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" }'

네 개 작업 모두 동일한 레지스트리에서 프롬프트를 가져오므로, Prompt API를 통해 런타임 시 언제든지 업데이트할 수 있습니다.

요약

• One registry → 모든 프롬프트에 대한 단일 진실 소스.
• Live REST API → 재배포 없이 프롬프트를 편집, 미리보기, 버전 관리 및 영구 저장합니다.
• Typed templates → 보다 안전한 프롬프트 구성을 위한 전체 TypeScript 추론 제공.
• FileStore → 서버 재시작 후에도 프롬프트가 유지됩니다.

직접 사용해 보고, 프롬프트를 즉시 조정하면서 RAG, 에이전트, AI 작업의 동작이 얼마나 즉시 변하는지 확인해 보세요!

API 예시

# 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!" }'

프롬프트 레지스트리 개요

프로젝트 구조

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 – 단일 전역 PromptRegistry( PromptTemplate와 FileStore에 의해 지원) 가 모든 프롬프트 템플릿을 보관합니다.
• Runtime Overrides – 프롬프트는 REST API를 통해 목록화, 미리보기 및 재정의될 수 있으며, 변경 사항은 RAG, 에이전트 및 AI 작업에 즉시 반영됩니다.
• Persistence – 재정의는 ./data/prompts.json(또는 다른 저장소)에 영구 저장되며 재시작 후에도 유지됩니다.

Environment Variables

전체 목록은 스타터의 .env.example 및 README를 참고하세요.

스토어 확장

프로덕션 환경에서는 PromptsService 내부의 레지스트리 구성을 조정하여 FileStore를 RedisStore(또는 다른 백엔드)로 교체할 수 있습니다. REST API와 모든 소비자는 변경되지 않습니다.

스타터가 제공하는 것

1. 하나의 레지스트리 – PromptTemplate, PromptRegistry, 그리고 타입이 지정된 오버라이드 가능한 프롬프트를 위한 플러그인 가능한 저장소.
2. 하나의 REST API – 런타임에 모든 프롬프트를 목록화하고, 미리보기하며, 오버라이드할 수 있습니다. 모든 서비스(RAG, 에이전트, AI 작업)는 변경 사항에 즉시 반응합니다.
3. RAG, 에이전트 및 AI 작업 – 모두 동일한 레지스트리에서 읽어 코드 변경 없이 동작을 조정할 수 있습니다.

레포지토리를 클론하고 OPENAI_API_KEY를 설정하면, 프롬프트 관리, RAG, 감독 에이전트 및 AI 작업을 한 곳에서 시연하는 단일 애플리케이션을 얻을 수 있습니다.

더 자세한 정보는 HazelJS와 @hazeljs/prompts에 대해 hazeljs.com 및 HazelJS GitHub 리포지토리를 방문하세요.