n8n으로 AI 에이전트 파이프라인 구축하기: 이메일 자동 분류부터 RAG 파이프라인까지

Zapier로 단순 트리거-액션 자동화를 구현해봤거나, LangChain을 Python으로 직접 코딩해봤다면 한 번쯤 이런 불편함을 느꼈을 겁니다. Zapier는 로직 분기가 복잡해지면 한계에 부딪히고, LangChain 코드는 LLM을 교체하거나 도구를 추가할 때마다 수정 범위가 넓어집니다. n8n은 코드의 정밀함과 노코드의 속도를 동시에 활용해 AI 에이전트 파이프라인을 시각적으로 설계할 수 있는 오픈소스 워크플로우 자동화 플랫폼입니다.

n8n 2.0은 LangChain을 네이티브로 통합하며 AI 에이전트 오케스트레이션 레이어로 자리를 잡았습니다. AI Agent 노드는 내부적으로 LangChain의 AgentExecutor(ReAct 패턴)를 사용하고, MCP(Model Context Protocol) 트리거를 통해 워크플로우를 Claude Desktop이나 Cursor 같은 LLM 클라이언트에서 직접 호출할 수 있습니다.

이 글은 CLI와 Docker에 익숙한 백엔드·DevOps 개발자를 대상으로 합니다. 글을 읽고 나면 로컬 환경에서 고객 이메일을 자동 분류하고 초안 응답을 생성하는 AI 에이전트 워크플로우가 실제로 실행 중인 상태가 됩니다. GUI 중심의 입문이 필요하다면 n8n 공식 퀵스타트가 더 적합한 출발점이 될 수 있습니다.

핵심 개념

n8n의 구조: 워크플로우, 노드, 트리거

n8n의 모든 자동화는 워크플로우(Workflow) 단위로 관리됩니다. 워크플로우는 캔버스 위에 **노드(Node)**를 배치하고 연결선으로 이어 흐름을 정의하는 시각적 청사진입니다. 각 노드는 하나의 작업 단위로, HTTP 요청 전송, 데이터 변환, 조건 분기, 외부 서비스 연동 등 역할이 구분됩니다.

자동화의 출발점은 트리거(Trigger) 노드입니다. 웹훅 수신, cron 스케줄, 이메일 도착, 데이터베이스 변경 등 다양한 이벤트가 트리거로 작동합니다.

핵심 차별점: n8n은 "하이브리드 개발 환경"을 지향합니다. 비기술 사용자는 드래그 앤 드롭으로 워크플로우를 구성하고, 개발자는 Code 노드를 통해 JavaScript 또는 Python 코드를 직접 삽입할 수 있습니다. 외부 npm 패키지도 사용 가능합니다.

Fair-code 라이선스와 자체 호스팅

n8n은 Fair-code 라이선스를 채택하고 있습니다. 자체 호스팅 시 무료로 사용할 수 있고 소스 코드를 열람·수정할 수 있습니다. 단, n8n 소프트웨어 자체를 SaaS로 래핑해 판매하거나 재배포하는 것은 금지됩니다. 사내 자동화 도구로 활용하거나 n8n 위에 자체 애플리케이션을 구축해 고객에게 제공하는 것은 허용 범위에 해당합니다. 라이선스 경계가 불분명한 경우 n8n 공식 라이선스 FAQ를 참고하는 것이 좋습니다.

공식 권장 배포 스택은 다음과 같습니다.

컴포넌트	역할
Docker / Docker Compose	n8n 애플리케이션 실행
PostgreSQL	워크플로우·실행 이력 저장
Redis	큐 모드에서 수평 확장 지원
Kubernetes	대규모 엔터프라이즈 배포

n8n 2.0의 AI 네이티브 기능과 LangChain 통합

n8n 2.0의 핵심은 LangChain의 네이티브 통합입니다. 단순히 API를 연결하는 수준이 아니라, LangChain의 주요 추상화가 노드로 직접 매핑됩니다.

LangChain 추상화	n8n 노드	역할
AgentExecutor	AI Agent 노드	ReAct 루프(Thought → Action → Observation) 실행
Chain	Chain 노드	순차적 LLM 처리 (요약, 번역 등)
Tool 인터페이스	Tool 노드 / MCP 트리거	n8n 워크플로우를 LLM이 호출 가능한 도구로 노출
Memory	Memory 노드	대화 컨텍스트 유지 (Buffer, Summary 방식 지원)
LLM Wrapper	Model 노드	OpenAI, Claude, Gemini, Ollama 등 교체 가능

AI Agent 노드의 내부 동작: 이 노드는 LangChain의 AgentExecutor를 통해 ReAct(Reasoning + Acting) 패턴으로 작동합니다. LLM이 "어떤 도구를 어떤 순서로 사용할지" 스스로 판단하는 루프(Thought → Action → Observation → ...)를 반복합니다. 이 구조를 이해하면 시스템 프롬프트에서 도구 사용 지침을 어떻게 작성해야 할지, 루프가 무한 반복될 때 어떤 종료 조건을 추가해야 할지 설계 결정을 더 정확하게 내릴 수 있습니다.

새롭게 추가된 주요 기능은 다음과 같습니다.

AI Agent 노드: LangChain AgentExecutor 기반, 자율적 추론·계획·실행이 가능한 에이전트를 시각적으로 구성
MCP(Model Context Protocol) 트리거: n8n 워크플로우를 MCP 서버로 즉시 노출하여 Claude Desktop, Cursor 등 MCP 클라이언트에서 직접 호출 가능
RAG 파이프라인 내장: Pinecone, Qdrant, Supabase pgvector, Weaviate, ChromaDB 등 벡터 DB 노드 기본 지원
LLM Evaluations: 모델 성능을 워크플로우 내에서 직접 평가

MCP(Model Context Protocol): Anthropic이 제안한 AI 모델과 외부 도구 간 표준 통신 프로토콜입니다. n8n 워크플로우를 MCP 서버로 노출하면, Claude나 Cursor 같은 LLM 기반 도구가 n8n 워크플로우를 "도구(tool)"처럼 직접 호출할 수 있습니다.

실전 적용

예시 1: Docker Compose로 n8n 로컬 환경 구성하기

가장 빠르게 n8n을 시작하는 방법은 Docker Compose를 활용하는 것입니다. 먼저 자격증명 암호화에 사용할 키를 생성합니다.

# 32바이트 랜덤 키 생성 (실행 결과를 복사해 아래 설정에 사용)
openssl rand -hex 16

아래 설정 파일을 docker-compose.yml로 저장하면 PostgreSQL·Redis와 함께 프로덕션에 가까운 환경을 로컬에서 구성할 수 있습니다.

yaml

version: "3.8"
 
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: n8n
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: n8n_secret
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n"]
      interval: 5s
      timeout: 5s
      retries: 5
 
  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5
 
  n8n:
    image: n8nio/n8n:latest
    ports:
      - "5678:5678"
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=n8n_secret
      - N8N_ENCRYPTION_KEY=<openssl rand -hex 16 결과값으로 교체>
      - EXECUTIONS_MODE=queue          # 수평 확장 시 queue 모드 활성화
      - QUEUE_BULL_REDIS_HOST=redis    # queue 모드에서 Redis 연결
      - N8N_COMMUNITY_PACKAGES_ENABLED=true
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
 
volumes:
  postgres_data:
  n8n_data:

# 실행
docker compose up -d
 
# 브라우저에서 접속
open http://localhost:5678

N8N_ENCRYPTION_KEY는 n8n에 저장된 모든 자격증명(API 키, OAuth 토큰 등) 암호화에 사용됩니다. 컨테이너를 재생성할 때 이 값이 바뀌면 기존 자격증명이 전부 무효화되므로, .env 파일로 분리하거나 별도 시크릿 관리 시스템에 보관해두는 것을 권장합니다.

예시 2: AI Agent 워크플로우 — 이메일 자동 분류 및 응답

다음은 AI Agent 노드를 활용해 인입 이메일을 자동으로 분류하고 초안 응답을 생성하는 워크플로우입니다.

워크플로우 흐름

[Gmail Trigger]
      │  새 이메일 수신
      ↓
[Code 노드]
      │  이메일 → 프롬프트 가공 / $workflow, $execution 변수 주입
      ↓
[AI Agent 노드]           ← ReAct 루프로 분류·응답 생성
      │  JSON 응답 반환
      ↓
[IF 노드]                 ← requires_human 값으로 분기
   ↙                ↘
[Slack 노드]         [Gmail 노드]
담당자 알림           자동 응답 발송

Code 노드에서는 n8n의 내장 변수($workflow, $execution)를 활용해 실행 컨텍스트를 추적하고, try-catch로 필수 필드 누락이나 형식 오류를 미리 방어합니다.

java

// Code 노드: 이메일 데이터를 AI Agent에 전달할 컨텍스트로 가공
const emailData = $input.first().json;
 
// n8n 내장 변수 — 로그 추적 및 디버깅에 유용
const executionId = $execution.id;    // 현재 실행 ID
const workflowName = $workflow.name;  // 워크플로우 이름
 
let result;
try {
  // 필수 필드 검증
  if (!emailData.subject || !emailData.body) {
    throw new Error('이메일 subject 또는 body가 누락되었습니다');
  }
 
  const prompt = `
다음 고객 이메일을 분석하고 JSON 형식으로만 응답해주세요. 다른 텍스트는 포함하지 마세요.
 
이메일 제목: ${emailData.subject}
이메일 본문: ${emailData.body}
발신자: ${emailData.from}
 
반환 형식:
{
  "category": "billing | technical | general | complaint",
  "priority": "high | medium | low",
  "sentiment": "positive | neutral | negative",
  "suggested_response": "초안 응답 텍스트",
  "requires_human": true | false
}
  `.trim();
 
  result = [{ json: { prompt, originalEmail: emailData, executionId, workflowName } }];
 
} catch (error) {
  // JSON 파싱 실패, API rate limit 등 — 워크플로우를 멈추지 않고 오류 정보를 전달
  result = [{
    json: {
      error: true,
      message: error.message,
      originalEmail: emailData,
      executionId
    }
  }];
}
 
return result;

프롬프트 설계 팁: AI Agent 노드(ReAct 패턴)는 LLM이 도구 사용 순서를 스스로 추론합니다. 출력 형식을 JSON으로 고정하고 "다른 텍스트는 포함하지 마세요"를 명시하면 다운스트림 파싱 실패를 크게 줄일 수 있습니다.

노드	역할
Gmail Trigger	새 이메일 수신 시 워크플로우 시작
Code 노드	이메일 데이터를 프롬프트로 가공, 오류 방어 처리
AI Agent 노드	OpenAI GPT-4o / Claude 연결, ReAct 루프로 분류·응답 생성
IF 노드	`requires_human: true`인 경우 분기
Slack 노드	담당자에게 우선순위와 함께 알림 발송
Gmail 노드	`requires_human: false`이면 초안 응답 자동 발송

예시 3: RAG 파이프라인 구성 (코드 없이)

n8n 2.0에서는 벡터 DB 노드가 기본 내장되어 있어 코드 없이도 RAG 파이프라인을 구성할 수 있습니다.

문서 수집 파이프라인

[문서 업로드 Webhook]
       ↓
[Text Splitter 노드]          ← 청크 크기: 512토큰, 오버랩: 50토큰
       ↓
[Embeddings 노드]             ← OpenAI text-embedding-3-small
       ↓
[Pinecone Vector Store 노드]  ← 벡터 저장

청크 크기 선택 기준: 512토큰은 대부분의 단락 단위 문서에 적합한 기본값이며, 50토큰 오버랩은 청크 경계에서 문맥이 끊기는 것을 방지합니다. 짧은 FAQ나 표 형식 문서는 256토큰 이하로, 긴 법률·의료 문서는 1024토큰 이상으로 조정하는 것을 권장합니다. 사용하는 임베딩 모델의 최대 입력 길이도 함께 확인하는 것이 좋습니다.

질의 파이프라인

[Chat Trigger 노드]
       ↓
[Pinecone Vector Store 노드]  ← 유사도 검색 (Top-K: 5)
       ↓
[AI Agent 노드]               ← 검색 결과를 컨텍스트로 주입
       ↓
[응답 반환]

RAG(Retrieval-Augmented Generation): LLM이 답변을 생성하기 전에 외부 문서나 데이터베이스에서 관련 정보를 검색(Retrieve)해 컨텍스트로 제공하는 패턴입니다. 모델의 학습 데이터에 없는 사내 문서나 최신 정보를 LLM이 활용할 수 있게 됩니다.

장단점 분석

장점

항목	내용
비용 효율성	자체 호스팅 시 워크플로우·실행 건수 무제한 무료. 대량 처리 환경에서 Zapier/Make의 실행 건당 과금 대비 압도적으로 유리합니다
데이터 주권	온프레미스 또는 자체 클라우드에 배포 가능. GDPR, 의료·금융 규제 환경에서 데이터를 외부로 전송하지 않아도 됩니다
개발자 친화성	Code 노드(JS/Python), HTTP 노드, GraphQL 지원, 외부 npm 패키지 사용 가능. Zapier의 30초 실행 제한 같은 제약이 없습니다
AI 통합 깊이	LangChain AgentExecutor 네이티브 통합, MCP 서버 기능, 벡터 DB 연동 등 AI 파이프라인 구축에 최적화되어 있습니다
오픈소스 생태계	GitHub 98k+ 스타, 활성화된 커뮤니티 노드 생태계, 소스 코드 수정 가능

단점 및 주의사항

항목	내용	대응 방안
학습 곡선	Zapier 대비 초기 진입 장벽이 높습니다	공식 퀵스타트 튜토리얼과 템플릿 갤러리부터 시작하는 것이 좋습니다
인프라 운영 부담	자체 호스팅 시 서버 관리, 보안 패치, 백업 등을 직접 책임져야 합니다	n8n Cloud(관리형) 옵션을 활용하거나, 소규모라면 Railway/Render 등 PaaS를 고려해볼 수 있습니다
커뮤니티 노드 유지보수	서드파티 API 변경 시 커뮤니티 노드는 수동 업데이트가 필요합니다	중요 통합에는 공식 지원 노드 위주로 사용하는 것을 권장합니다
디버깅 복잡성	대규모 워크플로우에서 오류 추적이 Zapier 대비 덜 직관적입니다	워크플로우를 소단위로 분리하고 Error Trigger 노드로 오류 처리 흐름을 별도 구성하는 방법이 효과적입니다

Error Trigger 노드: 워크플로우 실행 중 발생한 오류를 별도의 워크플로우에서 처리할 수 있도록 해주는 노드입니다. Slack 알림이나 로그 저장 등 오류 대응 로직을 분리해 관리할 수 있습니다.

실무에서 가장 흔한 실수

암호화 키 미설정 또는 분실: N8N_ENCRYPTION_KEY를 설정하지 않거나 컨테이너 재생성 시 변경하면 저장된 자격증명이 모두 무효화됩니다. openssl rand -hex 16으로 생성한 값을 반드시 .env 파일이나 시크릿 관리 시스템에 별도 보관해두는 것이 좋습니다.
단일 워크플로우에 모든 로직 집중: 모든 처리를 하나의 워크플로우에 넣으면 디버깅과 유지보수가 어려워집니다. 역할별로 워크플로우를 분리하고 Execute Workflow 노드로 연결하는 패턴을 활용하면 각 단위를 독립적으로 테스트할 수 있습니다.
AI Agent 노드 오류 처리 미흡: LLM이 예상치 못한 형식으로 응답하거나 API 요청 한도를 초과하면 워크플로우 전체가 멈출 수 있습니다. 위 Code 노드 예시처럼 응답 파싱 전에 try-catch로 방어하고, IF 노드로 error: true 분기를 별도로 구성해두는 것이 안전합니다.

마치며

n8n은 단순한 자동화 도구를 넘어, 개발자가 코드의 정밀함과 노코드의 속도를 함께 활용해 AI 에이전트 파이프라인을 구축할 수 있는 플랫폼으로 자리잡았습니다. Vodafone의 위협 인텔리전스 자동화 사례(£2.2M 절감)나 StepStone의 200개 미션 크리티컬 프로세스 운영처럼, n8n의 가능성은 팀 규모와 관계없이 실질적인 결과로 이어집니다.

지금 바로 시작할 수 있는 3단계:

Docker Compose 실행: 위의 docker-compose.yml을 복사하고, openssl rand -hex 16으로 생성한 키를 N8N_ENCRYPTION_KEY에 설정한 뒤 docker compose up -d를 실행합니다.
템플릿 가져오기: n8n.io/workflows에서 "AI Agent" 또는 "Email Automation"으로 검색해 즉시 사용 가능한 워크플로우를 불러옵니다.
이메일 분류 워크플로우 실행: OpenAI API 키를 n8n 자격증명에 등록하고, 위의 Code 노드·AI Agent 노드 구성을 캔버스에 배치합니다.

API 키를 등록하고 첫 이메일 분류 결과를 확인하는 데 10분이면 충분합니다.

다음 글: n8n MCP 서버 기능을 활용해 Claude Desktop에서 사내 워크플로우를 자연어로 호출하는 방법을 다룰 예정입니다.

참고 자료