1つのドキュメント検索APIでRAGチャットエージェントを構築する方法

このリファレンス統合は、KnowledgeBoxという既存のドキュメントSaaSにプライベートナレッジチャットを追加します。KnowledgeBoxはすでにファイルのインデックス作成とワークスペース権限の適用を行っています。検索APIのドキュメントをAgentChatにプロビジョニングし、テナント単位のセッションを作成して、証拠をいつ、どのように取得するかをAgentChatに判断させます。

KnowledgeBox は文書データベースを AgentChat にアップロードせず、カスタムモデルツールとして検索を再構築することもありません。インデックス化された顧客コンテンツを読み取れるサービスは、引き続き独自の検索 API のみです。

ステップ 1: KnowledgeBox の検索契約を定義する

POST /v1/search
{
  "query": "How long are audit logs retained?",
  "limit": 8,
  "filters": { "collection_ids": ["security"] }
}

→ {
  "results": [
    { "document_id": "doc_42", "title": "Security Policy", "section": "Audit retention", "text": "Audit logs are retained for...", "score": 0.91, "source_url": "/documents/doc_42#audit-retention" }
  ],
  "query_id": "qry_88"
}

API は注入されたユーザー認証情報を検証し、検索前に承認済みのワークスペースで絞り込みます。完全な非公開文書ではなく、簡潔な抜粋と引用フィールドを返します。エージェントがより多くのコンテキストを必要とする場合は、2 つ目の読み取りエンドポイントで特定のセクションを返せます。

ステップ 2: 完全な検索手順を AgentChat に登録する

curl -X POST "$AGENT_CHAT_URL/api/api-documents" 
  -H "Authorization: Bearer ac_live_AGENT_CHAT_KEY" 
  -H "Content-Type: application/json" 
  --data '{
    "title": "KnowledgeBox Search API",
    "description": "Search authorized workspace documents and return citable passages.",
    "content": "# KnowledgeBox Search API\nBase URL: https://knowledge.example.com/v1\n\nUse POST /search before answering questions about workspace knowledge. Send a focused natural-language query. Results are already permission-filtered. Cite title, section, and source_url. If results are weak, reformulate once. If results remain empty, say the documents do not contain the answer. Never claim a fact that is not supported by a returned passage.\n\nPOST /search body: query string required; limit integer 1-10; filters.collection_ids optional. Response results contain document_id, title, section, text, score, source_url.\n\nGET /documents/{document_id}/sections/{section_id} reads one authorized section when a search passage is incomplete."
  }'

返されたドキュメント UUID は KnowledgeBox の設定に保存されます。そのドキュメントを添付したチャットには完全なドキュメント内容が含まれるため、エージェントは検索 API を呼び出す前に、リクエストと引用のルールを把握できます。

ステップ 3: ワークスペース単位の RAG セッションを作成する

POST /api/agent/sessions
Authorization: Bearer ac_live_AGENT_CHAT_KEY
Content-Type: application/json

{
  "title": "Workspace ws_17 knowledge assistant",
  "llm_config_id": "llm_config_uuid",
  "api_document_ids": ["knowledge_search_doc_uuid"],
  "system_prompt": "Answer from retrieved workspace evidence. Include source title and URL for factual claims.",
  "max_turns": 12,
  "host_headers": [
    { "host": "knowledge.example.com", "header_key": "Authorization", "header_value": "Bearer short_lived_workspace_user_token" },
    { "host": "knowledge.example.com", "header_key": "X-Workspace-ID", "header_value": "ws_17" }
  ]
}

KnowledgeBox はユーザーの会話ごとに個別の AgentChat セッションを作成します。同じ検索ドキュメントが再利用されますが、各セッションには異なる書き込み専用ヘッダーが付与されます。モデルはプロンプト内の API コントラクトとワークスペース名を認識しますが、ベアラートークンを目にすることはありません。

ステップ 4：ユーザーの質問を送信する

POST /api/agent/sessions/session_uuid/chat
Authorization: Bearer ac_live_AGENT_CHAT_KEY
Content-Type: application/json

{ "message": "Can customer data be removed from backups immediately? Please cite the policy." }

AgentChat は直ちに処理中の状態を返します。実行中、エージェントは http_request を介して POST https://knowledge.example.com/v1/search を呼び出します。AgentChat はホスト名を照合し、リクエストを送信する前にワークスペースヘッダーを挿入します。

実際の検索シーケンス

1. 顧客データの削除とバックアップ削除ポリシーを検索する。
2. KnowledgeBox が返したタイトル、セクション、スコア、抜粋を確認する。
3. バックアップの動作に不十分な点がある場合は、バックアップの保持と復元について、焦点を絞った 2 回目の検索を実行する。
4. 完全なドキュメントを取得する代わりに、必要に応じて ID で特定の 1 セクションを読み取る。
5. プライマリデータの即時削除と、スケジュールに基づくバックアップの有効期限切れを区別した回答を作成する。
6. API が返すソースタイトルとソース URL を含めます。

1 回のモデル応答からの検索呼び出しは同時に実行される場合があります。2 つ目のクエリが 1 つ目の結果の解釈に依存する場合は、後続のモデルターンで実行する必要があります。AgentChat は各ツール結果を永続化するため、最終回答はエージェントが受け取った正確な箇所に基づきます。

ステップ 5: KnowledgeBox でチャットの進行状況を表示する

GET /api/agent/sessions/session_uuid/messages?after_id=&after_revision=0
Authorization: Bearer ac_live_AGENT_CHAT_KEY

KnowledgeBox はバックエンド経由で毎秒 1 回ポーリングします。メッセージ ID ごとに行をマージし、リビジョンが増加した場合にのみ更新を受け入れます。ツールメッセージは「ワークスペースのナレッジを検索中」という簡潔なアクティビティとして表示でき、アシスタントのコンテンツは、永続的なデータベースを基盤とするメッセージ行から段階的に表示されます。

最終回答は AgentChat の履歴の一部として残ります。引用されたソース URL は KnowledgeBox に戻るリンクであり、通常のドキュメントビューアーがソースを開く前に現在のユーザーの権限を確認します。

これが汎用的な RAG デモではなく AgentChat 統合である理由

• 検索コントラクトは /api/api-documents を通じてプロビジョニングされ、ドキュメント UUID で関連付けられます。
• 選択されたモデル、プロンプト、制限、API 権限は AgentChat セッションに属します。
• 検索取得は、エージェントにコンパイルされたカスタム検索ツールではなく、組み込みの HTTP ツールによって実行されます。
• ユーザー ID はホスト固有のセッションヘッダーによって注入され、モデルに開示されることはありません。
• KnowledgeBox クライアントは、after_id と after_revision のカーソルを使用して永続メッセージを消費します。
• 停止、回復可能なエラー、最大ターン数による一時停止は、AgentChat の continue エンドポイントを通じて再開できます。

この統合の本番環境テスト