하나의 문서 검색 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로 연결되며, 일반 문서 뷰어는 소스를 열기 전에 현재 사용자의 권한을 확인합니다.

이것이 일반적인 RAG 데모가 아니라 AgentChat 통합인 이유

• 검색 계약은 /api/api-documents를 통해 프로비저닝되고 문서 UUID로 연결됩니다.
• 선택한 모델, 프롬프트, 제한 사항 및 API 권한은 AgentChat 세션에 속합니다.
• 검색은 에이전트에 컴파일된 사용자 지정 검색 도구가 아니라 기본 제공 HTTP 도구를 통해 실행됩니다.
• 사용자 ID는 호스트별 세션 헤더를 통해 주입되며 모델에 절대 공개되지 않습니다.
• KnowledgeBox 클라이언트는 after_id 및 after_revision 커서를 사용하여 영속 메시지를 소비합니다.
• 중지, 복구 가능한 오류 및 최대 턴 수로 인한 일시 중지는 AgentChat continue 엔드포인트를 통해 재개할 수 있습니다.

이 통합을 위한 프로덕션 테스트