Make

AI 워크플로우 에이전트 만들기: n8n + Docker로 처음부터 끝까지

## 뭘 만드나 이 튜토리얼을 끝까지 따라하면 n8n 기반의 AI 워크플로우 자동화 시스템을 만들 수 있다. 채팅 메시지를 입력하면 AI가 내용을 분석하고, 외부 서비스(Google Calendar, Slack 등)와 연동해서 자동으로 작업을 수행하는 에이전트다. 예를 들어 "내일 오후 3시에 팀 미팅 잡아줘"라고 입력하면 AI가 일정 정보를 추출해서 Google Calendar에 이벤트를 생성하고, Slack에 알림을 보내는 식이다. 사용 기술 스택: n8n(셀프호스팅), Docker Compose, PostgreSQL, OpenAI GPT-4o 또는 Anthropic Claude Sonnet, LangChain(n8n 내장). "이 튜토리얼을 끝까지 따라하면 이것을 만들 수 있다": HTTPS로 접근 가능한 AI 에이전트가 Docker 컨테이너 위에서 동작하고, 채팅 인터페이스로 대화하면 외부 API를 호출해서 실제 업무를 처리하는 시스템. ## 시작 전 준비  왜 n8n인가: 2026년 현재 워크플로우 자동화 도구 시장에서 n8n, Zapier, Make가 3강 구도를 형성하고 있다. Zapier는 8,000개 이상 앱 연동과 최저 진입 장벽으로 비개발자에게 적합하지만, 월 10,000 태스크 기준 연간 $3,588 수준으로 비용이 급증한다. Make는 시각적 빌더가 뛰어나고 가격 대비 성능이 좋지만 셀프호스팅이 불가능하다. n8n은 셀프호스팅 시 태스크 제한 없이 무료이며, n8n 2.0에서 LangChain 네이티브 통합으로 70개 이상 AI 노드를 제공한다. 데이터 주권이 중요하거나, 월 수만 건의 자동화를 돌려야 하는 팀이라면 n8n이 유일한 현실적 선택지다. 한 DEV Community 기고자는 Zapier에서 n8n으로 전환 후 연간 2,000 유로 이상을 절감했다고 보고했다. 비용 절감도 있지만, 실질적인 차이는 셀프호스팅으로 얻는 데이터 통제권과 커스텀 코드 노드(JavaScript/Python)로 만드는 자유도라고 설명했다. (출처: DEV Community) ### 사전 요구사항 - Docker Desktop 설치 (Docker Compose 포함) - OpenAI API 키 또는 Anthropic API 키 (하나만 있으면 된다) - 기본적인 터미널 사용 경험 - (선택) Google Calendar, Slack API 키 - Step 4 Tool 연동 시 필요 ### 버전 정보 (2026년 4월 기준) - n8n: v1.80+ (Docker 이미지 `n8nio/n8n:latest`) - Docker Compose: v2.x - PostgreSQL: 16 - Node.js: 18+ (n8n 내부 코드 노드용) ### 예상 API 비용 OpenAI GPT-4o 기준 테스트 단계에서 약 $0.50 ~ $2.00 수준. Claude Sonnet 사용 시에도 비슷한 범위. 이 튜토리얼의 모든 단계를 따라하며 여러 번 테스트해도 $5를 넘기기 어렵다. ## 진행 로드맵  ## Step 1: n8n Docker 환경 설정 (입문자 기준 약 15분, 추정치) 프로젝트 디렉토리를 만들고 Docker Compose 파일을 작성한다. ```bash mkdir ~/n8n-ai-agent && cd ~/n8n-ai-agent ``` `docker-compose.yml` 파일을 생성한다: ```yaml version: '3.8' services: postgres: image: postgres:16 restart: always environment: POSTGRES_USER: n8n POSTGRES_PASSWORD: n8n_password POSTGRES_DB: n8n volumes: - postgres_data:/var/lib/postgresql/data n8n: image: n8nio/n8n:latest restart: always ports: - "5678:5678" environment: - DB_TYPE=postgresdb - DB_POSTGRESDB_HOST=postgres - DB_POSTGRESDB_PORT=5432 - DB_POSTGRESDB_DATABASE=n8n - DB_POSTGRESDB_USER=n8n - DB_POSTGRESDB_PASSWORD=n8n_password - N8N_ENCRYPTION_KEY=your-encryption-key-here volumes: - n8n_data:/home/node/.n8n depends_on: - postgres volumes: postgres_data: n8n_data: ``` 컨테이너를 실행한다: ```bash docker compose up -d ``` > 왜 PostgreSQL인가: n8n은 기본적으로 SQLite를 사용하지만, 프로덕션 환경에서는 PostgreSQL이 권장된다. 워크플로우 실행 이력과 자격증명을 안정적으로 저장하고, 컨테이너 재시작 시에도 데이터가 유지된다. n8n 공식 문서에서도 Docker 배포 시 PostgreSQL 사용을 명시적으로 권장하고 있다. 체크포인트: 브라우저에서 `http://localhost:5678`에 접속하면 n8n 초기 설정 화면이 나타나면 성공. 이메일과 비밀번호를 입력해서 owner 계정을 생성한다. 실패 경로: - `port 5678 already in use` 에러 -> `docker-compose.yml`에서 포트를 `5679:5678`로 변경 후 `docker compose up -d` 재실행 - `postgres` 컨테이너가 계속 재시작 -> `docker logs n8n-ai-agent-postgres-1`로 로그 확인. 대부분 볼륨 권한 문제이며, `docker volume rm n8n-ai-agent_postgres_data` 후 재시작으로 해결 - n8n 컨테이너가 `postgres` 연결 실패로 종료 -> `depends_on`이 있어도 PostgreSQL 초기화가 늦을 수 있다. `docker compose down && docker compose up -d`로 재시작 ## Step 2: 트리거 + 기본 플로우 구성 (입문자 기준 약 10분, 추정치) n8n UI에서 첫 번째 워크플로우를 만든다. 1. 좌측 메뉴에서 "Workflows" > "Add Workflow" 클릭 2. 캔버스에 "Chat Trigger" 노드 추가 (노드 추가 버튼 `+` 클릭 후 검색) 3. "Set" 노드 추가하고 Chat Trigger의 출력에 연결 4. Set 노드에서 `response` 필드를 추가하고 값에 `{{ $json.chatInput }}` 입력 이 구성은 사용자가 채팅에 입력한 내용을 그대로 돌려주는 에코 워크플로우다. 단순하지만, 트리거-노드-출력의 기본 흐름을 확인하는 데 필수적이다. > 왜 Chat Trigger인가: n8n의 트리거 노드는 Webhook, Schedule, Chat Trigger 등 여러 종류가 있다. Chat Trigger를 선택하면 n8n UI 내에서 바로 채팅 인터페이스로 테스트할 수 있어서 외부 도구 없이 개발이 가능하다. 프로덕션에서는 Webhook 트리거로 교체해서 Slack이나 커스텀 프론트엔드와 연결할 수 있다. 체크포인트: 워크플로우를 활성화(토글 On)한 뒤, 좌측 하단 채팅 아이콘을 클릭해서 "hello"를 입력한다. "hello"가 그대로 응답으로 돌아오면 성공. 실패 경로: - 채팅 아이콘이 보이지 않음 -> 워크플로우가 비활성 상태. 우측 상단 토글을 확인 - `{{ $json.chatInput }}`이 빈 값 -> Chat Trigger 노드 설정에서 "Chat Input" 필드가 활성화되어 있는지 확인 ## Step 3: AI Agent 노드 연결 - MVE 완성 (입문자 기준 약 20분, 추정치) 이 단계가 핵심이다. n8n의 AI Agent 노드는 LangChain 프레임워크를 내장하고 있어서, 코드를 작성하지 않고도 AI 에이전트를 구성할 수 있다. 1. Step 2에서 만든 Set 노드를 삭제한다 2. "AI Agent" 노드를 추가하고 Chat Trigger에 연결한다 3. AI Agent 노드를 클릭하면 하단에 서브노드 연결 슬롯이 보인다: - "Chat Model" 슬롯: 여기에 LLM을 연결한다 - "Memory" 슬롯: 대화 기록 유지용 (이 단계에서는 비워둔다) - "Tool" 슬롯: 외부 도구 연결용 (이 단계에서는 비워둔다) 4. "OpenAI Chat Model" 또는 "Anthropic Chat Model" 노드를 추가해서 Chat Model 슬롯에 연결: OpenAI 사용 시: - Credential: "Create New Credential" > OpenAI API 키 입력 - Model: `gpt-4o` Anthropic 사용 시: - Credential: "Create New Credential" > Anthropic API 키 입력 - Model: `claude-sonnet-4-20250514` 5. AI Agent 노드의 System Message에 에이전트 역할을 지정한다: ``` You are a helpful assistant that helps users manage their schedule and tasks. When a user asks to create an event, extract the date, time, and description. Respond in Korean. ``` > 왜 AI Agent 노드인가: n8n에는 단순한 "OpenAI" 노드도 있지만, AI Agent 노드를 선택하는 이유는 Tool 연동과 Memory 지원 때문이다. 일반 LLM 노드는 텍스트 입출력만 처리하지만, AI Agent는 "이 작업을 하려면 Google Calendar API를 호출해야 한다"는 판단을 스스로 내릴 수 있다. n8n 2.0에서 LangChain 네이티브 통합이 이루어진 덕분에, ReAct(Think-Act-Observe) 루프가 노드 내부에서 자동으로 동작한다. 체크포인트: 채팅에 "안녕하세요, 당신은 누구인가요?"를 입력한다. AI가 한국어로 자기 소개를 응답하면 MVE(Minimum Viable Example) 완성. 이 시점에서 AI 에이전트의 기본 동작이 확인된 것이다. 실패 경로: - `401 Unauthorized` 에러 -> API 키 확인. Settings > Credentials에서 키 값이 정확한지 점검 - `model not found` 에러 -> 모델명 오타 확인. `gpt-4o`(소문자 o)인지, `claude-sonnet-4-20250514`인지 정확히 입력 - 응답이 영어로 나옴 -> System Message에 "Respond in Korean" 지시가 있는지 확인 - 토큰 초과 에러 -> System Message가 너무 길면 발생. 500자 이내로 줄여본다 ## Step 4: Tool 노드 연결 - 외부 서비스 연동 (입문자 기준 약 15분, 추정치) MVE가 동작하는 상태에서 AI Agent에 도구(Tool)를 추가한다. 이제 AI가 단순히 텍스트를 생성하는 것이 아니라, 실제 외부 API를 호출할 수 있게 된다. 1. AI Agent 노드의 "Tool" 슬롯에 "HTTP Request Tool" 노드를 추가한다 2. HTTP Request Tool 설정: - Name: `create_calendar_event` - Description: `Creates a new event on Google Calendar. Requires: summary (event title), startDateTime (ISO 8601), endDateTime (ISO 8601)` - Method: POST - URL: `https://www.googleapis.com/calendar/v3/calendars/primary/events` - Authentication: OAuth2 (Google Calendar API Credential 필요) - Body: ```json { "summary": "{{ $fromAI('summary') }}", "start": { "dateTime": "{{ $fromAI('startDateTime') }}" }, "end": { "dateTime": "{{ $fromAI('endDateTime') }}" } } ``` `$fromAI()` 함수는 n8n의 핵심 기능이다. AI Agent가 Tool의 Description을 읽고, 필요한 파라미터를 자체적으로 추출해서 전달한다. 개발자가 파싱 로직을 작성할 필요가 없다. > Google Calendar API 설정이 번거롭다면 대안이 있다. n8n에는 "Google Calendar" 전용 노드가 있어서 OAuth2 연결만 하면 된다. HTTP Request Tool 대신 "Google Calendar Tool" 노드를 Tool 슬롯에 연결하면 더 간단하다. 이 튜토리얼에서 HTTP Request를 먼저 보여주는 이유는, 대부분의 실무 API 연동이 HTTP Request 기반이기 때문이다. 체크포인트: 채팅에 "내일 오후 3시에 1시간짜리 팀 미팅 만들어줘"라고 입력한다. AI가 일정 정보를 추출하고 Google Calendar에 이벤트가 생성되면 성공. 실패 경로: - `403 Forbidden` -> Google Calendar API가 활성화되지 않음. Google Cloud Console에서 Calendar API 활성화 필요 - AI가 Tool을 호출하지 않음 -> Tool의 Description이 너무 모호하면 AI가 언제 사용해야 하는지 판단하지 못한다. Description을 구체적으로 작성 - 날짜 파싱 오류 -> System Message에 "현재 날짜는 2026-04-05이다. 날짜를 ISO 8601 형식으로 변환하라"를 추가 ## Step 5: Memory + RAG 확장 (입문자 기준 약 20분, 추정치) 여기까지 오면 AI 에이전트가 동작하지만, 대화 기록을 기억하지 못한다. 매번 새로운 대화처럼 취급된다. Memory 노드를 추가해서 이전 대화 맥락을 유지하게 만든다. ### 5 -1: 대화 메모리 추가 1. AI Agent 노드의 "Memory" 슬롯에 "Buffer Memory" 노드를 연결한다 2. Buffer Memory 설정: - Session Key: `sessionId` (기본값 사용) - Context Window Length: `10` (최근 10턴의 대화를 기억) 이것만으로 AI가 이전 대화를 기억한다. "아까 말한 미팅 시간 변경해줘"라는 요청을 이해할 수 있게 된다. > 왜 Buffer Memory인가: n8n은 Buffer Memory(인메모리), PostgreSQL Chat Memory(영구 저장), Zep Memory(외부 서비스) 등 여러 메모리 옵션을 제공한다. 개발 단계에서는 Buffer Memory가 가장 간단하다. 프로덕션에서는 PostgreSQL Chat Memory로 교체하면 컨테이너 재시작 후에도 대화 이력이 유지된다. 이미 docker-compose.yml에 PostgreSQL이 있으므로 교체가 간단하다. ### 5 -2: RAG(문서 검색) 추가 (선택) AI가 특정 문서를 참조해서 답변하게 만들려면 Vector Store를 추가한다. 1. "Vector Store Tool" 노드를 AI Agent의 Tool 슬롯에 추가 2. Vector Store로 "In-Memory Vector Store" 선택 (테스트용) 3. 임베딩 모델로 "OpenAI Embeddings" 노드 연결 4. 문서 로더로 "PDF Loader" 또는 "Text Loader" 연결 ``` Vector Store Tool 설정: - Name: search_company_docs - Description: Search internal company documents for policies, procedures, and guidelines - Top K: 3 ``` 이 구성은 회사 내부 문서를 검색해서 답변하는 사내 AI 어시스턴트의 기초가 된다. 체크포인트: - 메모리: "내 이름은 김개발이야"라고 입력한 뒤, 다음 메시지로 "내 이름이 뭐야?"라고 물어본다. "김개발"이라고 답하면 메모리가 정상 동작. - RAG: 문서를 로드한 뒤 해당 문서 내용에 대해 질문한다. 관련 내용을 인용하며 답하면 성공. 실패 경로: - 메모리가 동작하지 않음 -> Memory 노드가 AI Agent의 Memory 슬롯에 연결되어 있는지 확인. 독립 노드로 배치하면 동작하지 않는다 - Session ID 불일치 -> 매번 새 세션으로 취급되면 대화가 이어지지 않는다. Session Key 설정 확인 ## Step 6: 프로덕션 배포 (입문자 기준 약 10분, 추정치) 로컬에서 동작하는 AI 에이전트를 외부에서 접근 가능하게 만든다. `docker-compose.yml`에 Nginx 리버스 프록시와 SSL을 추가한다: ```yaml nginx: image: nginx:alpine ports: - "80:80" - "443:443" volumes: - ./nginx.conf:/etc/nginx/conf.d/default.conf - certbot_data:/etc/letsencrypt depends_on: - n8n ``` `nginx.conf` 예시: ```nginx server { listen 80; server_name your-domain.com; location / { proxy_pass http://n8n:5678; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; } } ``` SSL은 Let's Encrypt certbot을 사용하거나, Cloudflare Tunnel을 활용하면 인증서 관리 없이 HTTPS를 적용할 수 있다. VPS 비용은 월 $5 수준(DigitalOcean, Contabo 등)이면 충분하다. n8n의 환경변수에 웹훅 URL을 추가한다: ```yaml - N8N_HOST=your-domain.com - N8N_PROTOCOL=https - WEBHOOK_URL=https://your-domain.com/ ``` 체크포인트: 외부 네트워크에서 `https://your-domain.com`으로 접속해서 n8n UI가 뜨면 성공. 채팅 워크플로우를 Webhook 트리거로 교체하면 Slack 봇이나 웹 프론트엔드와 연결할 수 있다. ## 확장 과제 ### 난이도: 쉬움 - Slack 봇 연동 Chat Trigger를 Slack Webhook으로 교체하고, Slack 채널에서 AI 에이전트와 대화하는 구조로 변경한다. n8n의 Slack 노드를 사용하면 30분 이내에 구현 가능. ### 난이도: 보통 - 다중 도구 에이전트 Google Calendar 외에 Gmail(이메일 전송), Google Sheets(데이터 기록), Notion(문서 관리) 등 여러 Tool을 AI Agent에 연결한다. AI가 사용자 요청에 따라 적절한 도구를 자동 선택하게 된다. n8n 커뮤니티에 6,200개 이상의 워크플로우 템플릿이 공개되어 있어 참고할 수 있다. (출처: n8n.io) ### 난이도: 어려움 - Orchestrator-Agent-Worker 패턴 2026년 n8n 생태계에서 주목받는 패턴으로, n8n이 오케스트레이터 역할을 하고 여러 AI 에이전트가 각자 전문 영역을 담당하는 구조다. 예를 들어 "리서치 에이전트"가 웹 검색을 수행하고, "작성 에이전트"가 보고서를 생성하며, "검수 에이전트"가 품질을 확인하는 파이프라인이다. 이 구조는 단일 에이전트보다 복잡하지만, 각 에이전트의 시스템 프롬프트를 작업 특화로 작성할 수 있어 품질이 높아진다. (출처: OpenClaw 2026 Conference) ## 트러블슈팅  ### Docker 컨테이너 문제 - `docker compose up` 시 에러 -> `docker compose version`으로 v2 이상인지 확인. macOS의 Docker Desktop 최신 버전이면 기본 포함 - 메모리 부족 -> Docker Desktop Settings > Resources에서 메모리를 4GB 이상으로 설정 - 볼륨 데이터 손상 -> `docker compose down -v`로 볼륨 삭제 후 재시작 (데이터 초기화됨) ### AI Agent 노드 문제 - `429 Too Many Requests` -> API rate limit. OpenAI는 분당 요청 제한이 있다. n8n의 "Wait" 노드를 중간에 넣어서 간격을 둘 수 있다 - 응답이 너무 느림 -> GPT-4o 대신 GPT-4o-mini를 사용하면 속도가 2-3배 빨라지지만 품질이 다소 하락한다. Claude Sonnet은 GPT-4o와 비슷한 속도-품질 밸런스를 제공한다 - AI가 Tool을 호출했지만 결과를 무시함 -> AI Agent의 "Return Intermediate Steps"를 활성화해서 중간 과정을 확인. Tool 호출 결과가 Agent에 제대로 전달되는지 점검 ### n 8n 공식 리소스 문제 해결이 안 되면 n8n 커뮤니티 포럼(community.n8n.io)에서 에러 메시지로 검색하는 것이 가장 빠르다. 공식 문서(docs.n8n.io)의 Advanced AI 섹션에 AI 워크플로우 전용 가이드가 있다. ```references https://docs.n8n.io/advanced-ai/intro-tutorial/ https://n8n.io/ai/ https://n8n.io/ai-agents/ https://blog.n8n.io/ai-workflow-automation/ https://dev.to/automatewithai/n8n-vs-zapier-in-2026-why-i-switched-and-saved-eu2000year-59l7 https://contabo.com/blog/n8n-vs-zapier-vs-make-an-in-depth-comparison/ https://docs.n8n.io/hosting/installation/docker/ https://kollox.com/openclaw-2026-architecting-agentic-workflows-with-n8n/ https://www.lowcode.agency/blog/n8n-features https://hatchworks.com/blog/ai-agents/n8n-ai-agent/ ```