노드 사용법 익히기 - Excel Reader 노드

이 튜토리얼에서는 에이전트리아(Agentria) 의 Excel Reader 노드 사용법을 안내합니다. Excel Reader 노드는 XLSX 파일의 시트를 파싱하여 열 이름·행 데이터·행 개수를 나누어 반환합니다.

이 튜토리얼에서는 엑셀 파일을 업로드하면 표의 내용을 구조 그대로 읽어오는 'Excel 표 데이터 읽기' 워크플로를 완성합니다.

사전 준비

에이전트리아 캔버스 진입 방법은 🔗3단계 핵심 가이드를 참고하시기 바랍니다.

XLSX 파일 한 개를 미리 준비합니다. 첫 행에 열 이름이 들어 있는 표 형태여야 합니다. Excel Reader 노드는 첫 행을 열 이름으로 인식하고, 그 아래 행을 데이터로 읽습니다.

Excel Reader 노드가 읽는 형식은 .xlsx입니다. 구형식인 .xls 파일은 엑셀에서 .xlsx로 저장한 뒤 사용하시기 바랍니다.

이후 화면에 나오는 열 이름은 예제 파일의 것이며, 준비하신 파일의 첫 행 내용에 따라 다르게 표시됩니다.

이 튜토리얼을 완료하면 다음을 수행할 수 있습니다.

1. Excel Reader 노드의 Excel 파일 항목에 파일 타입 변수를 연결할 수 있습니다.

2. 시트의 열 이름을 headers로 받아 확인할 수 있습니다.

3. 데이터 행을 rows로 받아 열 이름으로 값을 참조할 수 있습니다.

4. 데이터 행 개수를 count로 받아 다른 노드에서 활용할 수 있습니다.

5. 노드 테스트와 어빌리티 테스트로 파싱 결과를 확인할 수 있습니다.

워크플로 개요

이 튜토리얼의 핵심은 Excel Reader 노드입니다.

Excel Reader 노드는 연결된 XLSX 파일의 시트를 파싱하여 세 가지 값을 반환합니다. 첫 행의 열 이름은 headers로, 그 아래 데이터 행은 rows로, 데이터 행의 개수는 count로 나뉩니다. 표를 문자열로 늘어놓지 않고 구조를 유지한 채 돌려주기 때문에, 특정 열의 값만 골라 쓰거나 행 단위로 반복 처리하기 좋습니다.

Excel Reader 노드는 '파일 처리 도구' 카테고리에 속합니다. 처리할 파일 형식에 따라 아래 노드를 함께 활용할 수 있습니다.

CSV Reader 노드는 Excel Reader 노드와 반환 형식까지 같습니다. 다루는 파일이 .csv라면 이 튜토리얼을 그대로 따라 하시면 됩니다.

나머지 리더 노드도 지원하는 파일 형식과 반환 형식만 다를 뿐, 파일을 연결하고 결과를 받아 다음 노드로 넘기는 흐름은 같습니다.

PDF 텍스트 리더 노드의 자세한 사용법은 🔗PDF 텍스트 리더 노드 가이드를 참고하시기 바랍니다.

1단계: 인풋 변수 선언 (시작 노드)

시작 노드를 더블 클릭하여 노드 편집기(Node Editor)를 엽니다. 어빌리티 캔버스에서 시작 노드는 Ability Input으로 표시됩니다.

입력 변수 영역에서 아래 변수를 추가하고 저장을 클릭합니다.

타입은 파일 하나를 받는 File로 선택합니다. Excel Reader 노드는 파일을 하나씩 처리하므로 여러 파일을 담는 Filearray는 사용하지 않습니다.

excel_file은 다음 단계에서 Excel Reader 노드의 입력으로 연결할 변수입니다.

2단계: Excel Reader 노드 추가

캔버스에서 노드 추가(Add Node)를 클릭하고, 파일 처리 도구 카테고리에서 Excel Reader 노드를 드래그 앤 드롭으로 캔버스에 배치합니다.

배치한 노드의 이름은 New Excel Reader Node 1로 지정됩니다.

3단계: Excel Reader 노드 설정

New Excel Reader Node 1 노드를 더블 클릭하여 노드 편집기를 엽니다.

Excel Reader 노드는 아래 항목을 제공합니다.

이 튜토리얼에서는 Excel 파일만 사용합니다. 선택 항목인 sheet_name과 evaluate_formula는 기본 상태로 두면 첫 번째 시트를 읽습니다.

파일을 연결하는 두 가지 방법

Excel 파일 항목은 두 가지 방식으로 채울 수 있습니다.

노드에 직접 업로드하려면 Excel 파일 항목의 선택 또는 드래그 앤 드롭 영역에 파일을 올립니다. 파일이 노드에 저장되므로 시작 노드에서 파일을 받지 않아도 됩니다.

CSV Reader 노드, JSON Reader 노드, 텍스트 리더 노드, Word Reader 노드, HWPX Reader 노드, HTML Reader 노드도 같은 방식으로 파일을 연결합니다.

두 방식 모두 파일 하나만 연결할 수 있습니다. 인풋 변수를 연결하는 경우 변수 타입을 File로 선언하고 테스트에도 파일 하나만 업로드합니다. 여러 엑셀 파일을 처리해야 한다면 파일 수만큼 Excel Reader 노드를 배치하고 각 노드에 파일을 하나씩 연결합니다.

이 튜토리얼에서는 인풋 변수를 연결하는 방식을 사용합니다. Excel 파일 항목에 시작 노드의 excel_file 변수를 드래그 앤 드롭으로 연결합니다. 사용자가 업로드한 파일을 그때그때 처리하는 워크플로를 만들기 위해서입니다.

선택 항목 추가하기

선택 항목은 처음부터 화면에 표시되지 않습니다. 사용하려면 노드 편집기의 변수 추가 버튼을 클릭합니다. 변수 추가 모달에서 필요한 항목을 체크하고 저장을 클릭하면, 노드의 옵션 변수 영역에 해당 항목이 나타납니다. sheet_name을 추가하면 시트 이름 항목으로 표시됩니다.

• sheet_name : 읽어올 시트의 이름을 지정합니다. 시트가 여러 개인 파일에서 특정 시트를 읽어야 할 때 사용합니다. 지정하지 않으면 첫 번째 시트를 읽습니다.

• evaluate_formula : 수식이 들어 있는 셀을 어떻게 반환할지 정합니다. True이면 수식이 계산된 결과값을, False이면 =SUM(A1:A10) 같은 수식 문자열 자체를 반환합니다. 항목을 추가하면 True로 켜진 상태로 시작합니다.

노드가 출력하는 값

노드가 정상 실행되면 아래 세 값을 출력합니다.

세 값의 관계는 다음과 같습니다.

• headers : 시트의 첫 행을 열 이름으로 읽어 배열로 반환합니다.

• rows : 첫 행을 제외한 나머지 행을 데이터로 반환합니다.

• count : rows의 개수입니다. 열 이름 행은 세지 않습니다.

첫 행은 열 이름으로 사용되므로 rows에 포함되지 않습니다. 따라서 엑셀에서 보이는 전체 행 수보다 count가 하나 적습니다.

4단계: 종료 노드 설정

종료 노드를 더블 클릭하여 노드 편집기를 엽니다. 어빌리티 캔버스에서 종료 노드는 Ability Output으로 표시됩니다.

출력 변수 영역에서 아래 변수를 추가하고 저장을 클릭합니다.

추가한 row_list 항목에 Excel Reader 노드의 rows를 드래그 앤 드롭으로 연결합니다.

출력 변수는 이름과 타입을 직접 정한 뒤, 이전 노드의 아웃풋 중 타입이 맞는 값을 드래그 앤 드롭으로 연결하는 방식입니다. rows는 배열이므로 타입을 Array로 선택했습니다.

headers와 count도 필요하다면 같은 방식으로 출력 변수를 추가해 연결할 수 있습니다. headers는 배열이므로 Array를, count는 정수이므로 Integer를 선택합니다. 이 튜토리얼에서는 데이터 행만 내보냅니다.

5단계: 노드 테스트로 출력 확인

노드 편집기 상단의 테스트(TEST) 버튼을 클릭하면 왼쪽에 테스트 입력 패널이 열립니다. [Ability Input] excel_file 항목에 준비한 XLSX 파일을 드래그 앤 드롭으로 업로드한 뒤 테스트를 클릭합니다.

아웃풋 영역에서 headers를 펼치면 시트 첫 행의 값이 순서대로 나열됩니다. 아래는 예제 파일을 넣었을 때의 결과입니다.

headers
├─ [0]  번호
├─ [1]  구분
├─ [2]  기능명
├─ [3]

headers
├─ [0]  번호
├─ [1]  구분
├─ [2]  기능명
├─ [3]

headers
├─ [0]  번호
├─ [1]  구분
├─ [2]  기능명
├─ [3]

rows를 펼치면 데이터 행이 [0]부터 나열됩니다. 각 행을 다시 펼치면 [0], [1] 같은 인덱스가 아니라 열 이름이 표시됩니다.

rows
└─ [0]

rows
└─ [0]

rows
└─ [0]

여기 보이는 번호, 구분, 기능명은 노드가 정해둔 이름이 아니라 예제 파일의 첫 행에 적혀 있던 값입니다. 다른 파일을 사용하면 그 파일의 첫 행 내용이 그대로 열 이름이 됩니다.

이것이 Excel Reader 노드의 핵심입니다. 값을 꺼낼 때 rows[0]의 세 번째 항목처럼 순서를 세지 않고, 열 이름으로 바로 지정할 수 있습니다. 나중에 엑셀에서 열 순서를 바꾸더라도 워크플로를 고칠 필요가 없습니다.

![노드 테스트 결과 하단에서 count 값을 확인하는 이미지]

아웃풋 영역 맨 아래에서 count를 확인합니다. rows의 마지막 인덱스가 [11]이면 count는 12가 됩니다. 인덱스는 0부터 시작하기 때문입니다.

노드 테스트는 해당 노드만 단독으로 실행합니다. 앞뒤 노드를 연결하지 않은 상태에서도 파싱 결과를 먼저 확인할 수 있어, 워크플로를 완성하기 전에 파일이 정상적으로 읽히는지 점검할 때 유용합니다.

6단계: 어빌리티 테스트로 워크플로 전체 실행

캔버스 우측 하단의 테스트 실행(RUN TEST) 버튼을 클릭하여 어빌리티 테스트(Ability Test)를 실행합니다.

excel_file 항목에 XLSX 파일을 업로드한 뒤 테스트를 실행하면, 종료 노드의 row_list에 파싱된 데이터 행이 반환되는 것을 확인할 수 있습니다.

참고: 파싱 결과의 특징

셀 값의 타입이 보존됩니다. 숫자가 들어 있는 열은 숫자로, 글자가 들어 있는 열은 문자열로 반환됩니다. 예제 파일의 번호 열처럼 숫자만 들어 있는 열은 문자열 "1"이 아니라 숫자 1로 전달되므로, 이어지는 노드에서 계산에 바로 사용할 수 있습니다.

첫 행은 항상 열 이름으로 처리됩니다. Excel Reader 노드는 시트의 첫 행을 무조건 열 이름으로 간주하고 파일을 읽습니다. 따라서 첫 행에 보고서 제목이나 안내 문구가 들어 있거나 데이터가 바로 시작하는 파일은, 그 내용이 열 이름 자리를 차지하게 되어 원하는 결과를 얻지 못합니다.

읽을 파일의 형식을 미리 맞춰 두시기 바랍니다. 제목 행이나 빈 행이 표 위에 있다면 삭제하고, 첫 행에 열 이름이 오도록 정리한 뒤 워크플로에 넣습니다.

시트 첫 행의 값이 그대로 키가 됩니다. 열 이름은 노드가 만들어내는 것이 아니라 파일에 적혀 있는 값을 그대로 가져옵니다. 한글 이름도 별도의 영문 변환 없이 유지되며, 사용 난이도처럼 공백이 포함된 이름도 그대로 사용됩니다.

읽어올 시트는 sheet_name으로 지정합니다. 지정하지 않으면 파일의 첫 번째 시트를 읽습니다. 다른 시트를 읽어야 한다면 변수 추가로 sheet_name 항목을 꺼내 시트 이름을 입력합니다. 한 파일 안의 여러 시트를 모두 읽어야 한다면, 시트 수만큼 Excel Reader 노드를 배치하고 각 노드의 sheet_name에 서로 다른 시트 이름을 지정합니다.

이때 시트 이름은 엑셀 파일의 시트 탭에 적힌 이름과 정확히 일치해야 합니다. 일치하지 않으면 노드 실행이 실패하며 아래 오류가 반환됩니다.

이 오류는 값을 입력하지 않았을 때뿐 아니라 입력한 이름의 시트를 찾지 못했을 때도 나타납니다. 시트 이름 항목에 값을 분명히 입력했는데 이 메시지가 보인다면, 괄호 안의 이름을 엑셀의 시트 탭과 대조해 보시기 바랍니다. 공백이나 대소문자가 다른 경우가 많습니다.

수식 셀은 반환 방식을 고를 수 있습니다. evaluate_formula는 추가하면 True로 켜진 상태이므로, 그대로 두면 수식이 계산된 결과값이 반환됩니다. 수식 자체를 점검하거나 문서화해야 하는 경우처럼 =SUM(A1:A10) 같은 원본 문자열이 필요할 때만 False로 바꿉니다.

병합된 셀은 첫 칸에만 값이 담깁니다. 엑셀에서 여러 칸을 병합하면 화면에는 하나의 넓은 칸으로 보이지만, 파일 안에서는 왼쪽 위 첫 번째 칸만 값을 가지고 나머지 칸은 비어 있습니다. Excel Reader 노드는 이를 그대로 읽으므로 첫 칸에는 값이, 나머지 칸에는 null이 반환됩니다.

세로 병합과 가로 병합 모두 같은 방식으로 처리됩니다. 예를 들어 구분 열의 두 행을 병합했다면 첫 번째 행에만 값이 담기고 두 번째 행의 구분은 null이 됩니다. 설명과 활용 예시 두 열을 가로로 병합했다면 설명에만 값이 담기고 활용 예시는 null이 됩니다.

행마다 값이 채워져 있어야 하는 워크플로라면, 병합을 해제하고 각 칸에 값을 입력한 파일을 사용하시기 바랍니다. 병합된 표를 그대로 읽으면 중간중간 null이 섞여 이후 노드에서 예상과 다른 결과가 나올 수 있습니다.

데이터가 없는 시트는 빈 결과를 반환합니다. 내용이 비어 있는 시트를 읽으면 노드는 오류를 내지 않고 정상 완료로 처리하며 headers와 rows에 빈 배열을, count에 0을 반환합니다. 워크플로가 성공한 것처럼 다음 노드로 진행되므로, 데이터가 있을 때만 이후 단계를 실행하려면 count가 0인지 확인하는 분기를 두시기 바랍니다.

행 단위 반복 처리에 적합합니다. rows가 배열이므로 반복(Loop) 노드에 연결하면 행마다 같은 작업을 수행할 수 있습니다. count는 처리할 행이 몇 개인지 미리 확인하거나, 행이 하나도 없을 때 이후 단계를 건너뛰는 판단에 활용할 수 있습니다.

표 데이터에는 리더 노드를 사용합니다. 같은 표라도 PDF 안에 들어 있으면 PDF 텍스트 리더 노드가 셀 내용을 문자열로 이어 붙여 반환하므로 행과 열의 구분이 사라집니다. 표를 구조 그대로 다뤄야 한다면 원본을 XLSX나 CSV로 준비해 Excel Reader 노드나 CSV Reader 노드로 읽는 것이 정확합니다.

다음 단계

🎉 축하합니다! 에이전트리아를 사용해 'Excel 표 데이터 읽기' 워크플로를 완성했습니다.

rows를 반복 노드에 연결해 행마다 처리하거나, 특정 열의 값만 뽑아 AI 모델 노드에 넘겨 분류·요약하는 워크플로로 확장할 수 있습니다. count를 활용해 처리할 데이터가 있을 때만 이후 단계를 실행하는 구성도 만들어 보시기 바랍니다.

에이전트리아는 아이디어를 현실로 바꾸는 가능성의 공간입니다.

당신의 상상력으로 워크플로는 무한히 확장될 수 있습니다.

• 더 많은 어빌리티 예제가 궁금하다면 🔗어빌리티 가이드 페이지를 확인하세요.

• 에이전트 예제를 원한다면 🔗에이전트 가이드 페이지를 확인하세요.

자주 묻는 질문

Excel Reader 노드란 무엇인가요?

Excel Reader 노드는 에이전트리아에서 XLSX 파일의 시트를 파싱해 표의 내용을 구조 그대로 반환하는 노드입니다. '파일 처리 도구' 카테고리에 속하며, Excel 파일 항목에 파일을 연결하면 첫 행의 열 이름을 headers 배열로, 그 아래 데이터 행을 rows 배열로, 데이터 행 개수를 count 숫자로 출력합니다. 선택 항목으로 읽어올 시트를 지정하는 sheet_name과 수식 셀의 반환 방식을 정하는 evaluate_formula를 제공합니다.

Excel Reader 노드는 언제 사용해야 하나요?

엑셀로 관리하던 표 데이터를 워크플로에서 다뤄야 할 때 사용합니다. 상품 목록·고객 명단·재고 현황처럼 행마다 같은 처리를 반복해야 하는 데이터에 적합합니다. 표를 문자열이 아니라 행과 열의 구조로 받기 때문에, 특정 열의 값만 골라 쓰거나 행 단위로 반복 처리할 수 있습니다.

headers, rows, count는 각각 무엇인가요?

headers는 시트 첫 행에서 읽어온 열 이름 목록이고, rows는 첫 행을 제외한 데이터 행 목록이며, count는 그 데이터 행의 개수입니다. 첫 행은 열 이름으로 사용되어 rows에 포함되지 않으므로, 엑셀 화면에서 보이는 전체 행 수보다 count가 하나 적습니다.

rows에서 특정 열의 값을 어떻게 참조하나요?

rows의 각 원소는 순서대로 나열된 배열이 아니라 열 이름을 키로 갖는 객체입니다. 따라서 몇 번째 열인지 세지 않고 열 이름으로 값을 지정합니다. 이때 사용하는 열 이름은 노드가 정해둔 것이 아니라 시트 첫 행에 적혀 있는 값이며, 한글 이름과 공백도 그대로 유지됩니다. 이 방식이라면 나중에 엑셀에서 열 순서를 바꾸어도 워크플로를 수정할 필요가 없습니다.

Excel Reader 노드는 PDF 텍스트 리더 노드와 어떻게 다른가요?

두 노드는 반환 형식이 다릅니다. PDF 텍스트 리더 노드는 문서의 텍스트를 하나의 문자열로 이어 붙여 반환하므로, PDF 안에 표가 있어도 셀 내용이 순서대로 나열될 뿐 행과 열의 구분은 남지 않습니다. Excel Reader 노드는 시트를 파싱해 열 이름과 데이터 행을 나누어 반환하므로 표의 구조가 그대로 유지됩니다. 표 데이터를 행 단위로 다뤄야 한다면 원본을 XLSX로 준비해 Excel Reader 노드를 사용합니다.