에이전트 구축 및 관리
n8n v2.47요약
에이전트는 n8n에서 구축하는 자율 어시스턴트입니다. 에이전트는 다음 환경에서 사용할 수 있습니다: 에이전트는 미리보기(Preview) 상태입니다. 에이전트는 Enterprise를 포함한 모든 플랜에서 기본으로 켜져 있습니다.
에이전트는 n8n에서 구축하는 자율 어시스턴트입니다. 각 에이전트에는 언어 모델, 지침, 그리고 도구, 스킬, 지식 베이스 접근과 같이 직접 설정하는 기능이 있습니다. 에이전트는 프로젝트 내에서 워크플로와 나란히 일급 아티팩트로 존재합니다. 작업이 고정된 워크플로로 처리하기에는 너무 개방적이고, 요청을 추론하고, 적절한 도구를 선택하고, 응답에 맞게 적응할 수 있는 어시스턴트가 필요할 때 에이전트를 사용하세요.
기능 제공 여부
에이전트는 다음 환경에서 사용할 수 있습니다:
- n8n Cloud: 모든 플랜
- 셀프 호스팅: n8n 2.32.3부터 모든 플랜. 설정 방법은 셀프 호스팅을 참고하세요.
미리보기 상태
에이전트는 미리보기(Preview) 상태입니다. 실수를 할 수 있으며, 기능이 개발되는 동안 동작이 변경될 수 있습니다. 셀프 호스팅에서는 지식 베이스도 미리보기 상태입니다.
에이전트 활성화 또는 비활성화#
에이전트는 Enterprise를 포함한 모든 플랜에서 기본으로 켜져 있습니다. 인스턴스 소유자와 관리자는 인스턴스 전체에 대해 이 설정을 변경할 수 있습니다:
- Settings > Agents를 엽니다.
- Enable Agents를 켜거나 끕니다.
n8n은 재시작과 라이선스 변경 이후에도 선택한 값을 유지합니다. 이 설정은 n8n Assistant 설정과 별개입니다.
에이전트를 끄면:
- 사용자가 에이전트를 만들 수 없습니다. 미리보기, 채팅, 일정, 채널, MCP, 평가, Message an Agent 노드에서 새 실행을 시작할 수 없습니다.
- 승인을 기다리는 실행을 포함해, 진행 중인 실행은 끝까지 완료될 수 있습니다.
- n8n은 이후 실행을 위해 대기 중인 메시지를 취소합니다. 에이전트를 다시 활성화해도 이 메시지는 실행되지 않습니다.
- n8n은 저장된 에이전트와 세션 기록을 유지합니다. 에이전트를 다시 활성화하면 다시 접근할 수 있습니다.
일정은 저장된 상태로 유지됩니다. 에이전트를 다시 활성화하면 일정이 새 실행을 트리거할 수 있습니다. n8n은 에이전트가 꺼져 있는 동안 발생한 일정 트리거를 다시 실행하지 않습니다.
이 설정은 AI Agent 워크플로 노드에 영향을 주지 않습니다.
공유 샌드박스 설정#
에이전트와 n8n Assistant는 같은 샌드박스 연결을 공유합니다. 변경 사항은 두 기능 모두에 적용됩니다. 두 기능 중 하나가 꺼져 있어도 연결을 설정할 수 있습니다.
셀프 호스팅 인스턴스에서는 인스턴스 소유자 또는 관리자가 연결을 설정할 수 있습니다:
- Settings > Agents를 엽니다.
- Shared sandbox 아래에서 Add sandbox를 선택합니다. 기존 연결을 편집하려면 Code sandbox 행을 선택합니다.
- 샌드박스 제공업체를 선택하고 연결 정보를 입력합니다.
- Save를 선택합니다. n8n은 저장하기 전에 연결을 확인합니다.
n8n Cloud는 샌드박스 연결을 직접 관리합니다. 환경 변수로 셀프 호스팅 연결을 설정한 경우, 페이지에 편집 컨트롤 없이 Found in server configuration이 표시됩니다. 해당 연결이 설정되어 있지만 샌드박스가 꺼져 있다면 Enable sandbox를 선택합니다.
환경 변수와 모듈 요구 사항은 셀프 호스팅 n8n에서 에이전트 활성화를 참고하세요.
동영상: 에이전트가 워크플로 및 AI와 어우러지는 방식#
에이전트, 고정된 워크플로, 특정 단계에 AI를 사용하는 워크플로는 각각 적합한 작업의 종류가 다릅니다. 세 가지를 비교하고, 프로덕션 수준의 시스템에서 어떻게 함께 동작하는지 확인해 보세요.
에이전트로 구축할 수 있는 것#
업로드한 파일과 연결된 서비스를 사용해 질문에 답하고, Slack, Google Sheets, Linear와 같은 도구에서 작업을 수행하고, 더 큰 작업을 완료하기 위해 워크플로를 트리거하거나 조율하는 데 에이전트를 사용하세요. 에이전트는 다른 에이전트에 위임하거나 일정에 따라 실행될 수도 있습니다. 아래의 서브 에이전트와 일정을 참고하세요.
에이전트 작동 방식#
에이전트는 추론 루프를 실행합니다. 메시지를 보내거나 일정이 트리거하면, 에이전트는 지침을 읽고 요청을 살펴본 다음 다음에 무엇을 할지 결정합니다: 도구 호출, 지식 베이스 검색, 다른 에이전트로 넘기기, 또는 후속 질문하기. 최종 응답을 만들어낼 때까지 이 루프를 반복합니다.
에이전트와의 각 대화는 세션이며, n8n은 이를 저장하여 나중에 재개할 수 있게 하고 에이전트가 메모리를 통해 컨텍스트를 기억할 수 있게 합니다.
에이전트의 구성 요소#
에이전트 빌더에서 에이전트의 다음 구성 요소를 설정합니다:
| 구성 요소 | 하는 일 |
|---|---|
| 모델(Model) | 추론하고 응답을 생성하는 언어 모델입니다. 에이전트를 설정할 때 제공업체와 모델을 선택합니다. |
| 지침(Instructions) | 에이전트의 역할, 어조, 제약 조건을 설명하는 시스템 프롬프트입니다. |
| 도구(Tools) | 에이전트가 수행할 수 있는 작업입니다: 워크플로, 커스텀 코드, n8n 기본 통합, MCP 서버. |
| 웹 검색(Web search) | 에이전트가 모델의 네이티브 검색 도구 또는 대체 서비스를 사용해 최신 정보를 웹에서 검색할 수 있게 합니다. |
| 스킬(Skills) | 특정 작업에 필요한 도구와 지침을 함께 묶은 재사용 가능한 동작 번들입니다. |
| 채널(Channels) | Slack, Telegram, Linear와 같이 사람들이 에이전트에 접근할 수 있는 곳입니다. |
| 일정(Schedules) | 게시된 이후 에이전트가 반복적으로 실행하는 작업입니다. |
| 서브 에이전트(Sub-agents) | 이 에이전트가 작업을 위임할 수 있는 다른 게시된 에이전트입니다. |
| 지식 베이스(Knowledge base) | 에이전트가 컨텍스트를 위해 검색하고 읽을 수 있는 파일입니다(n8n Cloud, 또는 샌드박스를 설정한 셀프 호스팅의 미리보기). |
| 메모리(Memory) | 세션 메모리는 현재 대화를 유지합니다. 에피소드 메모리는 이전 세션의 컨텍스트를 기억합니다. |
모델, 지침, 도구, 스킬, 지식, 메모리, 서브 에이전트는 에이전트를 구축하는 동안 설정합니다. 채널과 일정은 게시해야 적용됩니다.
초안 버전과 게시된 버전#
모든 에이전트에는 초안 버전이 있으며, 준비가 되면 게시된 버전이 생깁니다. 초안은 변경 사항을 만드는 곳이며, n8n이 자동으로 저장합니다. 게시된 버전은 누군가 에이전트와 채팅하거나, 채널이 트리거하거나, 일정이 실행될 때 동작하는 버전입니다.
게시는 초안의 스냅샷을 만들기 때문에, 편집하는 동안 실행 중인 에이전트는 변경되지 않습니다. 게시할 때마다 게시 기록에 버전이 추가되며, 언제든지 이전 버전으로 복원하거나 되돌릴 수 있습니다.
에이전트 구축하기#
에이전트 빌더에서 에이전트를 구축합니다. 이름과 모델부터 시작해 지침을 추가한 다음, 에이전트에 필요한 도구, 스킬, 지식, 메모리, 서브 에이전트를 연결합니다. n8n은 변경 사항을 초안에 자동으로 저장합니다.
에이전트 생성하기#
- 왼쪽 메뉴에서 프로젝트를 선택합니다. 그런 다음 Agents 탭으로 이동합니다.
- Create Agent를 선택합니다. n8n이 빈 초안으로 에이전트 빌더를 엽니다.
- Agent 탭에서 에이전트의 이름을 입력합니다. 아이콘 선택기를 사용해 아이콘을 변경합니다.
n8n Assistant 사용하기
에이전트가 해야 할 일을 n8n Assistant에게 설명하세요. n8n Assistant가 추가할 지침, 도구, 스킬을 제안합니다. 진행하면서 에이전트 빌더에서 제안을 다듬으세요.
모델 선택하기#
Agent 탭에서 Model 필드를 열고 제공업체와 모델을 선택합니다. 제공업체에 자격 증명이 필요하다면 안내에 따라 추가하세요.
지침 작성하기#
Instructions 필드에 에이전트의 역할, 어조와 응답 형식, 해야 할 일과 하지 말아야 할 일, 일반적인 작업에서 선호해야 할 도구나 스킬을 설명합니다.
지침은 구체적으로 작성하세요. 에이전트가 예상대로 동작하지 않는다면, 도구를 더 추가하기 전에 먼저 지침을 다듬으세요.
도구 추가하기#
Tools 섹션에서 Add tool을 선택하고, 기본 도구(Slack이나 Google Sheets와 같은 n8n 통합), 동일한 프로젝트의 워크플로, JSON 스키마로 정의된 커스텀 도구, MCP 서버를 통한 외부 도구 중에서 선택합니다.
에이전트는 지침과 작업을 바탕으로 어떤 도구를 사용할지 결정하며, 도구를 추가할 때 연결한 자격 증명을 사용합니다. 민감한 도구의 경우, 에이전트가 실행하기 전에 승인을 요구하도록 설정할 수 있습니다. 도구 호출 승인하기를 참고하세요.
웹 검색 활성화하기#
Capabilities 섹션에서 Web search를 활성화하면, 에이전트가 별도의 도구를 추가하지 않고도 가격, 문서, 뉴스와 같은 최신 정보를 조회할 수 있습니다.
- 선택한 모델이 자체 네이티브 웹 검색 도구를 제공하는 경우, 에이전트가 이를 직접 사용합니다.
- 제공하지 않는 경우, 대체 수단으로 Brave Search 또는 셀프 호스팅 SearXNG 인스턴스를 선택하고, 선택한 항목의 자격 증명을 추가합니다.
스킬로 기능 묶기#
스킬은 특정 작업에 필요한 지침과 도구를 함께 묶습니다. 에이전트가 각기 다른 단계를 가진 여러 개별 작업을 처리해야 할 때 스킬을 사용하세요.
스킬을 추가하려면:
- Skills 섹션을 열고 Add skill을 선택합니다.
- 스킬에 이름과 짧은 설명을 부여합니다.
- 스킬이 사용할 수 있는 도구를 선택합니다.
- 에이전트가 스킬을 실행할 때 따라야 할 지침을 작성합니다.
에이전트는 설명과 현재 요청을 바탕으로 적절한 스킬을 선택합니다.
지식 업로드하기#
Knowledge 탭에서 에이전트가 검색하고 읽을 수 있는 파일을 추가합니다. 지원되는 파일 형식: csv, pdf, markdown, txt.
미리보기 상태
셀프 호스팅에서 지식 베이스는 미리보기 상태이며 향후 릴리즈에서 변경될 수 있습니다.
파일을 업로드하면, 에이전트는 질문에 답하고 컨텍스트를 가져오기 위해 지식 베이스를 검색할 수 있습니다.
메모리 설정하기#
세션 메모리는 현재 대화의 컨텍스트를 유지합니다. 기본으로 켜져 있으며 별도의 설정이 필요 없습니다.
에이전트가 이전 세션의 컨텍스트를 기억하게 하려면:
- Memory 탭을 엽니다.
- Episodic memory를 활성화합니다.
에피소드 메모리는 메모리를 저장하고 조회하기 위해 OpenAI 자격 증명이 필요합니다.
서브 에이전트 추가하기#
서브 에이전트를 사용하면 이 에이전트가 다른 게시된 에이전트에게 작업을 넘길 수 있습니다. 작업에 명확하게 분리된 부분이 있고 전문화된 에이전트가 각 부분을 더 잘 처리할 수 있을 때 서브 에이전트를 사용하세요.
- 기능 목록에서 Agents 섹션을 엽니다.
- Add agent를 선택하고 프로젝트에서 게시된 에이전트를 선택합니다.
- When should this agent be used? 아래에 이 서브 에이전트를 호출해야 하는 상황을 설명합니다.
에이전트 설정에서 병렬로 실행되는 서브 에이전트의 최대 개수를 설정할 수 있습니다.
에이전트 미리보기#
게시하지 않고 에이전트를 테스트하려면 헤더에서 Preview를 선택합니다. n8n이 현재 초안으로 채팅 세션을 시작합니다. 게시하기 전에 미리보기를 사용해 에이전트의 동작, 도구 선택, 응답을 확인하세요.
Preview가 비활성화되어 있다면 초안에 설정 오류가 있는 것입니다. n8n이 해결해야 할 항목을 나열합니다.
에이전트 게시하기#
에이전트를 게시하면 사용자, 채널, 일정에서 사용할 수 있게 됩니다. 게시된 버전만 프로덕션에서 실행되므로, 사람들이 보는 내용이나 일정이 사용하는 내용을 바꾸지 않고도 초안을 계속 편집할 수 있습니다.
- 에이전트 빌더에서 에이전트를 엽니다.
- 오류를 확인합니다. Publish가 비활성화되어 있다면 n8n이 해결해야 할 설정 항목을 나열합니다.
- Publish를 선택합니다.
게시는 현재 초안의 스냅샷을 만들어 이를 활성 버전으로 표시합니다.
게시된 에이전트 업데이트하기#
에이전트가 게시되면 편집 내용은 초안에 반영됩니다. 게시된 버전은 다시 게시할 때까지 계속 실행됩니다.
변경 사항을 배포하려면:
- 에이전트 빌더에서 초안을 편집합니다. n8n이 변경 사항을 자동으로 저장합니다.
- Preview로 변경 사항을 테스트합니다.
- 새 버전을 릴리즈하려면 Publish를 다시 선택합니다.
저장하지 않은 변경 사항을 버리고 게시된 버전과 일치시키려면, 게시 메뉴에서 Revert changes를 선택하세요.
에이전트 게시 취소하기#
프로젝트에 초안을 유지하면서 에이전트를 오프라인으로 전환하려면, 게시 메뉴에서 Unpublish를 선택합니다. 다시 게시할 때까지 사용자, 채널, 일정은 더 이상 에이전트를 실행할 수 없습니다. 초안은 계속 편집할 수 있습니다.
게시된 에이전트와 채팅하기#
에이전트 빌더의 채팅 패널을 사용하면 에이전트와 직접 대화할 수 있습니다.
- 채팅 패널을 엽니다.
- 메시지를 입력하고 전송합니다. 에이전트가 세션을 시작하고 응답합니다.
- 과거 대화를 검토하거나 이어가려면, 세션 기록을 열고 세션을 선택합니다.
n8n은 각 대화를 세션으로 저장합니다. 주고받은 메시지, 에이전트가 사용한 도구, 대기 중인 승인을 포함해 Sessions 탭에서 세션을 검토하세요.
도구 호출 승인하기#
민감한 도구의 경우, 에이전트는 도구를 실행하기 전에 일시 중지하고 승인을 요청합니다. 채팅에서 도구를 실행하려면 Approve를, 취소하려면 Reject를 선택하세요. 에이전트는 여러분의 결정을 반영해 중단했던 지점부터 계속 진행합니다.
다른 곳에서 에이전트에 접근하기#
채널을 연결하면 사람들이 에이전트 빌더 채팅 외부에서도 에이전트에 접근할 수 있습니다.
사용 가능한 채널:
- Slack
- Telegram
- Linear
- Microsoft Teams: 에이전트를 Microsoft Teams에 연결하기를 참고하세요.
에이전트에서 Channels 섹션을 열고 원하는 채널의 설정 방법을 따르세요. 각 채널은 고유한 연결 및 권한 모델을 갖습니다.
MCP를 통한 에이전트 관리#
Claude Desktop이나 Claude Code와 같은 MCP 클라이언트에서 n8n의 인스턴스 수준 MCP 서버를 사용해 에이전트를 구축하고 관리할 수도 있습니다. 이 방식은 MCP 서버가 이미 제공하는 워크플로 도구와 함께, 에이전트를 검색, 생성, 설정하는 도구를 노출합니다.
기존 MCP 클라이언트 재연결
에이전트를 사용할 수 있게 되기 전에 MCP 클라이언트를 n8n 인스턴스에 연결했다면, 에이전트 관리 도구에 접근하기 위해 클라이언트를 다시 연결해야 합니다. Settings > Instance-level MCP로 이동해 클라이언트를 다시 연결하면 MCP를 통해 에이전트를 관리하는 새 권한을 받을 수 있습니다.
일정에 따라 에이전트 실행하기#
일정을 사용하면 에이전트가 반복적으로 자체적으로 실행됩니다. Schedules 섹션에서 일정을 추가하고, 에이전트가 완료해야 할 작업을 설명한 다음, 빈도를 선택합니다:
- 매시간(Hourly)
- 매일(Daily)
- 매주(Weekly)
- 매월(Monthly)
- 커스텀 cron(Custom cron)
일정은 에이전트의 게시된 버전에 대해서만 실행됩니다. n8n은 각 일정에 대해 다음 실행 시각, 마지막 실행 시각, 마지막 실행 결과를 표시합니다.
워크플로에서 에이전트 사용하기#
워크플로 내에서 에이전트를 두 가지 방식으로 사용할 수 있습니다:
- 에이전트를 인라인으로 생성: 워크플로에 노드로 에이전트를 직접 추가합니다. 워크플로 에디터를 벗어나지 않고 에이전트를 구축하고 설정할 수 있습니다.
- 기존 에이전트에게 메시지 보내기: 워크플로에서 이미 생성된 에이전트에게 메시지를 보냅니다. 게시된 에이전트에 접근하고 그 기능을 자동화에 통합할 수 있습니다.
Message an Agent 노드#
두 방식 모두 Message an Agent 노드를 사용합니다. 메시지를 보낼 에이전트를 선택하고 보낼 메시지를 작성합니다. 에이전트는 자체 추론 루프를 실행하고, 자체 도구와 스킬을 호출하며, 이후 노드에서 사용할 수 있는 응답을 반환합니다.
이 노드는 다음 작업도 할 수 있습니다:
- 연결된 Chat 및 Webhook 트리거를 통해, 에이전트가 응답을 생성하는 대로 응답을 스트리밍합니다.
- 세션을 재사용하여 에이전트가 이전 메시지를 기억하게 합니다. 세션을 재사용하지 않으면 실행할 때마다 새 대화가 시작됩니다.
- 응답을 JSON 스키마로 제한하여, 이후 노드가 예측 가능한 필드를 받게 합니다.
각 메시지는 다른 워크플로 실행과 마찬가지로 하나의 실행으로 계산됩니다.
에이전트가 다른 에이전트에게 작업을 넘기게 하려면, Message an Agent Tool을 AI Agent 노드의 Tool 입력에 연결합니다.
셀프 호스팅#
셀프 호스팅 n8n에서 에이전트를 설정하는 방법은 두 가지가 있습니다:
- 수동으로 구축: 에이전트는 기본으로 켜져 있습니다. 모델을 직접 선택하고, 지침을 작성하고, 도구와 스킬을 직접 연결합니다. 인스턴스 소유자 또는 관리자는 Settings > Agents에서 에이전트를 켜거나 끌 수 있습니다.
- 전체 경험: AI 지원 구축을 위해 n8n Assistant(
instance-ai)도 설정합니다. 에이전트를 설명하면 n8n이 이를 스캐폴딩합니다. 지식 베이스에는 설정된 샌드박스가 필요하며, 채널을 연결하려면 공개WEBHOOK_URL이 필요합니다.
기능 제공 여부
에이전트는 n8n 2.32.3부터 모든 셀프 호스팅 플랜에서 사용할 수 있습니다.
큐 모드는 아직 에이전트에서 지원되지 않으며, 채널(예: Telegram) 연결이 실패할 수 있습니다. 당분간 에이전트는 일반 모드에서 실행하세요.
환경 변수와 설정 단계는 에이전트 활성화를 참고하세요.
에이전트 실행과 가격#
에이전트와의 한 턴은 하나의 실행으로 계산됩니다. 턴은 메시지를 보내고 에이전트가 응답을 생성하는 단일 교환입니다.
에이전트는 워크플로와 동일한 실행 할당량을 공유합니다. 에이전트와 워크플로의 실행은 플랜의 동일한 총량에 포함됩니다.