AGENIX 시작 가이드

고객사 관리자를 위한 완전한 사용 안내서입니다.

✅ 온보딩 체크리스트 — 제대로 된 AI 에이전트 만들기

AGENIX 챗봇의 품질은 딱 세 가지가 결정합니다 — ① Tool API(실시간·개인화), ② RAG 문서(회사 지식), ③ FAQ(즉답). 이 세 가지가 제대로 세팅돼야 "그냥 챗봇"이 아니라 진짜 AI 에이전트가 됩니다. 아래 순서대로 준비하세요.

① Tool API — 3대 필수 요건

Tool API는 챗봇이 고객사 시스템을 직접 호출해 실시간 데이터로 답하게 합니다. 단, 아래 3가지 요건을 만족해야 정상 동작합니다. 하나라도 어긋나면 도구가 겉돕니다.

{
  "found": true,
  "status": "배송중",
  "carrier": "CJ대한통운",
  "eta": "2026-07-05"
}

<div>배송중입니다 (CJ)</div>

또는  "배송중, CJ, 7/5 도착"

<script src="https://agenix.kr/sdk/v1/agent.js"
  data-site-id="your-site-id"
  data-api-key="sk-..."
  data-user-token="user_10023">   <!-- 로그인 사용자 식별자 -->
</script>

# AGENIX가 보내는 요청
POST https://your-api.com/tools/get_my_orders
Headers:
  X-Tool-API-Key: your-secret-key
  X-User-Token:   user_10023      # ← 로그인 사용자
Body: { }

# 고객사 API 처리
user_id = request.headers["X-User-Token"]   # user_10023
orders  = db.find_orders(user_id)           # 그 사람 주문만
return { "found": true, "orders": orders }

② RAG 문서 — 청킹 가이드

업로드한 문서는 여러 조각(청크)으로 잘려 저장되고, 질문이 오면 AI가 관련 조각만 찾아 근거로 답합니다. 그래서 "어떻게 쓰고 나누느냐"가 답변 품질을 좌우합니다.

권장 문서 구조 예시

## 배송 정책
- 무료배송: 3만원 이상 주문
- 배송기간: 결제 후 2~3영업일 (도서산간 +1~2일)
- 배송비: 3,000원 (3만원 미만)

## 반품 / 교환 정책
반품(=교환=취소)은 상품 수령 후 7일 이내 신청 가능합니다.
- 단순 변심: 왕복 배송비 5,000원 고객 부담
- 상품 하자: 배송비 무료, 전액 환불
- 환불 처리: 반품 확인 후 영업일 3일 이내

## 적립금 사용
1,000원 이상부터 결제 화면에서 사용 가능합니다...

③ FAQ — 작성 팁

FAQ는 자주 묻는 고정 질문에 대해 문서 검색보다 빠르고 정확하게 즉답합니다. 배송비·영업시간·환불규정처럼 답이 정해진 질문에 최적입니다.

• 고객이 실제 쓰는 표현으로 질문을 등록하세요. "배송 얼마나 걸려요?" / "언제 와요?"
• 키워드 필드에 동의어·변형을 넣으면 매칭률이 올라갑니다 (배송, 배달, 언제, 도착)
• 겹치는 FAQ가 있으면 우선순위로 어떤 답을 먼저 쓸지 조정
• 답변은 짧고 완결되게. 필요한 정보를 한 번에 담기
• 정책이 바뀌면 FAQ부터 갱신 (가장 먼저 노출되는 답)

④ 시스템 프롬프트 — 페르소나로 '범위' 한정

사이트 설정의 시스템 프롬프트(페르소나)는 챗봇의 역할과 '어디까지 답할지'를 정합니다. 위 3가지(Tool·RAG·FAQ)가 "무엇을 아느냐"라면, 페르소나는 "어떻게·어디까지 답하느냐"를 잡는 안전장치예요. 잘 쓰면 엉뚱한 주제(투자 추천·타사 서비스·법률/의료 자문 등)에 헛소리하지 않고 우리 서비스 범위 안에서만 답합니다.

• 제공되는 도메인 프리셋 프롬프트를 기반으로 회사명·톤·다루는 업무를 채우세요
• 범위 명시: "우리 회사·서비스 관련 문의만 답하고, 범위 밖이거나 확실하지 않은 것은 지어내지 말 것"
• 모를 때 행동 지정: "모르는 문의는 담당자 연결(또는 고객센터 번호)을 안내"
• 금지 주제가 있으면 명시 (예: 투자·종목 추천, 타사 비교, 의료 진단 등)

🧭 어디에 넣어야 할까? (3계층 역할)

✅ 최종 점검 체크리스트

👤 계정 설정

👥 팀원 관리

한 회사에서 여러 담당자가 함께 관리자 콘솔을 사용할 수 있습니다. 좌측 팀원 관리 메뉴에서 팀원을 초대·관리합니다.

⚙️ 사이트 설정

사이트 설정은 챗봇의 동작 방식, AI 모델, 응답 스타일을 결정합니다.

당신은 [브랜드명] 쇼핑몰의 친절한 AI 상담사입니다.
반드시 한국어로만 답변하세요.

[역할]
고객의 주문, 배송, 환불/교환 문의를 처리합니다.

[행동 규칙]
- 주문 조회 시 실제 데이터를 확인한 후 답변하세요
- 확인이 필요한 사항은 "확인 후 안내드리겠습니다"라고 답하세요
- 해결이 어려운 경우 고객센터 연결을 안내하세요

💬 위젯 설치

위젯 설치는 HTML에 스크립트 한 줄을 추가하는 것으로 완료됩니다.

<script
  src="https://agenix.kr/sdk/v1/chatbot.js"
  data-site-id="your-site-id"
  data-api-key="YOUR_API_KEY"
  data-user-token="">
  <!-- data-user-token: 로그인 연동 시 사용자 토큰 입력 (미사용 시 빈값) -->
</script>

<script
  src="https://agenix.kr/sdk/v1/agent.js"
  data-site-id="your-site-id"
  data-api-key="YOUR_API_KEY"
  data-user-token="">
  <!-- data-user-token: 로그인 연동 시 사용자 토큰 입력 (미사용 시 빈값) -->
</script>

📄 문서 업로드 (RAG)

PDF, TXT, DOCX 파일을 업로드하면 AI가 문서 내용을 학습하여 답변에 활용합니다. Tool API 미등록 시 문서 기반으로 답변합니다.

🔗 Tool API 연동Business↑

Tool API를 등록하면 AI가 고객 질문에 따라 자동으로 외부 API를 호출하여 실시간 데이터로 답변합니다.

POST https://your-api.com/tools/search_order
Headers:
  X-Tool-API-Key: your-secret-key
  Content-Type: application/json

Body:
{
  "order_number": "ORD-20240101-0001"
}

{
  "found": true,
  "order_number": "ORD-20240101-0001",
  "status": "배송중",
  "carrier": "CJ대한통운",
  "tracking_number": "1234567890",
  "estimated_arrival": "2024-01-03"
}

헤더명: X-Tool-API-Key
키값: your-secret-key

🎨 위젯 커스터마이징

챗봇 위젯의 디자인과 브랜드를 자유롭게 커스터마이징할 수 있습니다. 사이트 설정 우측 패널에서 실시간 미리보기와 함께 설정합니다.

주문 조회
배송 문의
교환/반품
회원 혜택

💬 위젯 기본설정

챗봇의 첫 인상과 운영 방식을 세밀하게 제어할 수 있습니다.

쇼핑몰: "안녕하세요! 무엇이든 도와드릴게요 😊"
병원:   "안녕하세요. 진료 예약 및 문의를 도와드립니다."
사내:   "IT 헬프데스크입니다. 어떤 문제가 발생했나요?"

현재 운영시간(평일 09:00~18:00)이 아닙니다.
운영시간 내에 다시 문의해 주시거나,
고객센터(1234-5678)로 연락해 주세요.

✍️ 프롬프트 설정

시스템 프롬프트는 AI의 성격, 역할, 답변 스타일을 결정합니다.

📊 통계 / 대화 로그

🔍 로그 검색 & 내보내기Business↑

대화 로그를 키워드·날짜·감정별로 검색하고 Excel 또는 PDF 분석 리포트로 내보낼 수 있습니다.

🧩 처리 과정 보기Business↑

챗봇이 왜 그렇게 답변했는지 단계별로 추적할 수 있습니다. 답변이 이상하거나 의도와 다르게 나왔을 때, 어느 단계에서 무슨 일이 있었는지 직접 확인하고 원인을 파악할 수 있습니다.

💬 FAQ 관리Starter↑

자주 묻는 질문을 등록하면 챗봇이 LLM을 호출하지 않고 즉시 등록된 답변을 반환합니다. 응답 속도가 빠르고 LLM API 비용이 발생하지 않습니다.

질문: 배송은 얼마나 걸리나요?
답변: 주문 후 1-3 영업일 이내 출고되며, 출고 후 1-2일 내 도착합니다.
      제주/도서 지역은 추가 2-3일이 소요될 수 있습니다.
키워드: 배송, 배달, 언제 와요, 도착
우선순위: 10

🚫 블랙리스트 필터Starter↑

욕설·스팸 키워드 또는 특정 IP를 등록하면 LLM 호출 전에 차단하고 안내 메시지를 반환합니다.

🧠 AI 대화 분석Business↑

고객과의 대화를 AI가 자동으로 분석합니다. 별도 설정 없이 대화가 완료되면 자동으로 분석이 실행됩니다.

📈 비즈니스 임팩트Business↑

Tool API 호출이 실제 비즈니스 성과(예약 완료, 환불 접수, 구매 전환 등)로 이어진 횟수를 추적합니다.

🔬 A/B 테스트Business↑

두 가지 시스템 프롬프트를 동시에 운영하여 어느 쪽이 더 효과적인지 비교합니다.

🔔 웹훅 알림Business↑

특정 키워드가 감지되면 Slack, Discord, 카카오워크 등으로 실시간 알림을 보냅니다.

환불, 화나다, 최악, 소송, 불량, 짜증, 환불해, 신고

💳 구독 / 결제

🔐 계정 보안

비밀번호 변경 및 찾기 기능을 안내합니다.

🧭 지식 배치 전략 — FAQ · 문서 · Tool

챗봇은 가드레일 → FAQ → 문서(RAG) → Tool API → AI 생성 순으로 답을 찾습니다. 같은 지식을 여러 곳에 중복해서 넣기보다, 성격에 맞는 위치에 넣어야 정확도와 비용이 최적화됩니다.

🧪 Tool 테스트 시뮬레이터

Tool API를 등록한 뒤, 실제 고객에게 공개하기 전에 어떤 메시지에 어떤 Tool이 작동하는지 미리 확인할 수 있습니다.Tool API 관리 페이지 하단의 시뮬레이터를 사용하세요. (Tool API 사용 가능 플랜 전용)

📢 공지사항 & 알림

운영에 필요한 소식과 사용량 상태를 놓치지 않도록 확인하세요.

• • 좌측 공지사항 메뉴에서 서비스 점검·업데이트 소식을 확인합니다. 안 읽은 공지가 있으면 메뉴에 빨간 배지로 표시됩니다.
• • 사용량 알림 메일 — 월 요청량이 80%·100%에 도달하면 관리자 이메일로 자동 발송됩니다. 한도 초과 전에 미리 업그레이드를 검토하세요.
• • 결제 영수증 메일 — 결제·정기 갱신 시 영수증이 발송됩니다.

✉️ 1:1 문의

운영 중 궁금한 점이나 요청 사항은 콘솔에서 바로 문의하고, 답변을 한곳에서 확인할 수 있습니다.

🛠️ 문제 해결 (자주 겪는 문제)

❓ FAQ