How to Build a RAG Chat Agent with One Document Search API

This reference integration adds private knowledge chat to an existing document SaaS called KnowledgeBox. KnowledgeBox already indexes files and enforces workspace permissions. It provisions its search API documentation into AgentChat, creates a tenant-scoped session, and lets AgentChat decide when and how to retrieve evidence.

KnowledgeBox does not upload its document database to AgentChat and does not rebuild retrieval as a custom model tool. Its own search API remains the only service that can read indexed customer content.

Step 1: define the KnowledgeBox search contract

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"
}

The API validates the injected user credential and filters by authorized workspace before retrieval. It returns compact passages and citation fields, not complete private documents. A second read endpoint can return a specific section when the agent needs more context.

Step 2: register the complete search instructions in 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."
  }'

The returned document UUID is saved in KnowledgeBox configuration. The full document content is included in chats that attach it, so the agent knows the request and citation rules before it calls the search API.

Step 3: create a workspace-scoped RAG session

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 creates a separate AgentChat session for each user conversation. The same search document is reused, but each session receives different write-only headers. The model sees the API contract and workspace name in the prompt; it never sees the bearer token.

Step 4: send the user question

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 returns processing immediately. During the run, the agent calls POST https://knowledge.example.com/v1/search through http_request. AgentChat matches the hostname and injects the workspace headers before sending the request.

The actual retrieval sequence

1. Search for customer data removal and backup deletion policy.
2. Inspect titles, sections, scores, and passages returned by KnowledgeBox.
3. If backup behavior is incomplete, run a second focused search for backup retention and restoration.
4. Optionally read one specific section by ID rather than retrieving a complete document.
5. Compose an answer that distinguishes immediate primary-data deletion from scheduled backup expiration.
6. Include the source title and source URL returned by the API.

Search calls from one model response may run concurrently. If the second query depends on interpreting the first result, it must happen in a later model turn. AgentChat persists each tool result, so the final answer is grounded in the exact passages the agent received.

Step 5: render chat progress in KnowledgeBox

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

KnowledgeBox polls through its backend once per second. It merges rows by message ID and accepts an update only when revision increases. Tool messages can be shown as compact “Searching workspace knowledge” activity, while assistant content appears progressively from the durable database-backed message row.

The final answer remains part of AgentChat history. The cited source URLs point back to KnowledgeBox, where the normal document viewer checks the current user’s permission before opening the source.

Why this is an AgentChat integration rather than a generic RAG demo

• The search contract is provisioned through /api/api-documents and attached by document UUID.
• The selected model, prompt, limits, and API permissions belong to the AgentChat session.
• Retrieval is executed by the built-in HTTP tool instead of a custom search tool compiled into the agent.
• User identity is injected by host-specific session headers and never disclosed to the model.
• The KnowledgeBox client consumes durable messages with after_id and after_revision cursors.
• Stops, recoverable errors, and max-turn pauses can resume through the AgentChat continue endpoint.

Production tests for this integration