n8n AI 에이전트 구축 가이드: VPS에서 직접 만들기

n8n AI 에이전트란 무엇이며, 체인과는 어떻게 다른가

n8n AI 에이전트는 하나의 AI Agent 노드에 채팅 모델, 하나 이상의 도구, 선택적 메모리 등 하위 노드가 연결된 형태입니다. 사용자가 평문으로 목표를 제시하면, 모델은 답변을 완료할 때까지 어떤 도구를 어떤 순서로 호출할지 스스로 결정합니다. 아래의 모든 내용은 이 개념을 중심으로 구성된 설정입니다.

체인은 이와 반대로 작동합니다. Basic LLM Chain에서는 사용자가 단계를 결정하고 모델은 텍스트만 채워 넣습니다. 반면 에이전트는 모델이 단계를 결정하므로, 동일한 질문이라도 오늘 한 번의 모델 호출로 끝날 수 있는 작업이 내일은 아홉 번의 호출을 필요로 할 수도 있습니다. 이 단 하나의 차이가 이 가이드의 모든 설정을 결정짓습니다.

이 가이드는 n8n이 사용자가 제어하는 머신에서 HTTPS 뒤에서 이미 실행 중임을 전제로 합니다. 만약 그렇지 않다면, Docker에서 실제 인증서를 사용하여 n8n을 직접 호스팅하는 방법부터 시작하십시오. 저장할 API 키에는 해당 가이드에서 강조하는 암호화 키 백업이 필요하기 때문입니다. 에이전트 이외의 패턴인 웹훅 요약기나 예약된 분류기에 대해서는 Claude와 n8n 워크플로우 패턴을 참조하십시오.

n8n은 AI 노드를 자주 변경하므로, 이 가이드의 필드 이름을 신뢰하기 전에 버전을 확인하십시오.

docker compose exec n8n n8n --version

이 가이드의 명칭은 2026년 7월 기준 n8n 최신 안정 버전과 일치합니다. 버전 1.82.0부터 모든 AI Agent 노드는 Tools Agent로 실행되므로, 기존의 에이전트 유형 드롭다운은 더 이상 존재하지 않습니다.

1단계: 트리거 선택

대화형 에이전트의 경우 Chat Trigger 노드를 추가합니다. 에이전트를 구축하는 동안에는 Make Chat Publicly Available 옵션을 끈 상태로 유지하여, 편집기의 채팅 패널에서만 접근할 수 있도록 합니다. 에이전트 개발이 완료되고 인증 방식을 결정한 후에 이 옵션을 켭니다.

Chat Trigger는 에이전트에 chatInput이라는 필드를 전달합니다. 이 이름은 3단계에서 중요하게 사용되며, 이름을 잘못 입력하는 것이 가장 흔히 발생하는 첫 번째 오류입니다.

무인 에이전트의 경우 대신 Schedule Trigger 또는 Webhook 노드를 사용합니다. 이 노드들은 chatInput을 생성하지 않으므로, 프롬프트를 직접 작성해야 합니다.

2단계: 모델 자격 증명

캔버스에 AI Agent 노드를 배치합니다. n8n은 즉시 노드 아래에 빈 Chat Model 커넥터를 표시합니다. 여기에 Anthropic Chat Model 하위 노드를 연결합니다.

Anthropic Console(platform.claude.com)의 Settings 내 API Keys 메뉴에서 자격 증명을 생성합니다. 키는 한 번만 표시됩니다. API 사용료는 토큰 단위로 청구되며 Claude.ai 구독과는 별개이므로, 첫 실행 전에 계정에 결제 수단을 설정해야 합니다.

모델은 회사 단위가 아닌 에이전트 단위로 선택합니다. 단순히 정보를 조회하고 보고하는 단일 도구 에이전트는 Haiku 모델로도 충분히 작동합니다. 2026년 7월 기준 Haiku의 비용은 입력 토큰 100만 개당 $1, 출력 토큰 100만 개당 $5입니다. 에이전트가 여러 도구를 사용하여 계획을 세워야 하는 단계가 되면 Sonnet으로 전환하십시오. 저렴한 모델이 잘못된 도구를 4번 호출하여 발생하는 비용이, 고성능 모델이 올바른 도구를 1번 호출하는 비용보다 더 클 수 있다는 점을 주의해야 합니다.

하위 노드의 옵션에서 Maximum Number of Tokens를 설정합니다. 이는 모델이 생성하는 각 응답의 길이를 제한합니다. 기본값을 크게 두면, 에이전트가 오작동할 경우 매우 긴 답변을 생성하여 불필요한 비용이 발생할 수 있습니다.

n8n 문서에서 자주 간과되는 주의 사항이 하나 있습니다. 하위 노드 내부의 표현식은 항상 첫 번째 입력 항목을 기준으로 해석되며, 항목별로 해석되지 않습니다. 항목별 표현식은 루트 노드의 프롬프트 필드에 작성하십시오.

3단계: 에이전트가 수신하는 프롬프트

AI Agent 노드를 엽니다. Prompt 매개변수에는 두 가지 설정이 있습니다.

• Take from previous node automatically는 chatInput라는 이름의 입력 필드를 기대합니다. Chat Trigger 뒤에 배치할 때 적합한 선택입니다.
• Define below를 선택하면 정적 텍스트나 표현식을 작성할 수 있는 Prompt (User Message) 필드가 나타납니다. Schedule Trigger나 Webhook 노드 뒤에 배치할 때 적합한 선택입니다.

앞단에 Webhook 노드가 있는 경우, POST 본문은 $json.body 아래에 위치하므로 프롬프트 필드는 다음과 같이 구성됩니다.

Check the current status of {{ $json.body.service }} and tell me
whether it is up. If it is down, say for how long. No preamble.

4단계: 에이전트에 도구 하나 추가하기

도구 하위 노드가 없는 AI Agent 노드는 실행되지 않습니다. 도구 4개를 어설프게 설정하는 것보다 제대로 작동하는 도구 1개를 설정하는 것이 학습에 더 효과적이므로, 하나로 시작하십시오.

에이전트의 Tool 커넥터에 HTTP Request 노드를 연결합니다. 일반 HTTP Request 노드를 설정하는 것과 동일하게 설정한 뒤, 먼저 셸에서 해당 엔드포인트를 테스트하십시오.

curl -s -H 'Accept: application/json' \
  https://status.example.com/api/status/database | head -c 400

만약 curl 명령이 오류를 반환하거나 HTML 로그인 페이지를 출력한다면, 에이전트 역시 실패하게 됩니다. 이때 발생하는 오류는 모델의 문제처럼 보일 수 있지만, 실제로는 URL이나 인증 문제입니다. 노드가 아닌 셸에서 먼저 문제를 해결하십시오.

도구의 Description 필드는 동료를 위한 문서가 아닙니다. 모델이 이 도구를 사용할지 결정할 때 읽는 유일한 정보입니다. "모니터링 중인 서비스 하나의 현재 상태(up/down)와 다운타임 지속 시간을 JSON 형식으로 반환함"과 같이 결과값을 명확하게 기술하십시오.

모델이 요청의 일부를 채우게 하려면 $fromAI() 표현식을 사용하십시오. 이 기능은 AI Agent 노드에 연결된 도구에서만 작동하며, Code 도구에서는 사용할 수 없습니다.

{{ $fromAI('service', 'The name of the service to look up', 'string') }}

인자는 key이며, 그 뒤에 선택적으로 description, type, defaultValue를 추가할 수 있습니다. 키는 1~64자 사이여야 하며, 영문자, 숫자, 밑줄(_), 하이픈(-)만 사용할 수 있습니다. 타입은 string, number, boolean, json 중 하나를 선택하며, 기본값은 string입니다. 전체 호출 예시는 다음과 같습니다.

{{ $fromAI('limit', 'How many records to return', 'number', 20) }}

키는 기존 데이터를 참조하는 것이 아니라 힌트 역할을 합니다. $fromAI('service')은 어디선가 service라는 필드를 읽어오는 것이 아닙니다. 이는 모델에게 "값을 생성하고 그 이름을 service라고 하라"고 지시하는 것이며, 모델은 대화 내용, 입력 데이터, 다른 도구의 결과 등을 살펴보고 값을 찾습니다. 채팅 워크플로우에서는 모델이 사용자에게 직접 물어볼 수도 있습니다.

웹 검색은 보통 두 번째로 추가하는 도구입니다. 이는 다른 HTTP 엔드포인트와 다를 바 없으므로, 유료 검색 API 대신 직접 구축한 SearXNG 인스턴스를 이 노드에 연결할 수 있습니다. 단, 검색 결과로 가져온 모든 페이지는 신뢰할 수 없는 텍스트로 간주하여 프롬프트에 포함해야 합니다.

5단계: 메모리, 그리고 에이전트가 기억을 잃는 이유

메모리 하위 노드가 없으면 모든 메시지는 아무런 맥락 없이 시작됩니다. 최근 대화 내용을 유지하려면 Simple Memory 하위 노드를 연결하십시오.

이 노드에는 두 가지 매개변수가 있습니다. Session Key는 현재 대화가 어떤 것인지 결정하므로, 서로 다른 키를 가진 두 사용자는 각자의 대화 기록을 갖게 됩니다. Context Window Length는 이전 대화 중 몇 개를 프롬프트에 다시 포함할지 결정합니다.

Context Window Length는 품질을 조절하는 도구인 동시에 비용을 결정하는 요소이기도 합니다. 기억된 모든 대화는 이후 호출될 때마다 입력 토큰으로 다시 전송되기 때문입니다. 대화가 많은 에이전트에서 윈도우 값을 20으로 설정하면, 초기 메시지들을 20번이나 반복해서 비용을 지불하게 됩니다.

n8n이 큐 모드(queue mode)로 실행되는 활성 프로덕션 워크플로우에서는 Simple Memory가 작동하지 않습니다. 대화 기록이 공유 저장소가 아닌 워크플로우 자체 데이터에 저장되기 때문입니다. 큐 모드 인스턴스에서는 대신 Postgres Chat Memory 하위 노드를 사용하고, 메인 프로세스와 워커가 모두 접근할 수 있는 데이터베이스를 지정하십시오.

6단계: 시스템 메시지

에이전트의 Options를 열고 System Message를 추가합니다. 이곳에 직무 기술서를 입력하며, 이는 워크플로우에서 가장 영향력이 큰 텍스트입니다.

You are an infrastructure status assistant. Always call the status
tool before answering a question about whether something is running.
Never guess. If the tool returns an error, say so and stop.

"Always call the status tool before answering"와 같은 지침은 실질적인 역할을 수행합니다. 이 지침이 없으면 모델은 이미 답을 알고 있다고 판단하여 도구를 호출하지 않고 메모리에 의존해 답변합니다. 이는 인프라가 변경되는 즉시 잘못된 정보를 자신 있게 제공하는 결과를 초래합니다.

에이전트가 루프에 빠지는 이유와 이를 중단하는 방법

Options 항목에는 기본값이 10으로 설정된 Max Iterations가 있습니다. 한 번의 반복(iteration)은 모델 호출 한 번과 그에 따른 도구 결과가 컨텍스트로 다시 전달되는 과정을 의미합니다. 따라서 에이전트 실행 한 번은 단일 API 호출이 아니라 최대 10번의 호출을 포함하며, 각 호출은 계속 커지는 전체 대화 내용을 입력으로 전달받습니다.

이 값을 낮추십시오. 대부분의 단일 도구 에이전트는 2번의 반복 내에 작업을 완료합니다. 제한을 3 또는 4로 설정하면 무한 루프를 실행 목록에서 확인할 수 있는 깔끔한 실패로 전환할 수 있습니다.

디버깅 중에는 Return Intermediate Steps를 켜십시오. 최종 출력에 에이전트가 수행한 도구 호출 과정이 포함되므로, "모델이 도구를 전혀 호출하지 않음"과 "도구가 유용한 결과를 반환하지 않음"을 구분할 수 있습니다. 최종 사용자에게는 이러한 단계가 불필요한 정보가 되므로, 운영 환경으로 배포하기 전에 다시 끄십시오.

셸에서 실행 과정을 모니터링하십시오.

docker compose logs -f n8n

무인 에이전트의 예기치 않은 비용 지출 방지

Chat Trigger 뒤의 agent에는 사람이 개입하며, 답변이 잘못되어 보이면 사람이 agent를 중지한다. Schedule Trigger 뒤의 agent는 지켜보는 사람이 없다. 여기서 관리해야 하는 대상은 라이선스 비용이 아니라 모델 사용 비용이다. agent, tool, memory 노드는 모두 무료 self-hosted edition에서 동작하기 때문이다. 유료 key가 필요한 기능은 대부분 팀 및 거버넌스 기능이다. 자세한 내용은 항상 실행되는 VPS에서 AI agent 비용 제어하기를 참조한다. 여기서는 4가지 설정이 대부분의 작업을 처리한다.

• 모델 하위 노드에서 Maximum Number of Tokens를 제한하여 단일 응답이 길어지지 않도록 합니다.
• Max Iterations를 작업을 완료할 수 있는 최소한의 숫자로 설정합니다.
• 도구 응답을 작게 유지합니다. 4,000줄의 JSON 블롭을 반환하는 도구는 해당 내용을 다음 모델 호출에 모두 포함하며, 이후 동일한 실행 내의 모든 호출에도 포함됩니다.
• 에이전트에 스케줄이 반드시 필요한지 자문해 보십시오. 5분마다 실행되는 작업은 하루에 288번 실행됩니다. 1회 실행 비용에 288을 곱한 값이 일일 비용이 됩니다.

워크플로우를 수정하는 동안에는 비활성화하십시오. Schedule Trigger가 활성화된 워크플로우는 n8n에 저장된 버전을 기준으로 계속 실행되는데, 이는 화면에 표시된 버전과 항상 일치하지는 않습니다.

FAQ

AI Agent 노드가 실행되지 않는 이유는 무엇입니까?

AI Agent 노드는 채팅 모델 하위 노드와 최소 하나의 도구 하위 노드를 필요로 합니다. 모델은 있지만 도구가 없는 노드는 API 호출을 시도하기 전에 실패합니다. 간단한 도구라도 하나 연결한 뒤 다시 실행하십시오.

에이전트가 답변은 하지만 도구를 호출하지 않습니다. 무엇이 문제입니까?

대부분 도구의 Description 필드 때문입니다. 모델은 이 설명을 읽고 도구를 선택하므로, "HTTP Request"와 같은 설명은 도구를 언제 사용해야 할지 알려주지 못합니다. 어떤 데이터가 반환되는지, 어떤 상황에서 유용한지 명시하여 설명을 다시 작성하십시오. 그런 다음 System Message에 답변하기 전에 해당 도구를 호출하라는 지시문을 한 줄 추가하십시오.

같은 질문인데 실행할 때마다 비용이 다른 이유는 무엇입니까?

모델이 단계 수를 결정하기 때문입니다. 각 반복마다 이전 도구 출력을 포함한 전체 대화 내용을 다시 전송하므로, 4번 반복한 실행은 단일 호출보다 훨씬 많은 비용이 발생합니다. Max Iterations는 반복 횟수의 상한선이며, Return Intermediate Steps를 통해 특정 실행에서 실제로 몇 단계가 사용되었는지 확인할 수 있습니다.

에디터에서는 메모리가 작동하는데 운영 환경에서는 작동하지 않습니다. 무엇이 바뀌었습니까?

인스턴스가 큐 모드(queue mode)로 실행 중인지 확인하십시오. Simple Memory는 워크플로우의 자체 실행 데이터에 기록을 저장하는데, 이는 별도의 워커 프로세스로 전달될 때 유지되지 않으므로 운영 중인 워크플로우에서는 기록이 소실됩니다. 모든 워커가 공유하는 데이터베이스에 기록을 저장하는 Postgres Chat Memory 하위 노드로 교체하십시오.