NestJS를 사용하면서 도구(tools)를 사용하고, 문맥(context)을 유지하며, 비동기 작업(asynchronous jobs)을 처리하는 AI 에이전트를 통합하고 싶다면 이 튜토리얼이 당신을 위한 것입니다. 이것은 이론이 아닙니다 — 우리가 SOM-OS에서 프로덕션 시스템을 위해 사용하는 아키텍처입니다.

아키텍처

Client → NestJS Controller → BullMQ Queue → Worker
                                            ↓
                                     LangChain Agent
...

흐름은 간단합니다: 사용자가 요청을 보내면 BullMQ에 큐(enqueue)에 쌓이고, 워커(worker)가 Zod로 타입이 지정된 도구(tools)에 접근할 수 있는 LangChain 에이전트를 사용하여 작업을 처리하며, 히스토리(history)는 PostgreSQL에 저장됩니다.

1. 설치

npm install @nestjs/bullmq bullmq ioredis
npm install @langchain/core @langchain/openai @langchain/community
npm install zod

2. NestJS 모듈

// ia-agent.module.ts
import { Module } from '@nestjs/common';
import { BullModule } from '@nestjs/bullmq';
...

3. 컨트롤러 (Controller)

// ia-agent.controller.ts
import { Controller, Post, Body } from '@nestjs/common';
import { IaAgentService } from './ia-agent.service';
...

4. 서비스 + 큐 (Service + Queue)

// ia-agent.service.ts
import { Injectable } from '@nestjs/common';
import { Queue } from 'bullmq';
...

5. LangChain 에이전트를 포함한 워커 (Worker)

// ia-agent.processor.ts
import { Processor, WorkerHost } from '@nestjs/bullmq';
import { Job } from 'bullmq';
...

6. Docker를 이용한 배포 (Deploy)

FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
...

빠른 튜토리얼이 알려주지 않는 것들

1. 속도 제한 (Rate limits): OpenAI에는 제한이 있습니다. 이를 초 exceed하지 않도록 rateLimit과 함께 BullMQ를 사용하세요.
2. 컨텍스트 윈도우 (Context window): 히스토리가 커지면 잘라내야(truncate) 합니다. 보통 마지막 10개의 메시지로 충분합니다.
3. 비용 (Cost): GPT-4o는 1M 토큰당 $5입니다. 3개의 도구(tools)를 사용하는 에이전트는 호출당 약 2k 토큰을 소비합니다. 모니터링하세요.
4. 에러 (Errors): LangChain이 항상 깔끔하게 실패하는 것은 아닙니다. 모든 것을 try/catch로 감싸고 전체 트레이스(trace)를 로그로 남기세요.

왜 Express가 아니라 NestJS인가

프로덕션 환경의 에이전트를 위해서는 다음과 같은 요소들이 필요합니다: 교체 가능한 도구 (Swappable tools)를 위한 의존성 주입 (DI), 속도 제한 (rate limiting)을 위한 가드 (guards), 로깅 (logging)을 위한 인터셉터 (interceptors), 그리고 조직화를 위한 모듈 (modules)이 필요합니다. Express는 함수를 제공하지만, NestJS는 아키텍처 (architecture)를 제공합니다.

저는 NestJS vs Express: 2026년에 각각을 선택해야 하는 시점에 대해 더 자세한 비교 글을 작성했습니다.

우리가 이를 실제 비즈니스 시스템에 어떻게 적용하는지 알고 싶다면 SOM-OS를 살펴보세요. 우리는 마요르카(Mallorca)에서 AI를 활용한 비즈니스 운영 체제를 구축합니다.

질문이 있으신가요? 댓글로 남겨주세요.