n8n AI Agent 노드는 언어 모델을 자율적인 워크플로우 참여자로 변환합니다. 단일 프롬프트 → 응답 방식 대신, 에이전트(Agent)는 도구(tools)를 사용하고, 추론 단계를 반복하며, 메모리(memory)를 참조하여 구조화된 결과를 생성할 수 있습니다. 이 모든 과정은 사용자가 오케스트레이션(orchestration) 코드를 작성할 필요 없이 이루어집니다.

이 가이드는 모든 설정 옵션, 사용자들이 흔히 겪는 실수(gotchas), 세 가지 프로덕션 준비 완료 패턴, 그리고 무료 워크플로우 JSON을 다룹니다.

AI Agent 노드가 하는 일

AI Agent 노드는 ReAct 스타일의 루프를 구현합니다:

1. Reason (추론) — 모델이 작업을 읽고 어떤 도구를 사용할지 결정합니다.
2. Act (실행) — 해당 도구(n8n 서브 워크플로우, HTTP Request, 계산기, 코드 등)를 호출합니다.
3. Observe (관찰) — 도구의 결과가 다시 피드백됩니다.
4. Repeat (반복) — 모델이 답변하기에 충분한 정보가 모였다고 판단할 때까지 반복합니다.

이 루프는 n8n 내부에서 실행되며 완전한 관찰 가능성(observability)을 제공합니다. 모든 단계는 실행 로그(execution log)에 나타납니다.

에이전트 유형 (Agent types)

에이전트 유형	사용 시점
Tools Agent	범용 목적. 모델이 사용자가 제공한 목록에서 도구를 선택합니다. 가장 권장되는 기본 선택지입니다.
...

대부분의 자동화 작업에는 Tools Agent로 시작하는 것이 좋습니다.

모델 연결하기

AI Agent 노드는 Chat Model 서브 노드가 필요합니다. 지원되는 제공업체는 다음과 같습니다:

• OpenAI Chat Model (gpt-4o, gpt-4o-mini)
• Anthropic Chat Model (claude-opus-4, claude-sonnet-4-6)
• Google Gemini Chat Model
• Ollama Chat Model (자체 호스팅)
• OpenRouter Chat Model (OpenRouter API를 통한 모든 모델)

Chat Model 노드를 AI Agent 노드의 Model 입력에 연결하세요. 각 Chat Model 노드는 자체적인 자격 증명(credential)과 모델 선택기를 가집니다.

주의 사항 — 모델 능력: ReAct 및 도구 사용(tool-use) 에이전트는 함수 호출(function calling)을 기본적으로 지원하는 모델(GPT-4o, Claude 3+, Gemini 1.5+ 등)에서 가장 잘 작동합니다. 오래되었거나 크기가 작은 모델은 도구 호출을 환각(hallucinate)하거나 무한 루프에 빠질 수 있습니다.

도구 (Tools)

도구는 에이전트에게 힘을 부여하는 요소입니다. 이를 Tools 입력에 연결하세요:

내장 도구 (Built-in tool)	기능
Calculator	산술 연산 — 모델이 수학적 환각 (Hallucination)을 일으키는 것을 방지함
...

**n8n 워크플로우 도구 (The n8n Workflow Tool)**를 사용하면 기존의 모든 n8n 워크플로우를 호출 가능한 도구로 래핑(wrap)할 수 있습니다. 에이전트(Agent)가 자연어로 필요한 내용을 설명하면, 도구가 해당 워크플로우를 실행하고 그 결과가 에이전트의 추론 루프(reasoning loop)로 돌아옵니다. 이는 에이전트가 이메일을 보내거나, 데이터베이스를 조회하거나, Notion 페이지를 생성하거나, Stripe를 호출하는 등 n8n에서 할 수 있는 모든 작업을 수행할 수 있음을 의미합니다.

메모리 (Memory)

메모리(Memory)를 사용하면 에이전트가 호출 간에 문맥(Context)을 유지할 수 있습니다. Memory 입력에 메모리 노드를 연결하세요:

메모리 유형 (Memory type)	저장소 (Storage)	사용 사례 (Use case)
Window Buffer Memory	프로세스 내 (RAM)	단일 세션, 영속성 없음
...

단순한 단회성 워크플로우의 경우 메모리를 생략하세요. 챗봇이나 이전 실행 내용을 기억해야 하는 워크플로우의 경우, Postgres 또는 Redis 메모리를 연결하세요.

핵심 설정 (Core configuration)

필드 (Field)	참고 사항 (Notes)
System Message	에이전트의 기본 지침 — 역할, 제약 조건, 출력 형식, 도구 가이드
...

주의 사항 및 일반적인 오류 (Gotchas & common errors)

1. 무한 루프 (Infinite loops)

모델이 사용 가능한 도구로 작업을 완료할 수 없는 경우, 최대 반복 횟수(Max Iterations)에 도달할 때까지 루프를 돕니다. 개발 중에는 Max Iterations를 낮은 값(5–8)으로 설정하세요. 모델이 자신이 막혀 있는지 명시적으로 추론할 수 있도록 Think Tool을 추가하세요.

2. 도구 설명의 품질이 성능을 결정함

에이전트는 도구의 설명을 바탕으로 도구를 선택합니다. 동료에게 문서를 작성하듯 도구 설명을 작성하세요:

• 나쁨: "Database tool"
• 좋음: "고객 Postgres 데이터베이스를 조회합니다. 입력: SQL SELECT 문. 출력: 행 객체 배열. 고객 기록, 주문 또는 구독 상태를 조회할 때 사용하세요."

3. 자격 증명 접근 (Credential access)

에이전트는 해당 노드가 가진 자격 증명(Credentials)을 사용하여 도구를 실행합니다. 각 서브 워크플로우(sub-workflow)와 도구 노드에 자격 증명이 연결되어 있는지 확인하세요. 에이전트 자체에는 자격 증명이 없으며, 에이전트의 도구들이 자격 증명을 가집니다.

4. 비용 폭주 (Cost runaway)

각 도구 호출(tool call)은 토큰을 소모합니다. GPT-4o를 사용하여 5번의 반복(iteration)이 필요한 복잡한 작업을 수행하면 $0.10 이상의 비용이 발생할 수 있습니다. 최대 성능이 필요하지 않은 작업에는 gpt-4o-mini 또는 claude-haiku를 사용하세요. 토큰 사용량은 n8n의 실행 로그(execution log)가 아닌 OpenAI/Anthropic 대시보드를 통해 모니터링해야 합니다.

5. 중간 단계 반환(Return Intermediate Steps) 출력 형태

Return Intermediate Steps가 활성화되면, 출력에 intermediateSteps 배열이 포함됩니다. 후속 노드(downstream nodes)가 평면적인(flat) output 필드를 기대하는 경우, 정규화(normalize)를 위해 Code 노드가 필요할 수 있습니다:

return [{ json: { result: $input.first().json.output } }];

6. 구조화된 출력(Structured output) vs 자유 텍스트(free text)

기본적으로 에이전트(Agent)는 output 문자열을 반환합니다. JSON이 필요한 경우, Output Parser(Structured Output Parser 또는 Auto-Fixing Output Parser)를 추가하고 Zod 스키마를 정의하세요. 이를 통해 후속 노드에서의 파싱 오류(parsing errors)를 방지할 수 있습니다.

3가지 워크플로우 패턴

패턴 1: 고객 지원 분류(triage) 에이전트

Webhook (수신된 지원 티켓)
→ AI Agent (Tools Agent, GPT-4o-mini)
  System: "당신은 지원 분류(triage) 에이전트입니다. 문제를 분류하고, 알려진 문제인지 확인한 후, 답변 초안을 작성하세요. CRM 도구를 사용하여 고객을 조회하세요. 지식 베이스(knowledge base) 도구를 사용하여 관련 문서를 찾으세요."
...

사용 사례: 사람이 확인하기 전에 티켓의 80%를 자동으로 분류하고 초안을 작성합니다.

패턴 2: 조사 및 요약 에이전트

Schedule Trigger (매일 아침 07:00)
→ HTTP Request (API를 통해 오늘의 Hacker News 상위 20개 항목 가져오기)
→ AI Agent (Tools Agent)
...

사용 사례: 20개의 탭을 일일이 읽지 않고도 매일 개인화된 뉴스 요약을 받아봅니다.

패턴 3: 데이터 보강(Data enrichment) 에이전트

Webhook (양식을 통한 신규 리드)
→ AI Agent (Tools Agent, gpt-4o-mini)
  System: "리드 정보를 보강하세요. 회사의 웹사이트, LinkedIn 페이지, 예상 직원 수를 찾으세요. LinkedIn에서 해당 인물을 검색하세요. 우리의 ICP(B2B SaaS, 직원 10-500명)에 부합하는지 평가하세요. 다음을 포함하는 JSON 객체를 반환하세요: company_website, linkedin_url, employee_estimate, icp_fit (high/medium/low), fit_reason."
...

활용 사례: 퍼널 상단(top of the funnel)에서의 자동화된 리드 보강(lead enrichment) 및 ICP 점수 산정.

무료 워크플로우 JSON

다음은 기초적인 조사 및 요약(research-and-summarise) 에이전트입니다:

{
  "name": "AI Research Agent Starter",
  "nodes": [
...

Settings → Import from URL/Clipboard를 통해 가져오세요. 활성화하기 전에 Chat Model 노드(OpenAI 또는 Anthropic)를 Model 입력에 연결하십시오.

다음 단계

• 도구 사용(tool use)이 필요하지 않을 때 직접적인 완료(completions)를 수행하려면 n8n OpenAI node를 추가하세요.
• 외부 이벤트로부터 에이전트를 트리거하려면 n8n Webhook node를 사용하세요.
• 채팅을 통한 대화형 에이전트 인터페이스를 구축하려면 n8n Telegram node와 결합하세요.
• 미리 구축된 자동화 패턴을 확인하려면 전체 n8n Workflow Starter Pack을 살펴보세요.

여러분은 n8n AI Agent 노드로 무엇을 만들고 계신가요? 여러분의 활용 사례를 댓글로 남겨주세요.