如何僅使用一個文件搜尋 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：在 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 合約和工作區名稱，但永遠看不到 bearer 權杖。

第 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. 如果備份行為不完整，則針對備份保留和還原執行第二次聚焦搜尋。
4. 可以選擇依 ID 讀取一個特定章節，而不是擷取完整文件。
5. 撰寫一份區分主要資料立即刪除與備份依排程到期的答案。
6. 包含 API 回傳的來源標題與來源 URL。

來自同一次模型回應的搜尋呼叫可能會並行執行。如果第二個查詢取決於對第一個結果的解讀，則必須在後續的模型回合中執行。AgentChat 會持久化每個工具結果，因此最終答案是以代理程式收到的確切段落為依據。

步驟 5：在 KnowledgeBox 中呈現聊天進度

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

KnowledgeBox 每秒透過其後端輪詢一次。它會依訊息 ID 合併資料列，並且僅在修訂版本增加時接受更新。工具訊息可以顯示為簡潔的「正在搜尋工作區知識」活動，而助理內容則會根據由持久化資料庫支援的訊息資料列逐步呈現。

最終答案仍是 AgentChat 歷史記錄的一部分。引用的來源 URL 會指向 KnowledgeBox，一般文件檢視器會在開啟來源前檢查目前使用者的權限。

為什麼這是 AgentChat 整合，而不是通用的 RAG 示範

• 搜尋契約透過 /api/api-documents 進行佈建，並透過文件 UUID 附加。
• 所選模型、提示詞、限制和 API 權限屬於 AgentChat 工作階段。
• 擷取由內建 HTTP 工具執行，而不是由編譯至代理程式中的自訂搜尋工具執行。
• 使用者身分透過主機特定的工作階段標頭注入，且絕不會向模型揭露。
• KnowledgeBox 用戶端使用 after_id 和 after_revision 游標來取用持久訊息。
• 停止、可復原的錯誤，以及因達到最大回合數而暫停的工作階段，都可以透過 AgentChat continue 端點恢復。

此整合的正式環境測試