슬립 키워드 검색 노드
노드 사용법 익히기 - 슬립 키워드 검색(Slip Keyword Search) 노드
슬립 키워드 검색(Slip Keyword Search) 노드는 슬립박스 안의 문서를 키워드로 전문(全文) 검색하는 노드입니다. 검색어는 단순 문자열이 아니라 불리언 검색 식으로 해석됩니다 — 공백이나 &&는 AND(모두 포함), ||나 OR는 OR(그룹)로 동작하며, 공백이나 특수 문자가 포함된 구는 따옴표로 감싸 하나의 리터럴 문자열로 처리할 수 있습니다. 여기에 슬립 타입·태그 필터를 더해 원하는 범위로 좁힐 수 있습니다.
이 노드는 에이전트에 도구로 연결해 활용하기도 좋지만, 이 튜토리얼에서는 가장 기본적인 사용법을 확인할 수 있도록 어빌리티에서 다룹니다. 에이전트에 연결하는 방법은 별도의 슬립박스 에이전트 통합 가이드에서 다룰 예정입니다. 이 튜토리얼에서는 에이전트리아 Docs 슬립박스에 이미 있는 문서들을 대상으로 키워드 검색을 실행하는 어빌리티 워크플로를 완성합니다.
사전 준비
이 튜토리얼을 시작하기 전에 프로젝트에 슬립박스가 구축되어 있어야 합니다. 슬립박스 구성 방법은 🔗슬립박스 가이드를 참고하시기 바랍니다. 이 노드는 조회 전용이므로 검색 대상이 될 문서(슬립)가 슬립박스 안에 이미 몇 개 있어야 검색 결과를 확인할 수 있습니다.
이 튜토리얼을 완료하면 다음을 수행할 수 있습니다.
슬립 키워드 검색 노드로 슬립박스 안의 문서를 키워드로 검색할 수 있습니다.
AND·OR·따옴표 리터럴 문법을 상황에 맞게 사용해 검색식을 작성할 수 있습니다.
슬립 타입 필터와 태그 필터로 검색 범위를 좁힐 수 있습니다.
런테스트와 출력값으로 검색 결과(
hits)의 구조를 확인할 수 있습니다.
워크플로 개요
이 튜토리얼의 핵심은 슬립 키워드 검색 노드입니다.
슬립 키워드 검색 노드는 검색어를 받아 슬립박스 전체(제목·요약·본문)를 대상으로 전문 검색을 수행합니다. 노드가 정상 실행되면 조건에 맞는 문서들이 hits 배열로 반환됩니다.
슬립 키워드 검색 노드 기본 정보
슬립 키워드 검색 노드는 아래 옵션을 제공합니다.
옵션 | 필수 여부 | 설명 |
|---|---|---|
| 필수 | 불리언 검색 식입니다. 공백이나 |
| 선택 | 특정 슬립 타입만 검색합니다(색인/콘텐츠). 비워 두면 모든 타입을 검색합니다. |
| 선택 | 반환할 최대 히트 수입니다(기본 20, 최대 50). 이 수를 넘는 매칭이 있으면 초과분은 돌려주지 않고 |
| 선택 | 히트가 전부 가지고 있어야 하는 태그 목록입니다(AND). |
| 필수 | 검색 대상 슬립박스입니다. 빌더에서 선택해 고정합니다. |
이 튜토리얼에서는 다섯 항목을 모두 시작 노드와 연결합니다. 최대 결과 수는 반드시 값을 명시적으로 채우도록 안내합니다 — 아래 "주의" 참고.
주의:
최대 결과 수를 비워 두고 실행하면 문서에 적힌 기본값 20이 아니라 실질적으로 1건만 반환되는 것으로 실측 확인되었습니다. 원하는 결과 수(예: 20)를 항상 명시적으로 입력하세요.
1단계: 어빌리티 생성
새 어빌리티를 생성합니다. 이름에 슬립 키워드 검색 노드, 설명에 슬립박스 문서 키워드로 검색하기를 입력합니다. 어떤 슬립박스를 검색할지는 각자 알아서 정하면 되며, 이 튜토리얼에서는 에이전트리아 Docs 슬립박스에 이미 있는 문서들을 대상으로 진행합니다.
2단계: 시작 노드 설정
시작 노드를 더블 클릭하여 노드 편집기로 진입합니다. 아래 네 변수를 추가합니다.
keyword: 검색어(불리언 검색 식)를 입력받습니다. (String)slipType: 슬립 타입 필터를 입력받습니다. (String)limit: 최대 결과 수를 입력받습니다. (Integer)tags: 태그 필터를 입력받습니다. (Array)
tags는 String이 아니라 Array 타입으로 추가해야 합니다.
3단계: 슬립 키워드 검색 노드 추가
+노드 추가(Add Node) → 슬립박스(Slipbox) 카테고리에서 슬립 키워드 검색 노드를 추가합니다.
4단계: 슬립 키워드 검색 노드 설정
슬립 키워드 검색 노드를 더블 클릭하여 노드 편집기로 진입합니다. 슬립박스 공개 UUID에서 사용할 슬립박스를 선택합니다 — 이 튜토리얼에서는 예시로 에이전트리아 Docs를 선택합니다. 이 값을 선택하지 않고 비워두면 노드 실행이 실패하니 반드시 확인합니다.
나머지 항목에는 아래와 같이 시작 노드의 입력값을 드래그 앤 드롭으로 바인딩합니다.
어댑터 변수 | 바인딩 값 |
|---|---|
|
|
|
|
|
|
|
|
노드가 정상 실행되면 hits(검색된 문서 목록), slip_ids, total(반환된 히트 수), truncated(더 많은 매칭이 있으면 true), error_code, error_message를 출력합니다.
5단계: 종료 노드 설정
종료 노드를 더블 클릭하여 노드 편집기로 진입합니다. String 타입의 result 출력변수를 추가하고 슬립 키워드 검색 노드의 error_code를 드래그 앤 드롭으로 바인딩합니다. 이렇게 하면 검색이 정상적으로 이루어졌는지를 출력값으로 확인할 수 있습니다.
6단계: 검색 대상 확인
이 노드는 조회 전용이라 별도로 슬립을 만들 필요는 없습니다. 에이전트리아 Docs 슬립박스로 이동해, 검색해 볼 만한 문서 제목을 몇 개 눈에 익혀 둡니다(예: 제목에 노드가 들어간 문서들). 이 값을 다음 단계에서 keyword 입력값으로 사용합니다.
7단계: 런테스트 실행
keyword에 노드를 입력합니다. limit에는 반드시 20처럼 값을 명시적으로 입력합니다(비워 두면 1건만 반환됩니다). slipType과 tags는 비워 둔 채 테스트 실행(RUN TEST)을 클릭합니다. result 출력값으로 SUCCESS가 나오면 성공입니다.
8단계: 디버그 로그 확인
슬립 키워드 검색 노드의 디버그 로그를 확인하면 error_code가 SUCCESS로 반환된 세부 내역과, hits 배열에 담긴 검색 결과(page_id, title, page_type, summary, parent_index_title, tags, snippet)를 확인할 수 있습니다. total은 이번 요청에서 실제로 반환된 히트 수이며, 슬립박스 전체의 매칭 총량이 아닙니다 — 매칭이 limit보다 많으면 truncated가 true로 표시됩니다.
9단계: 검색 결과 대조 확인
hits에 반환된 문서 제목들을 에이전트리아 Docs 슬립박스에서 직접 열어보고, 제목뿐 아니라 요약이나 본문에도 노드라는 단어가 실제로 포함되어 있는지 확인합니다. 이 노드는 제목만이 아니라 문서 전체(제목·요약·본문)를 대상으로 검색하므로, 제목에 검색어가 없는 문서도 결과에 포함될 수 있습니다.
다음 단계
🎉 축하합니다! 에이전트리아를 사용해 '슬립박스 문서 키워드로 검색하기' 워크플로를 완성했습니다.
이 노드를 에이전트 루프 노드에 도구로 연결하면, 에이전트가 대화 중 슬립박스 문서를 스스로 검색해 답변에 활용하는 워크플로로도 확장할 수 있습니다.
에이전트리아는 아이디어를 현실로 바꾸는 가능성의 공간입니다.
당신의 상상력으로 워크플로는 무한히 확장될 수 있습니다.
더 많은 노드 활용 예제가 궁금하다면 🔗노드 사용법 페이지를 확인하세요.
자주 묻는 질문
슬립 키워드 검색 노드는 무엇을 하는 노드인가요?
슬립 키워드 검색 노드는 슬립박스 안의 문서를 키워드로 전문 검색하는 노드입니다. 제목뿐 아니라 요약·본문까지 검색 대상에 포함되며, 불리언 검색 식(AND/OR/리터럴)과 슬립 타입·태그 필터로 범위를 좁힐 수 있습니다. 결과는 hits 배열로 반환되는 조회 전용 노드입니다.
키워드에 여러 단어를 입력하면 어떻게 동작하나요?
기본적으로 공백은 AND로 해석되어, 입력한 모든 단어를 (문서 어딘가에 따로따로) 포함하는 문서만 찾습니다. 예를 들어 Slack 노드를 검색하면 "Slack"과 "노드"라는 단어가 각각 문서 안에 존재하는 모든 문서가 매칭되며, 두 단어가 반드시 붙어 있을 필요는 없습니다. ||나 OR을 쓰면 둘 중 하나만 포함해도 매칭되는 OR 그룹으로 바뀌어 훨씬 넓은 결과를 얻습니다.
정확한 구(phrase)로만 검색하고 싶다면 어떻게 하나요?
검색어를 따옴표로 감싸면 됩니다. 예를 들어 값 설정(따옴표 없이)은 "값"과 "설정"이라는 두 단어를 각각 포함하는 모든 문서를 찾아 매우 넓은 결과가 나오지만, "값 설정"(따옴표로 감싼 리터럴)은 이 문자열이 그대로 붙어서 등장하는 문서만 좁혀서 찾습니다.
최대 결과 수를 비워 두면 안 되나요?
비워 두지 않는 것을 권장합니다. 필드 설명상 기본값은 20이지만, 실제로는 값을 비운 채(또는 0으로) 실행하면 1건만 반환되는 것으로 확인되었습니다. 원하는 결과 수(최대 50)를 항상 명시적으로 입력하세요.
슬립 타입 필터와 태그 필터는 어떻게 다른가요?
슬립 타입 필터는 문서의 구조적 분류(색인 문서인지 콘텐츠 문서인지)로 범위를 좁히고, 태그 필터는 문서에 수동으로 붙인 태그(예: reviewed, deprecated)로 범위를 좁힙니다. 두 필터는 서로 다른 기준이므로 필요하면 함께 사용할 수 있습니다.