RAGO-X API活用ガイド：社内規程アシスタントから顧客対応まで

社員がグループウェアで休暇規程を調べ、担当者が顧客の問い合わせに答え、ユーザーが製品画面でインストール方法を尋ねる。共通するのは、作業中の画面で文書に基づく答えを得たいという要望です。

RAGO-X APIは、こうした画面に文書ベースの質疑応答を組み込みます。既存サービスが認証と画面を担当し、RAGO-XはAPIキーに許可された文書キャビネットを対象にRAG Chatを処理します。

本記事は開発者メニューと外部連携APIの呼び出し構造を基にしています。業務例や質問は説明用で、特定顧客の導入実績ではありません。APIは現在Pro以上のプランで提供されます。条件は料金プランと開発者メニューをご確認ください。

質問の送信と回答の受信は別の処理です

質問送信時のHTTP応答が完成した回答とは限りません。まず処理を受け付けた task_id を受け取り、そのタスクのストリームに接続して結果を取得します。

既存サービスの画面
    ↓ 質問
自社バックエンド — ユーザー認証・キャビネット権限確認
    ↓ APIキーで質問を送信
RAGO-X API — タスク受付、task_idを返す
    ↓ タスクのSSEストリームに接続
自社バックエンド — 結果を受信し画面へ転送
    ↓
ユーザー画面 — 回答と提供された根拠を確認

キーは連携サーバーに保管し、ブラウザーには渡しません。ユーザーは既存サービスにログインして質問します。社内ポータル、顧客対応ツール、製品画面に共通する構成です。

事例1：グループウェアに社内規程アシスタントを追加

社員の質問

「半日休暇を申請するには、どのような手続きが必要ですか？」

グループウェアに質問欄を設け、人事規程のキャビネットを接続します。社員は複数の文書を開き回らず、同じ画面で関連する規程を確認できます。

接続の手順

1. 休暇規程、勤怠案内、申請手順をRAGO-Xのキャビネットに準備します。
2. そのキャビネットだけを許可したAPIキーを発行します。
3. バックエンドがログイン済み社員の質問を受け、RAG Chatを要求します。
4. タスクのストリームを受信して画面に回答を表示します。
5. 根拠が返された場合は併記し、原文を確認できるようにします。

部署や社員によって閲覧範囲が異なる場合、送信前にバックエンドで権限を確認します。APIキーの許可範囲と社員個人の閲覧権限は同じではありません。 ブラウザーから届いたキャビネットUUIDを無検証で使用しないでください。

会話も社員ごとに分けます。バックエンドでユーザー・キャビネット・会話の関係を管理し、新しい会話には固有の session_id を発行します。全社員で固定のセッションを共有しないようにします。

APIキーの準備と最初の質問

三つの事例はいずれも次のAPIを使います。

1. 開発者メニューでキーを発行

開発者 → APIキー管理で「グループウェア規程アシスタント」など目的が分かる名前を付け、必要なキャビネットだけを選びます。

有効期限と許可する送信元IP/CIDRも設定できます。固定の外向きIPを持つサーバーなら、そのアドレスで利用元を制限できます。許可アドレス一覧が空の場合、送信元制限はありません。

キーの原文は発行直後に一度だけ表示されます。サーバーのシークレット保管領域などに保存し、URL、フロントエンドコード、ブラウザーストレージには入れません。キー管理に使うログインJWTと、外部連携要求に使うAPIキーも区別します。

以下のcURLは連携サーバーまたは開発者の端末で実行します。

ランディングサイトのURLをAPIのベースURLにしないでください。接続先と最新の要求・応答形式は、利用環境の開発者 → 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キーを使います。同じ組織のキーであっても、別のキーが作成したタスクを自由に参照することはできません。

現在のストリームは接続通知の subscribed と結果通知の message イベントを使います。event: final というイベント名だけを待つ実装にはせず、message のJSON内の type と完了・エラー情報を解釈してください。

SSEは空行でイベントを区切ります。ネットワークから読んだ一片が一イベントとは限りません。バッファーに蓄積して境界ごとに処理し、接続維持用のコメント行も考慮します。

ブラウザー標準の EventSource は任意の Authorization ヘッダーを設定できません。バックエンドが認証ヘッダーを付けて受信し、フロントエンドにはサービスに適した方法で転送します。

事例2：顧客対応画面で回答の下書きを作る

担当者の質問

「配送先の変更を依頼されました。出荷状況別の案内手順を探してください。」

問い合わせの横に文書から回答案を作成するボタンを置き、顧客対応方針と業務マニュアルのキャビネットに質問します。

下書きと業務データを一緒に確認

RAGO-Xの文書は方針と手順の根拠です。現在の出荷状況など変動する情報は注文システムで確認します。API接続だけで注文の自動照会や配送先変更が行われるわけではありません。

• 既存の業務システムで注文状況を確認します。
• 必要な状況説明と質問をRAGO-Xに送ります。
• 回答と根拠を担当者に表示します。
• 担当者が実際の注文状況と方針を照合して返信を確定します。

「すでに出荷済み」という条件は質問に含められますが、不要な連絡先や決済情報まで送る必要はありません。方針判断に必要な部分だけを抽出します。

最初は自動送信よりも、担当者が編集・確定する下書き機能にすると、結果比較と運用基準の整備が容易になります。

事例3：製品画面にマニュアル検索を追加

ユーザーの質問

「初回接続で認証エラーが出ます。どの設定を確認すればよいですか？」

設定画面にヘルプ入力欄を設け、導入ガイド、トラブル対処文書、運用マニュアルのキャビネットを接続します。

製品とバージョンに合う文書を選択

製品やバージョンを分ける必要があればキャビネットを分割し、バックエンドが適切なものを選びます。本記事の質問APIの本文は session_id と question です。product_version など任意のフィールドが検索フィルターとして機能すると仮定しないでください。

質問にバージョンを書けば説明には役立ちますが、キャビネット選択や閲覧権限の制御に代わるものではありません。

根拠データが返れば併記します。フィールド形式と原文へのアクセス方法は環境の仕様に従い、公開ダウンロードURLや数値の信頼度スコアが常にあるとは考えません。根拠不足の場合は文書補充やサポートにつなげます。

三つの事例の違い

呼び出しの流れは共通です。違いは、どのキャビネットを接続し、送信前に何を確認し、どこに結果を表示するかです。

エラー時は同じ要求をすぐ繰り返さない

送信時のエラーとストリーム受信中のエラーを区別します。

無条件の再送は別タスクを重複作成する可能性があります。同じ session_id を送っても重複防止キーとして機能するとは限りません。

会話を既存サービスの対応履歴や監査画面に残す場合、保存要件は別途設計します。画面に表示されたことと業務システムへの保存は別です。

一つのキャビネットと一つの画面から始める

まず一つのキャビネットと質問画面を選び、実際の質問で回答・根拠・失敗時処理を確認してから拡張します。規程なら半日休暇、休暇承認、証明書提出、製品ヘルプなら導入段階や代表的なエラーを試します。文書に答えのない質問も確認してください。

RAGO-Xが文書ベースの質疑応答を担い、既存サービスがユーザー、権限、業務状況を管理することで役割が明確になります。

API連携の概要とAPI活用事例、RAGO-Xのアーキテクチャ、RAGのチャンキングもご覧ください。環境固有の接続情報は開発者メニューまたはサポートで確認できます。