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

n8n AI 에이전트의 정의와 체인과의 차이점

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

체인은 이와 반대로 작동합니다. Basic LLM Chain에서는 사용자가 단계를 결정하고 모델은 텍스트만 채워 넣습니다. 반면 에이전트에서는 모델이 단계를 결정하므로, 동일한 질문이라도 오늘 한 번의 모델 호출로 끝날 수 있고 내일은 아홉 번의 호출이 필요할 수도 있습니다. 이 단 하나의 차이가 본 가이드의 모든 설정을 결정짓습니다. 만약 이 루프 구조가 n8n의 기능으로서가 아니라 개념적으로 생소하다면, 노드를 조합하기 전에 직접 코드로 한 번 작성해 보는 것을 권장합니다. 노드는 이 가이드의 나머지 부분에서 다룰 핵심 논리 과정을 숨기기 때문입니다.

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

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

docker compose exec n8n n8n --version

버전 1.82.0부터 agent-type 설정은 더 이상 사용되지 않으며 Tools Agent가 이를 대체합니다. 기존 v1 노드에는 여전히 해당 설정이 남아 있으나, n8n 공식 문서에 따르면 해당 노드 버전은 n8n 3.0에서 제거될 예정입니다.

1단계: 트리거 선택

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

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

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

2단계: 모델 자격 증명

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

Claude Console(platform.claude.com)의 Settings 내 API keys 메뉴에서 자격 증명을 생성합니다. 키는 한 번만 표시됩니다. 키를 생성할 때 만료일을 선택해야 하는데, 무인 에이전트는 키가 만료되면 작동을 멈추므로 해당 날짜를 확인할 수 있는 곳에 기록해 두어야 합니다. 무인 에이전트의 경우, 별도의 워크스페이스 헤더가 필요 없도록 워크스페이스 범위로 제한된 서비스 계정 키를 사용하십시오.

API 사용량은 토큰 단위로 과금되며, 결제 방식은 2026년 10월 31일 기준 Claude 플랜에 따라 다릅니다. Max, Ultra, Team 플랜은 월간 API 크레딧을 포함합니다. Max는 $100, Ultra는 $200, Team은 최대 $500까지 통합 제공됩니다. Max나 Ultra는 Settings > Billing에서, Team은 Organization settings > Billing에서 Console 조직을 플랜과 연결하여 크레딧을 수령할 수 있으며, Console에 별도의 결제 수단을 추가할 필요는 없습니다. 신규 구독자는 플랜 가입 7일 후부터 수령할 수 있으며, 사용하지 않은 크레딧은 매 결제 주기 말 또는 연간 플랜의 경우 매월 소멸합니다. 포함된 크레딧이 소진되면 구매한 크레딧으로 요청이 계속 처리되며, 자동 충전 기능을 통해 추가 구매가 가능하고, 인보이스 발행 조직은 초과 사용량에 대해 청구됩니다. 선불제 조직의 크레딧이 소진되면 요청이 중단됩니다. API 사용료는 Claude 플랜 요금에 합산되지 않습니다. Free, Pro, Enterprise 플랜은 월간 API 크레딧을 제공하지 않으므로, 해당 플랜에서는 구독료와 별도로 API 비용이 청구됩니다.

모델은 회사 단위가 아닌 에이전트 단위로 선택하십시오. 정보를 조회하고 보고하는 단순한 도구 에이전트는 Haiku 모델로도 충분합니다. 2026년 10월 12일 기준 현재 버전인 Haiku 5.5는 입력 토큰 100만 개당 $0.10, 출력 토큰 100만 개당 $0.50입니다. 프롬프트가 100,000 토큰을 초과하는 요청의 경우 각각 $0.50와 $2.50로 비용이 상승하는데, 긴 메모리 윈도우나 방대한 도구 결과값을 사용하면 이 기준을 넘길 수 있습니다. 에이전트가 여러 도구를 사용하고 이를 조합해 계획을 세워야 한다면 Sonnet으로 전환하십시오. 잘못된 도구를 4번 호출하는 저렴한 모델은 올바른 도구를 1번 호출하는 비싼 모델보다 더 많은 비용을 발생시킵니다. 이와 같은 실패를 방지해야 합니다.

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

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

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

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

• Connected Chat Trigger Node는 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단계: 에이전트에 도구 하나 연결하기

n8n 문서에 따르면 AI Agent 노드에는 최소 하나의 도구 하위 노드를 연결해야 합니다. 현재 노드 코드(버전 3.1)는 채팅 모델이 없으면 실행을 거부하지만, 도구 없이 실행하는 것은 비용만 많이 드는 체인에 불과하므로 처음부터 도구 하나를 제대로 설정하는 것이 학습에 더 효과적입니다.

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라고 부르라"고 지시하는 것이며, 모델은 대화 내용, 입력 데이터, 다른 도구의 결과에서 해당 값을 찾습니다. 채팅 워크플로우에서는 모델이 사용자에게 직접 물어볼 수도 있습니다.

웹 검색은 일반적으로 두 번째 도구로 사용됩니다. 이 역시 또 다른 HTTP 엔드포인트이므로, 유료 검색 API 대신 직접 구축한 SearXNG 인스턴스를 연결할 수 있습니다. 단, 검색 결과로 가져온 모든 페이지는 신뢰할 수 없는 텍스트로 간주하고 프롬프트에 포함해야 합니다.

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

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

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

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

n8n이 큐 모드(queue mode)로 실행되는 활성 운영 환경에서는 Simple Memory가 작동하지 않습니다. 이 노드는 워크플로우 및 세션 ID를 키로 하는 프로세스 로컬 싱글톤 Map에 기록을 저장하는데, 워커(worker)들은 이 메모리를 공유하지 않기 때문입니다. 큐 모드 인스턴스에서는 대신 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 뒤에 있는 에이전트에는 사람이 개입하며, 답변이 잘못되었다고 판단되면 사람이 이를 중단시킵니다. 반면 Schedule Trigger 뒤에 있는 에이전트는 아무도 지켜보지 않습니다. 여기서 주의해야 할 점은 라이선스 비용이 아니라 모델 사용 비용입니다. 에이전트, 도구, 메모리 노드는 모두 무료 자체 호스팅 버전에서 작동하며, 유료 키가 필요한 기능은 대부분 팀 및 거버넌스 관련 기능이기 때문입니다. 자세한 내용은 상시 가동 VPS에서의 AI 에이전트 비용 제어를 참조하십시오. 다음 네 가지 설정이 비용 제어의 핵심입니다.

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

워크플로우를 반복 수정하는 동안에는 게시를 취소하거나, 최소한 현재 라이브 상태인 버전을 기억하십시오. Schedule Trigger가 포함된 게시된 워크플로우는 화면에 있는 초안이 아니라 마지막으로 게시한 버전을 계속 실행합니다. n8n은 다시 게시하기 전까지 편집 내용을 초안 상태로 유지하기 때문입니다.

FAQ

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

먼저 커넥터를 확인하십시오. AI Agent 노드에는 반드시 Chat Model 하위 노드가 필요하며, 이 노드가 없으면 API 호출을 시도하기 전에 "Please connect a model to the Chat Model input"이라는 메시지와 함께 실행이 중단됩니다. n8n 문서에 따르면 최소 하나의 Tool 하위 노드도 필수 항목입니다. 모델이 연결되어 있는데도 노드가 실행되지 않는다면, 간단한 도구라도 하나 연결한 뒤 다시 실행해 보십시오.

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

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

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

모델이 수행하는 단계(step) 수가 달라지기 때문입니다. 각 반복마다 이전 도구 출력 결과를 포함한 전체 대화 내용을 다시 전송하므로, 4번 반복한 실행은 4번의 호출에 걸친 모든 입력 및 출력 토큰에 대해 비용이 청구됩니다. Max Iterations는 반복 횟수의 상한선이며, Return Intermediate Steps를 통해 실제 실행에서 몇 단계가 사용되었는지 확인할 수 있습니다.

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

인스턴스가 큐 모드(queue mode)로 실행 중인지 확인하십시오. Simple Memory는 워크플로 및 세션 ID를 키로 사용하는 프로세스 로컬 싱글톤 Map에 기록을 저장하는데, 별도의 워커 프로세스들은 이 메모리를 공유하지 않습니다. 모든 워커가 공유하는 데이터베이스에 기록을 저장하는 Postgres Chat Memory 하위 노드로 교체하십시오.