OpenCoach: 오래된 문서와 실제 코드를 조율하는 Sanity Context 에이전트

이 글은 Sanity Challenge, Path One: 실제 콘텐츠를 쿼리하는 에이전트 배포하기 제출물입니다.

제가 구축한 것 (What I Built)

OpenCoach는 주문 처리 시스템의 아키텍처 및 비즈니스 규칙에 대한 질문 답변 에이전트입니다. 이 에이전트는 개발자가 "데드 레터 큐(dead-letter queue, DLQ)가 어떻게 작동하나요?"와 같은 질문을 할 때, 그럴듯하지만 검증되지 않은 요약 대신 구조화되고 출처가 연결된 지식 기반의 증거를 통해 답변하는 데 도움을 줍니다.

이 문제는 문서가 시간이 지나면서 노후화될 때 특히 두드러집니다. 이전 진단에서는 재시도(retry)와 DLQ가 여전히 구현되어야 한다고 했지만, 현재 Go 코드는 데드 레터 익스체인지와 큐를 선언하고 메시지 실패 시 재큐잉 없이 거부합니다. 저는 이 두 가지 주장과 그 상태, 그리고 출처들을 Sanity에 모델링하여 에이전트가 역사적 조언과 현재 동작을 구별할 수 있도록 했습니다. 모든 일치하는 텍스트를 동등하게 최신으로 취급하는 것보다 이것이 훨씬 유용합니다.

기존의 Go 주문/결제 애플리케이션이 기반이며, 이번 콘테스트 제출물 자체가 아닙니다. 저는 이 챌린지 이전에 해당 저장소 작업을 시작했습니다. 챌린지 기간 동안 Sanity Studio 스키마와 시드 콘텐츠를 추가하고, OpenCoach를 MCP(Microservice Communication Protocol)를 통해 Sanity Context Knowledge Base에 연결했으며, 근거 기반 답변 인터페이스를 추가했습니다. 기존의 로컬 RAG 모드는 별도의 모드로 계속 사용할 수 있습니다.

데모 (Demo)

실시간 OpenCoach 데모를 사용해 보세요: OpenCoach를 열고, “Como funciona a DLQ?” (“DLQ는 어떻게 작동하나요?”)를 입력한 다음, **증거 검색(Buscar evidências)**을 클릭하세요. 응답에는 Sanity Context 모드와 그것이 사용한 지식 기반 증거가 표시됩니다. 이 정확한 질문은 배포된 앱에 대해 테스트되었습니다.

데모를 위해 로그인이 필요하지 않습니다. 백엔드는 무료 호스팅 티어에서 실행되므로 비활성 상태 이후 깨어나는 데 시간이 걸릴 수 있습니다. 상위 모델 요청이 일시적으로 503을 반환하는 경우, 기다렸다가 다시 시도해 보세요.

코드 (Code)

오픈 소스 저장소(open-source repository) [https://github.com/MarceloRodrigues1853/ada_go-desafio_pedidos]에는 Go 애플리케이션과 콘테스트 추가 내용이 포함되어 있습니다. Sanity 통합 풀 리퀘스트는 새로운 작업과 그 이력을 쉽게 검사할 수 있도록 합니다. 주요 통합 지점은 sanity/schemaTypes/, sanity/seed/, open_coach.py, rag_api.py, 그리고 frontend/src/App.tsx입니다.

Sanity 활용 방법

저는 고객이나 주문 기록이 아닌 기술적 지식을 위한 Sanity Studio를 생성했습니다. 다섯 가지 문서 유형은 비즈니스 규칙, 아키텍처 결정, 도메인 이벤트, API 엔드포인트 및 문서화 주장(documentation claims)을 모델링합니다. 콘텐츠 레코드는 코드 파일 증거를 포함하고 현재 주장을 오래된 것과 구별합니다. 역사적 DLQ 주장은 충돌하는 현재 주장을 명시적으로 참조합니다.

저는 저장소 코드를 기반으로 확인한 사실들로 Studio에 시드(seed)를 심고, 이 문서를 사용하여 Sanity Context 지식 기반을 구축했습니다. 질문이 발생할 때, OpenCoach 백엔드는 지식 기반 개요를 위해 Context MCP의 initial_context 도구를 호출합니다. Gemini 라우팅 단계가 관련 항목 경로를 선택하고; 백엔드가 knowledge_base_read로 해당 항목들을 읽어 들인 후; 두 번째 단계에서 검색된 항목들로부터 답변을 생성합니다. UI는 답변과 증거(evidence)를 노출하여 독자가 그 근거를 검사할 수 있게 합니다.

이 구조는 사용 사례의 핵심입니다: 에이전트는 어떤 주장이 현재 것인지 역사적인 것인지, 무엇이 이를 지원하는 코드인지, 그리고 어떤 주장들이 충돌하는지 알아야 합니다. 단순히 “DLQ”라는 키워드 매칭만으로는 상태를 해결하지 못한 채 오래된 진술과 새로운 진술을 모두 검색하게 됩니다.

여전히 한 가지 제한 사항이 남아 있습니다: 생성된 DLQ Knowledge Base 항목에서, 메트릭 및 모니터링에 대한 두 개의 인용 마커는 해당 세부 정보를 실제로 문서화하는 아키텍처 결정 출처가 아니라 현재의 DLQ 주장을 가리킵니다. 소스 카드 불일치(source-card mismatch)는 sanity/README.md에 기록되어 있습니다. DLQ의 존재 여부와 기본 동작은 코드를 기반으로 확인되었지만, 이 두 개의 인용 마커는 여전히 사람이 검토해야 합니다. '항목이 최신 상태임'이라는 것이 모든 생성된 인용이 정확하다는 것을 의미하지는 않습니다.

Sanity 프로젝트 상세 정보

• Sanity 프로젝트 ID: ss56mini
• 데이터셋: production
• Knowledge Base ID: kbbKnMXYLs6b
• Studio 스키마 및 시드 콘텐츠: sanity/

MCP 접근 토큰은 백엔드에 유지되며 데모나 리포지토리에 게시되지 않습니다.