에이전트
사용자와 대화하며 작업을 수행하는 AI 에이전트를 제공하는 노드입니다.
설명
에이전트 노드는 LLM을 기반으로 사용자와 대화하며 다양한 작업을 수행하는 AI 에이전트를 제공합니다. 사용자의 요청을 이해하고, 목표를 달성하기 위해 필요한 도구를 스스로 판단해 호출합니다.
에이전트가 사용할 수 있는 도구:
- 웹 검색 · 크롤링: Tavily 검색, Jina 웹 크롤링으로 실시간 정보를 조회합니다.
- HTTP 요청: 사용자가 준 링크나 공개 API를 직접 호출하고 응답을 읽습니다. (HTTP 요청 참고)
- 캔버스 조작: 노드 생성·수정, 엣지(연결선) 생성 등 캔버스를 직접 편집합니다.
- 문서 작성·수정: 보고서 등을 PDF·DOCX·XLSX 등의 파일로 저장하고, 저장한 문서를 대화로 고칩니다. (문서 작성과 수정 참고)
또한 이미지·문서·코드 파일을 첨부하여 함께 질문할 수 있습니다. (파일 첨부 참고)
에이전트의 작업을 캔버스 워크플로우로 확장하려면 에이전트 메시지 가로채기와 에이전트로 전달 노드를 함께 사용합니다.
포트 구성
입력 포트
- 데이터셋 (선택, 여러 개 가능): 에이전트가 참고할 데이터셋. 포트 편집으로 데이터셋 입력 포트를 더 추가할 수 있습니다
- 시스템 프롬프트 (선택): 에이전트의 행동 방침을 외부 노드에서 주입할 때 사용
- 도구 목록 (선택): 에이전트 도구 목록 노드를 연결해 에이전트가 쓸 도구를 제한하거나 MCP 서버 도구를 추가합니다. 연결하지 않으면 기본 도구 전체를 사용합니다
출력 포트
- 데이터셋: 채팅 내역이 포함된 데이터셋
속성
모델 선택
사용할 AI 언어 모델을 선택합니다. 각 모델마다 성능과 비용이 다릅니다.
이미지 분석은 이를 지원하는 모델에서만 동작합니다. 대부분의 최신 모델(GPT-4o, Gemini, Claude 등)은 이미지를 지원하지만, 일부 텍스트 전용 모델(예: 온프레미스 환경의 gpt-oss, EXAONE)은 지원하지 않습니다. 지원하지 않는 모델을 선택하면 이미지 첨부 시 안내 메시지가 표시됩니다.
데이터셋을 연결하거나 파일을 첨부했는데도 에이전트가 문서 내용을 반영하지 않고 답할 때가 있습니다. 에이전트는 연결된 문서를 읽을지 말지 스스로 판단하는데, 도구 호출 성향이 약한 모델은 "굳이 안 봐도 되겠다"고 판단해 자기 지식으로만 답하기 때문입니다.
GPT는 5 버전부터 도구 호출(tool calling) 성향이 강하게 학습돼 있어, 별도 프롬프팅 없이도 연결된 문서를 알아서 찾아 읽습니다. 문서 기반 답변을 안정적으로 받고 싶다면 모델을 GPT-5 계열(예: gpt-5-nano) 로 설정하는 것을 권장합니다. 저비용 모델이지만 이 용도에는 충분합니다.
에이전트는 응답 한 번에 LLM을 여러 번 호출할 수 있고, 모든 호출에서 사용한 토큰만큼 크레딧이 소모됩니다. 도구(문서 검색·웹 검색 등)를 사용하면 그 결과를 읽어 답하기 위해 LLM이 추가로 호출되므로, 도구를 많이 쓸수록 크레딧도 늘어납니다. 소모량은 선택한 모델에 따라 달라집니다. 이미지 생성을 요청하면 이미지의 크기, 품질, 생성 장수에 따라 크레딧이 추가로 소모됩니다. 자세한 계산 방식은 노드별 크레딧 소모량을 참고하세요.
인사말
에이전트가 대화를 시작할 때 표시할 인사말을 입력합니다. 사용자가 대화를 시작하면 이 인사말이 먼저 표시됩니다.
예시 질문
사용자에게 제안할 예시 질문을 추가할 수 있습니다. 대화를 시작할 때 함께 표시되어, 사용자가 쉽게 대화를 시작하도록 돕습니다.
사용자 정의 시스템 프롬프트
사용자 정의 시스템 프롬프트 사용을 켜면 시스템 프롬프트 입력란이 나타납니다. 여기에 에이전트의 역할·말투·행동 방침을 정의하면, 모든 대화에 일관되게 적용됩니다.
메시지 가로채기 노드 선택
에이전트 메시지를 가로채서 처리할 노드를 선택합니다. 에이전트 메시지 가로채기 노드를 선택하면 해당 노드가 에이전트의 메시지를 가로채 워크플로우로 전달합니다.
문서 저장 노드 지정
켜면 저장할 문서 노드 선택이 나타납니다. 캔버스에서 에이전트가 대화 내용이나 생성한 텍스트를 문서로 저장할 때, 여기서 고른 문서 데이터 노드에 추가합니다. 지정하지 않으면 저장할 때마다 캔버스에 새 문서 데이터 노드를 만듭니다.
배포한 웹 앱에서 실행한 에이전트는 이 설정과 관계없이 새 문서를 대화 첨부로 저장합니다. 원본 캔버스에 문서 데이터·문서 뷰어 노드가 추가되지 않으며, 사용자는 답변의 다운로드 카드로 문서를 받습니다.
대화 목록 표시
노드 좌측의 채팅방 목록 사이드바 표시 여부를 설정합니다.
채팅 색상
채팅 화면의 색을 노드마다 다르게 지정할 수 있습니다. 값을 바꾸지 않으면 기본 색이 적용됩니다.
- 글자 색: 대화 내용, 상단 모델 이름, 채팅방 목록의 글자 색
- 내 메시지 말풍선 색: 사용자가 보낸 메시지의 말풍선 배경 색
- 내 메시지 글자 색: 사용자가 보낸 메시지의 글자 색
- 강조 색: 전송 버튼, 링크, 에이전트 답변 왼쪽의 강조 선 색
- 대화 목록 항목 색: 채팅방 목록에서 선택 중이거나 마우스를 올린 채팅방의 배경 색
포트 편집
데이터셋 입력 포트를 추가하거나 삭제하고, 이름과 순서를 바꿀 수 있습니다. 데이터셋을 여러 개 연결하면 에이전트가 데이터셋 도구로 조회할 때 포트 이름이 데이터셋 이름으로 표시되므로, 포트 이름을 내용에 맞게 붙여 두면 에이전트가 어느 데이터를 볼지 판단하기 쉬워집니다.
채팅방 관리
에이전트 노드는 여러 개의 대화를 채팅방 단위로 관리할 수 있습니다. 노드 좌측 사이드바에서 채팅방 목록을 확인할 수 있습니다.
- 새 채팅: 새로운 대화를 시작합니다
- 채팅방 전환: 목록에서 다른 채팅방을 클릭하여 이전 대화로 돌아갈 수 있습니다
- 이름 변경: 채팅방 이름을 클릭하여 수정할 수 있습니다
- 삭제: 채팅방을 삭제할 수 있습니다
노드의 너비가 좁을 경우 채팅방 사이드바가 자동으로 숨겨집니다. 노드를 넓히면 다시 표시됩니다.
파일 첨부
입력창의 첨부 버튼으로 파일을 올려 에이전트에게 함께 질문할 수 있습니다. 지원 형식은 다음과 같습니다.
| 종류 | 지원 형식 |
|---|---|
| 이미지 | PNG, JPG, GIF, WebP, BMP, SVG |
| 문서 | PDF, DOC, DOCX, XLSX, PPT, PPTX, HWP, HWPX, CSV, TSV, ODS |
| 코드/텍스트 | PY, JS, TS, JSON, MD, TXT, HTML, CSS, JAVA, XML, YAML 등 |
이미지는 캡처 후 입력창에 바로 붙여넣기(Ctrl+V)할 수 있습니다.
DOC, PPT 파일은 서버에서 DOCX, PPTX로 변환한 뒤 내용을 읽습니다. 텍스트가 없는 스캔 문서는 내용을 읽을 수 없다는 안내가 에이전트에 전달됩니다.
문서 작성과 수정
에이전트에게 보고서·요약문 등을 파일로 만들어 달라고 요청하면, 에이전트가 문서를 작성해 저장합니다. 저장할 수 있는 형식은 PDF, DOCX, XLSX, MD, TXT, CSV, JSON입니다.
- 다운로드 카드: 저장한 문서는 답변 안에 다운로드 카드로 표시됩니다. 카드에서 파일을 바로 내려받을 수 있습니다
- 이어서 수정: "2장 표를 분기별로 나눠 줘"처럼 요청하면 에이전트가 같은 문서를 고쳐 다시 저장합니다. 에이전트가 저장한 문서만 고칠 수 있으며, 사용자가 업로드한 파일은 수정하지 않습니다
- 수정 위치 표시: PDF 문서를 고치면 문서 뷰어에서 바뀐 자리에 사각형과 "수정함" 라벨이 표시됩니다. 변경이 문서 대부분에 걸치거나 서식만 바뀐 경우에는 표시하지 않습니다
캔버스에서는 문서가 문서 데이터 노드에 저장됩니다. (문서 저장 노드 지정 참고)
에이전트 배포로 Telegram·MS Teams 등 메시징 채널에 배포한 에이전트는 파일을 답변으로 전달할 수 없어 문서를 저장하지 않습니다. 문서 작성을 요청하면 본문을 답변 텍스트로 작성합니다.
HTTP 요청
에이전트는 HTTP 요청 도구로 API를 직접 호출하고 받은 응답을 읽어 답합니다. 사용자가 링크를 주면 그 링크를 호출합니다. 링크가 없어도 필요하다고 판단하면 공개 API를 골라 호출합니다.
- 링크 호출: "https://... 이 링크 호출해서 결과 보여줘"처럼 요청하면 그 주소를 호출합니다
- AI Canvas API 호출: 워크플로우 API 배포나 데이터셋 API 배포로 만든 API를 호출해 결과를 대화로 가져옵니다
- 공개 API 조회: 날씨처럼 공개 API로 확인할 수 있는 정보는 링크 없이도 에이전트가 API를 찾아 호출합니다
요청 방식
GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS 메서드를 쓸 수 있고 헤더·쿼리 파라미터·본문(JSON 또는 텍스트)을 함께 보냅니다. 에이전트는 데이터를 바꾸는 요청(POST·PUT·PATCH·DELETE 등)을 사용자가 그 동작을 요청했을 때만 보내도록 안내받습니다.
API 키 전달
API 키가 필요하면 메시지에 키를 적거나, 키가 담긴 데이터셋을 에이전트에 연결합니다. 에이전트가 키를 읽어 헤더나 쿼리 파라미터에 넣습니다. AI Canvas의 워크플로우 API(API 키를 사용하도록 배포한 경우)와 데이터셋 API는 Authorization: Bearer <API 키> 헤더를 씁니다.
도구 실행 내역의 요청에서는 이름에 auth, token, key, secret, password 등이 들어간 헤더·쿼리 파라미터·본문 값을 ***로 가려 보여 줍니다.
키를 데이터셋에 넣어 연결하면, 에이전트가 데이터셋을 조회한 도구 실행 내역의 응답에는 데이터셋 내용이 그대로 보입니다. 배포한 웹 앱에서는 사용자도 이 내역을 볼 수 있습니다.
응답
- 본문 길이: 응답 본문은 앞 20,000자까지 읽습니다. 더 필요하면 에이전트가 최대 60,000자까지 늘려 읽고 넘는 부분은 잘립니다
- 오류 응답: 401, 404 같은 오류 응답도 본문을 받아 에이전트가 실패 원인을 설명합니다
- 웹 페이지와 PDF: HTML은 본문 텍스트로, PDF는 앞 50쪽의 텍스트로 바꿔 읽습니다
- 그 밖의 파일: 이미지·엑셀 같은 파일은 이름·형식·크기만 확인하고 내용은 읽지 못합니다
- 크기와 시간: 응답은 20MB까지 받습니다. 요청 시간은 기본 60초(최대 300초)입니다
기사나 블로그처럼 사람이 읽는 웹 페이지는 주로 웹 크롤링 도구로 읽습니다. HTTP 요청 도구는 API를 호출할 때 씁니다.
호출할 수 있는 주소
- 클라우드: 공개 인터넷 주소만 호출할 수 있습니다. 사내망이나 내부 주소(사설 IP 등)로 가는 요청은 막힙니다
- 온프레미스: 사내망 주소도 호출할 수 있습니다
- 리다이렉트: 응답이 다른 호스트로 리다이렉트되면, 처음 넣은 헤더(키 포함)와 쿠키는 넘어간 호스트로 보내지 않습니다
요청을 보낼지는 모델이 판단합니다. 삭제·수정 권한이 있는 API 키를 쓸 때는 권한을 필요한 범위로 제한한 키를 주세요.
도구 실행 내역
답변 중 에이전트가 호출한 도구는 대화창에 단계로 표시됩니다. 단계를 클릭하면 드로어에서 요청(도구에 넘긴 인자)과 응답(도구 실행 결과)을 나눠 볼 수 있어, 도구 호출이 실패했을 때 무엇을 시도했는지 확인할 수 있습니다.
응답 중단
에이전트가 답변을 생성하는 동안 전송 버튼이 응답 중단 버튼으로 바뀝니다. 이를 클릭하면 진행 중인 응답 생성을 멈출 수 있습니다.
대화 분량 초과
대화 기록과 에이전트가 읽어온 자료가 모델이 한 번에 처리할 수 있는 분량을 넘으면, 답변 자리에 안내 말풍선이 표시됩니다. 원인에 따라 안내가 다릅니다.
| 상황 | 원인 | 대처 |
|---|---|---|
| 이번 답변에서 도구를 사용함 | 도구가 가져온 결과가 쌓임 | 질문 범위를 좁힙니다 |
| 도구 사용 없음, 첨부 파일 있음 | 첨부 파일 내용이 통째로 전달됨 | 파일을 나누거나 문서 데이터 노드로 연결합니다 |
| 도구 사용 없음, 첨부 파일 없음 | 채팅방에 쌓인 이전 대화 | 새 대화를 시작합니다 |
같은 채팅방에서 다시 시도하면 기록이 남아 있어 같은 한도에 걸릴 수 있습니다. 말풍선의 새 대화 시작 버튼으로 새 채팅방을 열 수 있습니다.
사용 방법
에이전트 노드는 다음과 같은 세 가지 방법으로 사용할 수 있습니다.
방법 1: 연결 없이 사용
입력 포트에 아무것도 연결하지 않고 에이전트를 사용할 수 있습니다. 이 경우 에이전트는 일반적인 대화형 AI 어시스턴트로 동작합니다.
- 에이전트 노드를 캔버스에 추가합니다
- 모델을 선택합니다
- 사용자가 직접 대화를 시작할 수 있습니다
방법 2: 데이터셋 연결
입력 포트에 데이터셋을 연결하여 에이전트가 해당 데이터를 참고하도록 할 수 있습니다.
예제 워크플로우:
PDF 데이터
↓
PDF-데이터 변환
↓
에이전트 (데이터셋 입력)
- PDF 데이터 노드에 PDF 파일을 업로드합니다
- PDF-데이터 변환 노드로 PDF를 데이터셋으로 변환합니다
- 변환된 데이터셋을 에이전트 노드의 입력 포트에 연결합니다
- 에이전트가 PDF 내용을 참고하여 사용자의 질문에 답변합니다
단순히 문서 하나를 참고시키려는 경우라면, 별도 변환 없이 대화창에 파일을 첨부하는 것이 더 간단합니다. 데이터셋 연결은 다른 노드의 처리 결과를 참고 데이터로 넘길 때 유용합니다.
방법 3: 에이전트 메시지 가로채기 및 전달
에이전트 메시지 가로채기와 에이전트로 전달 노드를 사용하여 에이전트의 작업을 확장할 수 있습니다.
예제 워크플로우: 뉴스 크롤링 자동화
에이전트가 사용자의 뉴스 요청을 받아 자동으로 뉴스를 크롤링하고 요약하는 워크플로우입니다.
워크플로우 구성:
에이전트
↓ (사용자: "오늘 삼성전자 뉴스 기사 알려줘")
에이전트 메시지 가로채기
↓
프롬프트 (키워드 추출: "뉴스 크롤링할 키워드만 대답해 주세요")
↓
크롤링 (구글 뉴스: "삼성전자" 키워드로 뉴스 수집)
↓
프롬프트 (뉴스 요약: "뉴스 기사를 요약해 주세요")
↓
에이전트로 전달
↓
에이전트가 사용자에게 요약된 뉴스 제공
동작 과정:
- 사용자가 에이전트에 "오늘 삼성전자 뉴스 기사 알려줘"라고 요청합니다
- 에이전트가 뉴스 정보가 필요하다고 판단하면, 에이전트 메시지 가로채기 노드가 메시지를 가로챕니다
- 첫 번째 프롬프트 노드에서 사용자 요청에서 키워드("삼성전자")를 추출합니다
- 크롤링 노드가 구글 뉴스에서 "삼성전자" 키워드로 최신 뉴스를 수집합니다
- 두 번째 프롬프트 노드가 수집된 뉴스 기사들을 요약합니다
- 에이전트로 전달 노드가 요약된 뉴스를 에이전트에 전달합니다
- 에이전트가 사용자에게 요약된 뉴스 정보를 제공합니다
이를 통해 에이전트는 실시간 뉴스 정보를 자동으로 수집하고 요약하여 사용자에게 제공할 수 있습니다.
