[최신] 벨루가 에이전트 빌더 기능 출시

에이전트 빌더 가이드: 사용법 안내 챗봇을 만들어봐요

"사용법 알려줘"라고 물어보면 문서를 검색해서 답변하고, 그 외 질문에는 "지원하지 않는 기능입니다"라고 안내하는 AI 챗봇을 만들어 볼까요?
에이전트 빌더의 기능을 활용하면, 코딩 없이도 이런 스마트한 챗봇을 직접 구성할 수 있어요.

이 가이드를 보면서 아래와 같은 에이전트를 처음부터 끝까지 함께 만들어 봐요!

💡 Veluga Agent Tips
함께 만들어볼 에이전트는 답변의 품질이 우수한 챗봇이 아닌, 에이전트 적용 전과 후의 차이를
명확히 인지하기 위한 챗봇이에요.

에이전트의 품질을 결정하는 큰 요소 중 하나는 프롬프트예요.
벨루가에서 제공하는 프롬프트 엔지니어링 문서를 보면 도움이 될 거예요.

Staff_Veluga프롬프트 작성법 | 벨루가 - velugadoc

이 가이드에서 만들 에이전트

먼저 우리가 만들 에이전트를 설계해요.

우리가 만들 에이전트는 사용자 질문을 하면 아래와 같이 동작할 거예요.

💡 Veluga Agent Tips
에이전트 빌더 설명서를 먼저 읽고 오면 이 가이드를 훨씬 쉽게 따라 할 수 있어요.
특히 노드 종류, 변수 사용법, 노드 연결 방법을 미리 숙지해 주세요.

Step 1. 에이전트 만들기

에이전트 빌더에 접속한 뒤, 채널을 선택하고 에이전트 만들기 버튼을 클릭해 주세요.

💡 Veluga Agent Tips
에이전트는 채널이 있어야 만들 수 있어요.

Staff_VelugaAI 채팅 만들기 | 단 5분만에 만드는 나만의 AI 벨루가 - velugadoc
여기를 참고해 주세요.

화면이 열리면, 좌측 상단의 에이전트 이름 부분에 "사용법 안내 에이전트"이라고 입력해 주세요.

Step 2. 질문 의도 분류 (AI 호출)

해당 노드에서는 사용자의 질문이 "사용법" 관련인지 아닌지를 AI가 판별하는 기능을 만들게요.

노드 추가하기

중앙 상단의 "AI" 버튼을 클릭해 노드를 추가해요.

노드 설정하기

노드를 클릭하여 설정 패널을 열고, 아래와 같이 입력해 주세요.

일반 설정

노드 이름: 질문 의도 분류

AI 모델명: GPT-5

시스템 프롬프트: 아래 내용 참고

유저 프롬프트: {query}

시스템 프롬프트에 아래 내용을 입력해요.

You are a query classifier. Analyze the user's {query} and return a JSON object.

## Classification Rules
- If {query} is about usage, how-to, or contains "사용법" → "Tutorial"
- Otherwise → "search_required"

## Output Format (strict JSON only)
{
  "classification": "<label>"
}

## Examples
- query: "사용법" → {"classification": "Tutorial"}
- query: "사용법 알려줘" → {"classification": "Tutorial"}
- query: "어떻게 쓰나요" → {"classification": "Tutorial"}
- query: "에이전트 사용법" → {"classification": "Tutorial"}
- query: "벨루가 에이전트 사용법" → {"classification": "Tutorial"}
- query: "에이전트 어케 써" → {"classification": "Tutorial"}
- query: "에이전트에 어떤 노드가 있어" → {"classification": "Tutorial"}
- query: "최신 뉴스 알려줘" → {"classification": "search_required"}

노드 설정

상태 메시지: 질문 의도를 분류중이에요

노드 출력 변수명: ai_result

스트리밍 여부: 해제

응답 포맷: JSON 객체

설정 예시

💡 Veluga Agent Tips**
왜 JSON 포맷인가요?** 다음 단계의 조건 분기 노드에서 ai_result['classification'] 값을 읽어
경로를 나눠야 하기 때문에, AI가 정해진 JSON 형태로 응답하도록 설정해요.
최종 사용자에게 출력하는 노드가 아니므로 JSON 객체로 설정해도 괜찮아요.

Step 3. 질문 의도 분류 (조건 분기)

AI가 분류한 결과에 따라 에이전트의 경로를 나눠줘야 해요.

이런 분기는 우리 챗봇에서 지원 / 미지원 기능을 분리해서 관리해 주는 핵심 기능이에요.

노드 추가하기

질문 의도 분류 노드 우측에 조건 분기 노드를 추가하고, 연결해 주세요.

노드 설정하기

노드를 클릭하여 설정 패널을 열고, 아래와 같이 입력해 주세요.

일반 설정

노드 이름: 질문 의도 조건분기

BRANCHES (조건)

변수 명: ai_result['classification']

연산자: 같음

값: Tutorial

설정 예시

💡 Veluga Agent Tips
ai_result['classification']은 1단계 AI 노드가 출력한 JSON에서 classification 키의
값을 가져온다는 뜻입니다.

변수명 입력 시 Tab 키를 누르면 자동 완성 기능을 활용할 수 있어요.

💡 Veluga Agent Tips
ai_result['classification']은 1단계 AI 노드가 출력한 JSON에서 classification 키의
값을 가져온다는 뜻이에요.

변수명 입력 시 Tab 키를 누르면 자동 완성 기능을 활용할 수 있어요.

Step 4. 검색 쿼리 증강 (AI 호출)

사용자의 질문 하나를 비슷한 의미의 쿼리(검색어) 여러 개로 늘려서, 문서 검색의 정확도를 높이는 부분이 필요해요.

이 부분은 RAG 챗봇의 핵심적인 기능 중 하나에요.

노드 추가하기

조건 분기 노드에서 Tutorial 분기의 이동 위치에 새 AI 호출 노드를 추가해 주세요.

노드 설정하기

노드를 클릭하여 설정 패널을 열고, 아래와 같이 입력해 주세요.

일반 설정

노드 이름: 검색 쿼리 증강

AI 모델명: gpt-5-mini

시스템 프롬프트: 아래 내용 참고

유저 프롬프트: {query}

시스템 프롬프트에 아래 내용을 입력해요.

You are a search query augmenter. Given {query}, generate 5 semantically similar queries for vector DB retrieval.

## Rules
1. First item is always the original {query}
2. Add 4 variations: synonyms, rephrasings, and include "벨루가" in at least one

## Output Format (strict JSON only)
{
  "search_queries": ["<original>", "<var1>", "<var2>", "<var3>", "<var4>"]
}

## Example
query: "에이전트 사용법"
{"search_queries": ["에이전트 사용법", "에이전트 팁", "에이전트 잘 사용하기", "벨루가 에이전트 사용법", "에이전트 사용하기"]}

노드 설정

상태 메시지: 검색 쿼리를 증강중이에요

노드 출력 변수명: augmentation

스트리밍 여부: 해제

응답 포맷: JSON 객체

설정 예시

💡 Veluga Agent Tips
사용자가 "사용법"이라고만 입력해도, "사용법", "벨루가 사용법", "사용하기", "사용 방법",
"이용법" 등 다양한 표현으로 검색하면 더 관련성 높은 문서를 찾을 수 있어요.
이렇게 쿼리를 늘려주는 과정을 쿼리 증강이라고 해요.

Step 5. 문서 검색 (문서 검색)

이 노드는 Step 4에서 증강한 쿼리 목록으로 채널에 업로드한 문서를 검색하는 노드예요.

노드 추가하기

검색 쿼리 증강 노드 우측에 문서 검색 노드를 추가하고, 연결해 주세요.

노드 설정하기

노드를 클릭하여 설정 패널을 열고, 아래와 같이 입력해 주세요.

일반 설정

노드 이름: 문서 검색

상태 메시지: 문서를 검색하고 있어요

노드 출력 변수명: search_result

채널 ID: 현재 채널 선택

쿼리 리스트: {augmentation.search_queries}

설정 예시

💡 Veluga Agent Tips
채널 ID? 특정 채널 선택 기능을 활용하면 내가 만든 다른 채널의 데이터베이스를
활용할 수 있어요.

쿼리 리스트 변수 {augmentation.search_queries}는 이전 AI 노드가 출력한 JSON의
search_queries 배열을 그대로 전달해요.
쿼리 리스트를 사용하면 여러 개의 쿼리 각각에 대해 검색해요.

Step 6. 최종 답변 생성 (AI 호출)

검색한 문서 내용을 바탕으로 사용자에게 친절하게 답변하는 노드예요.

💡 Veluga Agent Tips
해당 노드의 프롬프트에 따라서, 답변 형식, 답변 길이 등 최종 출력이 크게 달라져요.
프롬프트 엔지니어링에 대한 자료는

Staff_Veluga프롬프트 작성법 | 벨루가 - velugadoc
에서 확인할 수 있어요.

노드 추가하기

문서 검색 노드 우측에 AI 호출 노드를 추가하고, 연결해 주세요.

노드 설정하기

노드를 클릭하여 설정 패널을 열고, 아래와 같이 입력해 주세요.

일반 설정

노드 이름: 최종 답변 출력

AI 모델명: GPT-5.2

시스템 프롬프트: 아래 내용 참고

유저 프롬프트: {query}

시스템 프롬프트에 아래 내용을 입력해요.

You are 벨루가's AI assistant. Answer the user's {query} based on {search_result}.

## Rules
1. Only use information from {search_result} — do not make up answers
2. If {search_result} has no relevant info, reply: "관련 정보를 찾을 수 없습니다."
3. Answer in Korean, concise and friendly

## Formatting
- Group related content under clear headers (###)
- How-to/Tutorial → numbered steps (1. 2. 3.)
- Comparisons/features → table format
- Key points → bold(**) for emphasis
- Keep paragraphs short (2-3 sentences max)
- Never dump raw data — always reorganize and summarize clearly
- Separate sections with line breaks for readability

## Bad Example (❌)
1. 에이전트 기본 기능
2. 에이전트 이름 변경: 에이전트 이름을 변경할 수 있어요.
3. 노드 추가/연결: 시작 노드를 다양한 노드...
7. 변수 사용 규칙
8. 사용 불가: 시스템 변수 사용 불가

## Good Example (✅)
### 🔧 기본 기능
| 기능 | 설명 |
|------|------|
| 이름 변경 | 에이전트 이름을 자유롭게 변경할 수 있어요 |
| 노드 추가/연결 | 시작 노드 여러 노드를 연결하여 흐름 구성 |
| 정렬/화면 조절 | 노드 배치 정렬, 화면 확대/축소 가능 |
| Undo/Redo | 이전/다음 작업으로 되돌리기 가능 |

### 📌 변수 사용 규칙
- 사용 형식: `{변수명}`, AI 출력 키는 `변수명['키']`
- **허용**: 영문, 숫자, 언더스코어(_) 조합
- **불가**: 특수문자, 공백, 숫자로 시작, 시스템 변수

> 💡 **팁**: 변수 값이 숫자인지 문자열인지 확인하세요. Tab으로 자동완성 가능!

## Input
- query: {query}
- search_result: {search_result}

노드 설정

상태 메시지: 답변을 생성중이에요

노드 출력 변수명: ai_result_3 (기본값 사용)

스트리밍 여부: 체크

응답 포맷: 텍스트

설정 예시

💡 Veluga Agent Tips**
스트리밍을 켜 주세요!** 이 노드는 사용자에게 최종 답변을 출력하는 노드이므로,
스트리밍을 활성화해서 사용자에게 답변이 출력되도록 해야 해요!

중요! 최종 사용자에게 보여주는 마지막 AI 노드의 응답 포맷은 반드시 텍스트로 설정해야 해요.
JSON 객체로 설정하면 사용자에게 JSON 데이터가 그대로 노출돼요.

Step 7. 미지원 질문 처리 (AI 호출)

사용법이 아닌 질문(예: "최신 뉴스 알려줘")이 들어왔을 때, 안내 메시지를 출력하는 노드예요.

노드 추가하기

조건 분기 노드에서 FALLBACK(그 외) 경로에 새 AI 호출 노드를 추가해요.

노드 설정하기

노드를 클릭하여 설정 패널을 열고, 아래와 같이 입력해 주세요.

일반 설정

노드 이름: 미지원 안내

AI 모델명: gpt-5-mini

시스템 프롬프트: "지원하지 않는 기능입니다"를 출력하세요.

유저 프롬프트: {query}

노드 설정

상태 메시지: 지원하지 않는 질문이에요

노드 출력 변수명: ai_result_4 (기본값 사용)

스트리밍 여부: 체크

응답 포맷: 텍스트

설정 예시

💡 Veluga Agent Tips
이 노드도 스트리밍을 켜 주세요! 이 노드도 사용자에게 최종 답변을 출력하는 노드이므로,
스트리밍을 활성화해서 사용자에게 답변이 출력되도록 해야 해요!

지원하지 않는 기능에 대한 처리도 사용자 경험과 관련이 있어요. 시스템 프롬프트를 수정해서
결과물을 향상시켜 보세요!

Step 7. 테스트

모든 노드를 추가했다면, 노드 간 연결이 올바르게 되어 있는지 확인해 주세요.

연결이 올바르다면, 테스트 기능으로 에이전트의 동작을 확인할 수 있어요.

빌더 화면 우측 테스트 버튼을 클릭해 주세요.

테스트 채팅 창이 열리면 여러 질문들을 입력해 봐요.

💡 Veluga Agent Tips
만약 노드를 잘못 연결했다면? 연결선을 더블 클릭하면 연결을 삭제할 수 있어요.
에이전트 적용 전에, 의도대로 동작하는지 테스트해서 에이전트의 성능을 향상시켜요.

에러가 발생했다면? 우측 상단 에러 버튼이 생기고, 에러가 난 노드에 경고 표시가 나타나요.
에러 버튼을 눌러 에러가 난 노드, 변수명 오타, 프롬프트 누락 등 에러 내용을 확인해 보세요.

에이전트 테스트하기

테스트 실행 중에는 에이전트의 노드들이 순서대로 강조되면서, 실제로 어떤 경로로 흐르는지 시각적으로 확인할 수 있어요.

또, 이전에 설정한 상태 메시지로 실행 흐름을 확인할 수 있어요.

💡 Veluga Agent Tips
지금 만든 에이전트를 테스트하려면 에이전트 설명서를 학습시켜야 해요!
파일이 없는 분들은 여기서 다운받으면 돼요!
블로그 링크로 학습을 진행해도 돼요.
파일과 링크를 같이 전달드릴게요

에이전트 설명서를 준비 해드릴게요. 이걸 사용해봐요.

벨루가_에이전트_설명서.pdf2.43MB

https://slashpage.com/velugadoc/d367nxm38jj932j98pv1

이제 다양한 질문들로 에이전트를 테스트해 봐요!

💡 Veluga Agent Tips
다양한 질문들로 많이 테스트하면서, 오류를 찾아 프롬프트를 수정해 봐요.
테스트하면서 다양한 설정들을 바꿔보면 챗봇을 정교하게 만들 수 있어요.

Step 8. 저장 및 활성화

테스트가 정상적으로 완료됐다면 에이전트를 최종적으로 저장하고 활성화해야 채널에 적용돼요.

우측 상단의 저장하기 버튼을 클릭해요.

에이전트 빌더 메인 화면으로 돌아가면 에이전트가 카드 형태로 나타날 거예요.

활성화 토글을 켜면 해당 채널에 에이전트가 즉시 적용돼요.

💡 Veluga Agent Tips
활성화 전의 에이전트를 저장할 경우, 팝업으로 바로 활성화(적용)할 수 있어요.
에이전트를 활성화하면 바로 챗봇으로 확인할 수 있어요.
만약 적용이 안 된다면 페이지를 새로고침하거나 채팅창을 다시 열어보세요.

에이전트 동작 원리 정리

최종 완성된 에이전트의 전체 흐름을 정리하면 다음과 같아요.

1단계: 질문 의도 분류

GPT-5가 사용자가 보낸 질문의 의도를 분석해서, 결과를 JSON으로 다음 노드에 전달해요.

•

"사용법 알려줘" → {"classification": "Tutorial"}

•

"오늘 날씨" → {"classification": "search_required"}

2단계: 질문 의도 조건 분기

classification 값이 "Tutorial"이면 문서 검색 경로로, 그 외에는 미지원 안내 경로로 이동해요.

3단계: 검색 쿼리 확장 (Tutorial 경로)

원본 질문을 의미가 비슷한 여러 개의 쿼리(검색어)로 확장해요. 이렇게 하면 문서 검색에서 관련 문서를 더 많이 찾을 수 있어요.

4단계: 문서 검색

확장한 여러 개의 쿼리로 채널의 문서를 검색하고, 유사도가 가장 높은 상위 n개 결과를 가져와요.

5단계: 최종 답변

검색한 문서 내용만을 근거로 한국어로 친절하게 답변해요. 관련 정보가 없으면 솔직하게 "관련 정보를 찾지 못했어요"라고 안내해요.

에이전트 적용 전 vs 후 비교

에이전트를 적용하면 챗봇의 답변 방식이 어떻게 달라지는지 직접 비교해 볼게요.

에이전트 적용 전 (기본 챗봇)

에이전트 없이 기본 상태의 챗봇은 사용자의 모든 질문을 같은 방식으로 처리해요.

💡 Veluga Agent Tips
벨루가의 챗봇 시스템은 기본적인 에이전트가 들어 있어 기본 성능도 좋아요!

에이전트 사용법 질의

벨루가 가격 정책 질의

기본 챗봇은 학습한 모든 문서를 기반으로 답변하기 때문에, 원하는 방향으로 커스텀할 수 없어요.

💡 Veluga Agent Tips
기본 챗봇은 RAG 방식의 챗봇으로, 학습한 모든 문서를 기반으로 답변해요.

에이전트 적용 후 (커스텀 챗봇)

에이전트를 적용하면, 질문의 의도에 따라 다른 경로로 처리해요. 즉, 원하는 답변만 할 수 있도록 커스텀할 수 있어요.

💡 Veluga Agent Tips
함께 완성한 에이전트 설명서만 답변할 수 있는 에이전트를 적용했어요.

에이전트 사용법 질의

벨루가 가격 정책 질의

이처럼 에이전트 목적에 따라서, 어떻게 의도를 분류하고, 어떤 분기 과정을 거쳐서, 어떤 형식으로 답변할지 챗봇을 코딩 없이 커스텀할 수 있는 강력한 기능을 알아봤어요.

벨루가 에이전트 빌더 소개에서도 언급하듯, 에이전트 빌더는 범용 챗봇을 위한 기능이 아니에요.

나만의, 우리 회사만의 업무 흐름을 그대로 AI로 구현하고, AI 모델, 프롬프트, 검색 방식까지 노드 단위로 세밀하게 조정할 수 있어요.

에이전트에서 정해 준 범위 안에서만 동작하기 때문에, 위 비교에서 확인한 것처럼 의도하지 않은 답변은 차단하고, 목적에 맞는 답변만 제공하도록 통제할 수 있어요.

💡 Veluga Agent Tips
벨루가 에이전트는 노드의 조합으로 원하는 기능을 구현할 수 있는 기능이에요.
코딩 지식이 없어도, 원하는 목적만 있다면 언제든 구현할 수 있어요.

활용 꿀팁

의도 분류를 더 세분화하세요. 조건 분기에 조건을 추가하면 "Tutorial" 외에도 "FAQ", "Contact" 등 다양한 의도를 나눌 수 있어요.

AI노드 하나에 너무 많은 의도를 분류하게 하지 마세요. AI노드 하나에 너무 많은 의도를 분류하면, 오히려 정확도가 떨어져요.

프롬프트를 반복해서 개선하세요. 테스트 결과가 기대와 다르다면, 시스템 프롬프트의 분류 규칙이나 답변 포맷을 수정해 보세요.

문서를 충분히 업로드하세요. 문서 검색의 품질은 채널에 업로드한 문서의 양과 질에 달려 있어요. 에이전트 목적과 관련된 문서를 충분히 올려두세요.

주기적으로 저장하세요. 에이전트가 복잡해질수록 예기치 않은 상황에 대비해서 자주 저장하는 습관을 들이세요.

에러 노드를 꼼꼼히 확인하세요. 변수명 오타, 문자와 숫자 구분 등이 주된 에러의 원인이에요.

Made with Slashpage