n8n AI Agent를 개인 VPS에 구축하는 방법

n8n AI agent란 무엇이며 chain과 어떻게 다른가

n8n AI agent는 하나의 AI Agent 노드에 하위 노드를 연결한 구성입니다. 여기에는 하나의 chat model, 하나 이상의 tools, 그리고 선택 사항인 memory가 포함됩니다. 일반 언어로 목표를 지정하면 model이 응답할 수 있을 때까지 호출할 tool과 호출 순서를 결정합니다. 아래의 모든 내용은 이 한 가지 개념을 중심으로 한 구성입니다.

chain은 반대로 작동합니다. Basic LLM Chain에서는 사용자가 단계를 결정하고 model은 텍스트만 작성합니다. agent에서는 model이 단계를 결정하므로 같은 질문에 대해 오늘은 model 호출 1회가 필요하고 내일은 9회가 필요할 수 있습니다. 이 한 가지 차이가 이 가이드의 모든 설정에 영향을 줍니다.

이 문서는 사용자가 관리하는 시스템에서 n8n이 이미 HTTPS 뒤에서 실행 중이라고 가정합니다. 그렇지 않다면 먼저 실제 인증서를 사용하여 Docker에서 n8n 자체 호스팅하기를 진행합니다. 곧 저장할 API key에는 해당 가이드에서 요구하는 encryption-key 백업이 필요하기 때문입니다. agent를 사용하지 않는 패턴인 webhook summarizer와 예약된 classifier에 대해서는 Claude 및 n8n workflow 패턴을 참조합니다.

여기에 표시된 field 이름을 신뢰하기 전에 version을 확인합니다. n8n은 AI 노드를 자주 변경하기 때문입니다.

docker compose exec n8n n8n --version

이 가이드의 이름은 2026년 7월 기준 n8n current stable과 일치합니다. version 1.82.0부터 모든 AI Agent 노드는 Tools Agent로 실행되므로 이전 agent-type dropdown은 더 이상 존재하지 않습니다.

1단계: 트리거 선택

대화형 에이전트에는 Chat Trigger 노드를 추가합니다. 구축하는 동안에는 Make Chat Publicly Available을 끈 상태로 둡니다. 이렇게 해야 편집기의 채팅 패널만 에이전트에 접근할 수 있습니다. 에이전트가 완성되고 인증 방식을 결정한 후에 이 옵션을 켭니다.

Chat Trigger는 chatInput이라는 필드를 에이전트에 전달합니다. 이 이름은 3단계에서 중요합니다. 이름을 잘못 지정하는 것이 처음 발생하는 가장 일반적인 오류입니다.

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

2단계: 모델 자격 증명

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

platform.claude.com의 Anthropic Console에서 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 매개변수에는 2가지 설정이 있습니다.

• 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 노드는 실행을 거부합니다. 먼저 도구 하나를 연결합니다. 제대로 작동하는 도구 하나가 불완전하게 구성된 도구 네 개보다 더 많은 정보를 제공합니다.

HTTP Request 노드를 에이전트의 Tool 커넥터에 연결합니다. 일반적인 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라고 부르라"고 지시합니다. 그러면 모델은 대화, 입력 데이터 및 다른 도구 결과를 확인해 값을 찾습니다. 채팅 워크플로에서는 사용자에게 직접 물어볼 수도 있습니다.

5단계: 메모리와 에이전트가 대화를 잊는 이유

메모리 하위 노드가 없으면 모든 메시지가 아무런 대화 기록 없이 시작됩니다. 최근 대화를 저장하려면 Simple Memory 하위 노드를 연결합니다.

이 노드에는 2개의 매개변수가 있습니다. Session Key는 대화를 식별하므로 키가 다른 두 사용자는 서로 분리된 기록을 사용합니다. Context Window Length는 프롬프트에 다시 포함할 이전 상호작용의 수입니다.

Context Window Length는 품질뿐 아니라 비용도 조절합니다. 기억된 각 대화 차례가 이후 호출마다 입력 토큰으로 다시 전송되기 때문입니다. 대화가 많은 에이전트에서 창 크기를 20으로 설정하면 초기에 입력한 동일한 메시지에 대해 20번 비용을 지불하게 됩니다.

n8n이 queue mode로 실행될 때 Simple Memory는 활성 production workflow에서 작동하지 않습니다. 대화 기록이 공유 저장소가 아니라 workflow 자체의 데이터에 저장되기 때문입니다. queue mode 인스턴스에서는 대신 Postgres Chat Memory 하위 노드를 사용하고, main process와 workers가 모두 접근할 수 있는 데이터베이스를 지정합니다.

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도 있습니다. 한 번의 반복은 모델 호출 1회와 컨텍스트에 다시 전달되는 도구 결과 1개로 구성됩니다. 따라서 에이전트 실행 1회는 API 호출 1회가 아니라 최대 10회이며, 각 호출에는 계속 증가하는 전체 대화가 입력으로 포함됩니다.

이 값을 낮추십시오. 대부분의 단일 도구 에이전트는 2회의 반복으로 완료됩니다. 제한을 3 또는 4로 설정하면 무한 반복을 실행 목록에서 확인할 수 있는 정상적인 실패로 바꿀 수 있습니다.

디버깅하는 동안 Return Intermediate Steps를 켜십시오. 그러면 최종 출력에 에이전트가 실행 중 수행한 도구 호출이 포함됩니다. 이를 통해 "모델이 도구를 호출하지 않은 경우"와 "도구가 유용한 결과를 반환하지 않은 경우"를 구분할 수 있습니다. 운영 환경에 배포하기 전에는 이 옵션을 다시 끄십시오. 최종 사용자에게 이러한 단계는 불필요한 정보이기 때문입니다.

셸에서 실행 과정을 확인하십시오.

docker compose logs -f n8n

무인 agent의 조용한 비용 지출 방지

Chat Trigger 뒤의 agent에는 사람이 개입하며, 답변이 잘못된 것처럼 보이면 해당 사람이 agent를 중지합니다. Schedule Trigger 뒤의 agent는 감시하는 사람이 없습니다. 자세한 내용은 항상 실행되는 VPS에서 AI agent 비용 제어를 참조합니다. 여기서는 4가지 설정이 대부분의 작업을 처리합니다.

• model sub-node에서 Maximum Number of Tokens를 제한합니다. 그러면 단일 응답이 지나치게 길어지지 않습니다.
• 작업을 완료하는 데 필요한 최소값으로 Max Iterations를 설정합니다.
• tool 응답을 작게 유지합니다. 4,000줄의 JSON blob을 반환하는 tool은 해당 내용을 모두 다음 model 호출에 넣습니다. 같은 실행에서 이후의 모든 호출에도 해당 내용이 계속 포함됩니다.
• agent에 일정이 정말 필요한지 확인합니다. 5분마다 실행되는 작업은 하루에 288번 실행됩니다. 한 번 실행하는 비용이 얼마이든 그 값을 곱해야 합니다.

반복해서 수정하는 동안 workflow를 비활성화합니다. 활성화된 workflow와 Schedule Trigger는 n8n이 저장한 버전을 기준으로 계속 실행됩니다. 이 버전이 화면에 표시된 버전과 항상 일치하지는 않습니다.

FAQ

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

AI Agent 노드에는 chat model 하위 노드와 최소 1개의 tool 하위 노드가 필요합니다. model은 있지만 tool이 없는 노드는 API 호출을 수행하기 전에 실패합니다. 간단한 tool이라도 1개 연결한 다음 다시 실행합니다.

Agent가 응답하지만 내 tool을 호출하지 않습니다. 무엇이 문제입니까?

대부분은 tool의 Description 필드가 문제입니다. model은 해당 설명을 읽고 사용할 tool을 선택합니다. 따라서 "HTTP Request"와 같은 설명만으로는 tool을 언제 적용해야 하는지 알 수 없습니다. 어떤 데이터가 반환되고 어떤 상황에서 유용한지 설명하도록 내용을 다시 작성합니다. 그런 다음 Agent가 응답하기 전에 해당 tool을 호출하도록 System Message에 한 줄을 추가합니다.

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

model이 수행할 단계 수를 선택하기 때문입니다. 각 반복에서는 이전 tool 출력이 포함된 현재까지의 전체 대화를 다시 전송합니다. 따라서 4회 반복하는 실행은 단일 호출 비용의 4배보다 훨씬 더 많은 비용이 발생할 수 있습니다. Max Iterations는 반복 횟수의 상한이며, Return Intermediate Steps를 사용하면 특정 실행에서 실제로 사용한 단계 수를 확인할 수 있습니다.

Editor에서는 memory가 작동하지만 production에서는 작동하지 않습니다. 무엇이 변경되었습니까?

인스턴스가 queue mode로 실행되는지 확인합니다. Simple Memory는 workflow 자체의 execution data에 기록한 이력을 저장합니다. 이 데이터는 별도의 worker process로 전달될 때 유지되지 않으므로 실행 중인 production workflow에서 이력이 손실됩니다. 모든 worker가 공유하는 database에 이력을 보관하는 Postgres Chat Memory 하위 노드로 교체합니다.