RAGO-X API 활용하기: 사내 규정 도우미부터 고객지원까지

직원이 그룹웨어에서 휴가 규정을 찾고, 상담원이 고객 문의에 답하고, 사용자가 제품 화면에서 설치 방법을 묻습니다. 세 상황의 공통점은 업무를 하던 화면에서 문서에 근거한 답을 얻고 싶다는 것입니다.

RAGO-X API는 이런 화면에 문서 기반 질의응답을 연결할 때 사용합니다. 기존 서비스는 사용자 인증과 화면을 담당하고, RAGO-X는 API Key에 허용된 문서함을 대상으로 RAG Chat을 처리합니다.

이 글은 실제 개발자 메뉴와 외부 연동 API의 호출 구조를 바탕으로 작성했습니다. 아래 업무 사례와 질문은 활용 방법을 설명하기 위한 예시이며, 특정 고객의 도입 실적은 아닙니다. API 이용은 현재 Pro 이상 요금제에서 제공하며, 적용 조건은 요금제와 서비스의 개발자 메뉴에서 확인할 수 있습니다.

먼저 이해할 흐름: 질문 제출과 답변 수신은 별도입니다

API 연동에서는 질문을 제출한 HTTP 응답이 곧 완성된 답변이라고 가정하면 안 됩니다. 먼저 작업을 접수해 task_id를 받고, 해당 작업의 스트림에 연결해 처리 결과를 받습니다.

기존 서비스의 사용자 화면
    ↓ 질문
우리 서비스의 백엔드 — 사용자 인증·문서함 권한 확인
    ↓ API Key로 질문 제출
RAGO-X API — 작업 접수 및 task_id 반환
    ↓ 해당 작업의 SSE 스트림 연결
우리 서비스의 백엔드 — 결과 수신·업무 화면에 전달
    ↓
사용자 화면 — 답변과 제공된 근거 확인

브라우저에 RAGO-X API Key를 전달할 필요는 없습니다. 키는 연동 서버에서 보관하고, 사용자는 기존 서비스에 로그인한 상태로 질문합니다. 이 구조는 사내 포털, 고객지원 도구, 제품 화면에 동일하게 적용할 수 있습니다.

사례 1. 그룹웨어에 사내 규정 도우미 붙이기

직원이 묻는 질문

“반차를 신청할 때 어떤 절차를 따라야 하나요?”

그룹웨어에 질문 입력창을 두고 인사 규정 문서함을 연결합니다. 직원은 메뉴를 돌아다니며 여러 문서를 열어보는 대신, 질문과 관련된 규정 설명을 같은 화면에서 확인합니다.

이렇게 연결합니다

1. 휴가 규정, 근태 안내, 신청 절차 문서를 RAGO-X 문서함에 준비합니다.
2. 해당 문서함만 허용한 API Key를 발급합니다.
3. 그룹웨어 백엔드는 로그인한 직원의 질문을 받아 RAG Chat을 요청합니다.
4. 작업의 스트림을 받아 그룹웨어 화면에 답변을 표시합니다.
5. 반환된 근거가 있으면 답변과 함께 보여주어 규정의 원문을 확인할 수 있게 합니다.

부서나 사용자에 따라 열람 가능한 규정이 다르다면, 질문을 보내기 전에 그룹웨어 백엔드에서 권한을 확인해야 합니다. API Key에 허용된 문서함 범위와 개별 직원의 열람 권한은 같은 개념이 아닙니다. 브라우저가 보내온 문서함 UUID를 검증 없이 그대로 사용하지 마세요.

직원별 대화도 구분합니다. 백엔드에서 사용자·문서함·대화의 관계를 관리하고, 새 대화에는 고유한 session_id를 부여합니다. 여러 직원이 하나의 고정 세션 값을 공유하지 않도록 구성합니다.

API Key를 준비하고 첫 질문 보내기

세 사례 모두 아래 세 API로 기본 흐름을 만들 수 있습니다.

1. 개발자 메뉴에서 키 발급하기

RAGO-X의 개발자 → API Key 관리에서 연동 목적을 식별할 수 있는 이름을 입력합니다. 예를 들어 그룹웨어 규정 도우미처럼 이름을 정하고, 필요한 문서함만 선택합니다.

만료일과 허용 출발지 IP/CIDR도 설정할 수 있습니다. 고정 출구 IP를 사용하는 서버라면 그 주소를 등록해 키를 사용할 수 있는 출발지를 제한할 수 있습니다. 허용 주소 목록이 비어 있으면 출발지 제한이 없는 상태입니다.

키 원문은 발급 직후 한 번만 표시됩니다. 서버의 시크릿 저장소 등에 보관하고, URL·프런트엔드 코드·브라우저 저장소에는 넣지 않습니다. API Key 관리 요청에 사용하는 로그인 JWT와 외부 연동 요청에 사용하는 API Key도 구분합니다.

아래 cURL 예제는 연동 서버 또는 개발자의 터미널에서 실행합니다. 환경 변수에는 다음 값을 준비합니다.

랜딩 사이트 주소를 API 기본 주소로 사용하지 마세요. 실제 접속 주소와 최신 요청·응답 형식은 이용 환경의 개발자 → API 사용 안내를 기준으로 설정합니다.

2. 키에 허용된 문서함 조회하기

curl --fail-with-body --request GET \
  --url "${RAGO_X_API_BASE_URL}/api/v2/integrations/cabinets" \
  --header "Authorization: Bearer ${RAGO_X_API_KEY}"

문서함 목록은 응답의 data.items에서 확인합니다. 각 항목에는 cabinet_uuid와 name이 포함됩니다. 사용할 문서함의 UUID를 CABINET_UUID에 설정합니다.

문서함 목록이 비어 있다면 질문을 보내기 전에 키의 허용 문서함 설정을 확인합니다. 서버에서 사용할 문서함을 명시적으로 선택하고, 단순히 목록의 첫 항목을 사용하지 않는 편이 좋습니다.

3. 질문을 제출하고 작업 ID 받기

curl --fail-with-body --request POST \
  --url "${RAGO_X_API_BASE_URL}/api/v2/integrations/cabinets/${CABINET_UUID}/rag-chat" \
  --header "Authorization: Bearer ${RAGO_X_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "session_id": "hr-demo-conversation-001",
    "question": "반차를 신청할 때 어떤 절차를 따라야 하나요?"
  }'

session_id는 대화를 구분하는 값이고 question은 질문입니다. 예제의 고정 세션 값은 한 사람이 호출 흐름을 확인하기 위한 값입니다. 실제 서비스에서는 백엔드가 발급한 대화 ID로 교체합니다.

응답에 반환된 task_id를 TASK_ID로 설정합니다. 작업 접수 성공과 답변 생성 완료는 구분해서 처리해야 합니다. 접수 후에는 화면에 처리 중 상태를 보여주고 스트림 연결을 시작합니다.

4. SSE 스트림으로 결과 받기

curl --fail-with-body --no-buffer --request GET \
  --url "${RAGO_X_API_BASE_URL}/api/v2/integrations/rag-chat/${TASK_ID}/stream" \
  --header "Authorization: Bearer ${RAGO_X_API_KEY}" \
  --header "Accept: text/event-stream"

스트림 조회에도 질문을 제출한 동일한 API Key를 사용합니다. 같은 조직에서 발급했더라도 다른 키로 만든 작업을 임의로 조회하는 방식은 지원하지 않습니다.

현재 스트림은 연결을 알리는 subscribed 이벤트와 결과를 전달하는 message 이벤트를 사용합니다. 따라서 event: final이라는 SSE 이벤트 이름만 기다리는 방식으로 구현하지 않습니다. message의 JSON 데이터 안에 있는 type과 완료·오류 정보를 해석해야 합니다.

SSE는 빈 줄로 이벤트를 구분합니다. 네트워크에서 읽은 데이터 조각 하나가 이벤트 하나와 일치한다고 가정하지 말고, 버퍼에 누적한 뒤 이벤트 단위로 나누어 처리합니다. 연결 유지를 위한 주석 줄도 올 수 있습니다.

브라우저의 기본 EventSource는 임의의 Authorization 헤더를 지정하는 용도로 사용할 수 없습니다. RAGO-X 스트림은 백엔드가 인증 헤더를 붙여 수신하고, 프런트엔드에는 서비스에 맞는 전달 방식을 제공합니다.

사례 2. 고객지원 화면에서 답변 초안 만들기

상담원이 묻는 질문

“고객이 배송지 변경을 요청했습니다. 출고 상태별 안내 절차를 찾아주세요.”

상담원이 문의 내용을 읽는 화면 옆에 문서 기반 답변 초안 버튼을 둡니다. 버튼을 누르면 고객지원 정책과 운영 매뉴얼을 담은 문서함에 질문을 보냅니다.

초안과 업무 데이터를 함께 검토합니다

RAGO-X에 넣은 문서는 정책과 절차의 근거입니다. 현재 주문의 출고 여부처럼 실시간으로 바뀌는 상태는 기존 주문 시스템에서 확인합니다. API를 연결했다는 이유만으로 RAGO-X가 주문 상태를 자동 조회하거나 배송지를 변경하는 것은 아닙니다.

상담 화면에서는 다음 흐름을 구성할 수 있습니다.

• 기존 업무 시스템에서 주문 상태를 확인합니다.
• 필요한 상황 설명과 질문을 RAGO-X로 전달합니다.
• 반환된 답변과 근거를 상담원에게 보여줍니다.
• 상담원이 실제 주문 상태와 정책을 대조한 뒤 답변을 확정합니다.

예를 들어 “이미 출고된 주문”이라는 조건을 질문에 포함할 수 있습니다. 이때 답변에 불필요한 연락처나 결제정보까지 함께 보낼 필요는 없습니다. 문의에서 정책 판단에 필요한 부분을 추려 전달합니다.

처음에는 고객에게 곧바로 자동 발송하는 기능보다, 상담원이 편집·확정하는 초안 기능으로 시작하면 결과를 비교하고 운영 기준을 정하기 쉽습니다.

사례 3. 제품 화면 안에 매뉴얼 검색 넣기

사용자가 묻는 질문

“처음 연결할 때 인증 오류가 나는데 어떤 설정을 확인해야 하나요?”

설정 화면에 도움말 입력창을 추가하고 설치 가이드, 오류 해결 문서, 운영 매뉴얼을 담은 문서함을 연결합니다. 사용자는 작업하던 화면을 벗어나지 않고 질문할 수 있습니다.

제품과 버전에 맞는 문서를 선택합니다

서로 다른 제품이나 버전의 문서를 구분해야 한다면 문서함을 나누고, 서비스 백엔드가 현재 제품에 해당하는 문서함을 선택합니다. 이 글에서 사용하는 질문 API의 요청 본문은 session_id와 question입니다. product_version 같은 임의의 필터 필드를 추가하면 적용될 것이라고 가정하지 않습니다.

질문에 제품 버전을 적는 것은 설명에 도움이 될 수 있지만, 문서함을 선택하거나 열람 권한을 제한하는 기능을 대신하지는 않습니다.

답변에 근거 데이터가 포함되어 있으면 함께 표시합니다. 근거 필드의 세부 형식과 원문 접근 방식은 이용 환경의 응답 명세에 맞추고, 모든 응답에 공개 다운로드 URL이나 숫자형 신뢰도 점수가 있다고 가정하지 않습니다. 근거가 부족하면 문서를 보완하거나 지원 채널로 연결할 수 있도록 화면을 구성합니다.

세 사례를 서비스에 적용할 때의 차이

API 호출의 기본 흐름은 같습니다. 차이는 어떤 문서함을 연결하고, 질문 전에 무엇을 확인하며, 결과를 어디에 보여줄 것인가에 있습니다.

실패했을 때는 같은 요청부터 반복하지 마세요

작업 제출 단계의 오류와 스트림 수신 중 오류를 나누어 처리합니다.

질문 제출을 무조건 반복하면 별도 작업이 중복 생성될 수 있습니다. session_id를 동일하게 보냈다고 해서 중복 요청 방지 키로 동작한다고 가정하지 않습니다.

대화 기록을 기존 서비스의 상담 이력이나 감사 화면에 남겨야 한다면 그 저장 요구사항도 별도로 설계합니다. 화면에 답변이 나타났다는 사실만으로 기존 업무 시스템에 기록이 보존되는 것은 아닙니다.

한 문서함, 한 화면부터 시작하기

첫 연동에서는 사용할 문서함 하나와 질문을 입력할 화면 하나를 정하는 것으로 충분합니다. 실제 업무 질문을 모아 답변·근거·실패 처리를 확인한 뒤 연결 범위를 넓힙니다.

예를 들어 인사 규정 도우미라면 “반차 신청”, “휴가 승인”, “증빙 제출”처럼 자주 묻는 질문부터 확인할 수 있습니다. 제품 도움말이라면 설치 단계별 질문과 대표 오류 메시지를 먼저 점검합니다. 문서에 답이 없는 질문도 포함해 결과가 어떻게 표시되는지 살펴보세요.

API의 가치는 기존 업무 흐름 안에 필요한 지식을 연결하는 데 있습니다. RAGO-X는 문서 기반 질의응답을 담당하고, 연동 서비스는 사용자·권한·업무 상태를 이해하는 역할을 맡으면 적용 범위가 명확해집니다.

RAGO-X API 연동 개요와 API 활용 사례에서 연결 방향을 살펴보세요. 문서가 답변으로 이어지는 원리가 궁금하다면 RAGO-X 아키텍처, 검색 단위를 준비하는 방법은 RAG 청킹을 참고할 수 있습니다. 이용 환경의 API 접속 정보는 개발자 메뉴 또는 고객지원에서 확인하세요.