임베딩 없이 지식 에이전트 만들기

대부분의 지식 에이전트는 같은 방식으로 시작됩니다. 벡터 데이터베이스를 고르고, 청킹(chunking) 파이프라인을 구축합니다. 임베딩 모델을 선택하고, 검색 파라미터를 튜닝합니다.

몇 주가 지나 에이전트가 틀린 답을 내놓았을 때, 어떤 청크가 검색되었는지, 왜 그 청크의 점수가 가장 높았는지 전혀 알 수 없습니다.

Vercel 위에서 에이전트를 구축하는 팀들과 내부적으로 이 패턴을 반복해서 목격했습니다. 임베딩 스택은 의미적 유사도 검색에는 잘 작동하지만, 구조화된 데이터에서 특정 값을 찾아야 할 때는 한계가 뚜렷합니다. 더 큰 문제는 실패가 조용하다는 점입니다. 에이전트는 자신 있게 잘못된 청크를 반환하고, 질문에서 답변까지의 경로를 추적할 수 없습니다.

그래서 다른 접근 방식을 시도했습니다. 벡터 파이프라인을 파일 시스템으로 대체하고, 에이전트에게 bash을 제공했습니다. 영업 통화 요약 에이전트의 건당 비용이 약 $1.00에서 약 $0.25로 떨어졌고, 출력 품질도 향상되었습니다. 에이전트가 이미 잘하는 것, 즉 파일 읽기, grep 실행, 디렉토리 탐색을 그대로 활용했을 뿐입니다.

그래서 이 아키텍처를 Vercel 위에 프로덕션 수준으로 구현한 지식 에이전트 템플릿을 오픈소스로 공개합니다.

템플릿이 하는 일

지식 에이전트 템플릿은 파일 시스템 기반의 오픈소스 에이전트로, 포크하고 커스터마이즈하여 바로 배포할 수 있습니다. GitHub 리포지토리, YouTube 트랜스크립트, 문서(예: 마크다운 파일), 커스텀 API 등 어떤 소스든 연결 가능합니다. 웹 채팅 앱, GitHub 봇, Discord 봇으로 배포할 수 있고, 세 가지를 동시에 운영할 수도 있습니다.

템플릿은 Vercel Sandbox, AI SDK, Chat SDK를 기반으로 구축되었습니다. 클릭 한 번으로 Vercel에 배포하고, 소스를 설정한 뒤 바로 질문에 답할 수 있습니다.

Vercel Sandbox를 활용한 파일 기반 검색

벡터 데이터베이스 없음. 청킹 파이프라인 없음. 임베딩 모델 없음.

에이전트는 격리된 Vercel Sandbox 안에서 grep, find, cat를 사용합니다.

동작 방식은 다음과 같습니다:

1. 관리자 인터페이스에서 소스를 추가하면 Postgres에 저장됩니다

2. Vercel Workflow를 통해 콘텐츠가 스냅샷 리포지토리에 동기화됩니다

3. 검색이 필요하면 Vercel Sandbox가 스냅샷을 로드합니다

4. 에이전트의 bash과 bash_batch 도구가 파일 시스템 명령어를 실행합니다

5. 에이전트가 선택적으로 출처를 포함한 답변을 반환합니다

결과는 결정적이고, 설명 가능하며, 빠릅니다. 에이전트가 잘못된 답을 줬을 때, 트레이스를 열면 바로 확인할 수 있습니다. grep -r "pricing" docs/를 실행하고 docs/plans/enterprise.md를 읽은 뒤 잘못된 섹션을 가져온 것입니다. 파일을 수정하거나 에이전트의 검색 전략을 조정하면 됩니다. 디버깅 전체 과정이 몇 분이면 끝납니다.

벡터 방식과 비교해 보겠습니다. 에이전트가 잘못된 청크를 반환하면, 우선 어떤 청크가 검색되었는지 파악하고, 왜 그 청크가 0.82점을 받고 정답 청크는 0.79점에 그쳤는지 분석해야 합니다. 문제가 청킹 경계에 있을 수도, 임베딩 모델에 있을 수도, 유사도 임계값에 있을 수도 있습니다. 파일 시스템 검색에서는 왜 그 청크가 선택되었는지 추측할 필요도, 검색 점수를 감으로 튜닝할 필요도 없습니다. 파이프라인이 아니라, 질문 자체를 디버깅하는 것입니다.

LLM은 이미 파일 시스템을 잘 알고 있습니다. 디렉토리를 탐색하고, 파일을 grep하고, 복잡한 코드베이스에서 상태를 관리하는 방대한 양의 코드로 훈련되었기 때문입니다. 에이전트가 코드 관련 파일 시스템 작업을 잘 수행한다면, 다른 모든 것에도 동일하게 적용할 수 있습니다. 이것이 파일 시스템 및 bash 접근 방식의 핵심 통찰입니다.

모델에게 새로운 기술을 가르치는 것이 아니라, 이미 가장 잘하는 능력을 활용하는 것입니다. 유지 보수할 임베딩 파이프라인도, 스케일링할 벡터 DB도 없습니다. 소스를 추가하고, 동기화하고, 검색하면 됩니다.

Chat SDK: 하나의 에이전트, 모든 플랫폼

에이전트의 지식 베이스는 하나, 코드베이스도 하나, 단일 소스 오브 트루스입니다. 하지만 엔지니어는 Slack에, 커뮤니티는 Discord에, 버그 리포트는 GitHub에 흩어져 있습니다. 하나의 에이전트로 세 곳을 모두 커버합니다.

Chat SDK는 사용자가 있는 모든 플랫폼에 지식 에이전트를 연결합니다. 필요한 어댑터를 불러오고, 각각을 동일한 에이전트 파이프라인에 연결하면, Chat SDK가 지원하는 모든 플랫폼에서 에이전트가 즉시 동작합니다.

Chat SDK 지식 에이전트 예시

각 어댑터는 플랫폼별 고유 사항(예: 인증, 이벤트 포맷, 메시징)을 처리하고, 에이전트 자체는 변경 없이 유지됩니다. 봇이 멘션되면 플랫폼과 관계없이 onNewMention이 실행됩니다. 에이전트가 메시지 텍스트를 받아 동일한 파일 시스템 기반 파이프라인으로 응답을 스트리밍한 후, 해당 스레드에 답변을 게시합니다.

템플릿에는 GitHub과 Discord 어댑터가 기본으로 포함되어 있으며, Chat SDK는 이미 Slack, Microsoft Teams, Google Chat 등도 지원합니다. 공식 및 커뮤니티 어댑터의 전체 목록은 어댑터 디렉토리에서 확인할 수 있습니다.

AI SDK 심층 통합

@savoir/sdk 패키지는 AI SDK 기반 에이전트나 앱을 지식 베이스에 연결하는 도구를 제공합니다. 도구를 불러오고, 클라이언트에 인스턴스 URL을 지정한 뒤, 에이전트에 도구를 전달하면 연결이 완료됩니다.

SDK의 기능을 확장하여 별도로 배포할 계획이라면, 패키지 이름을 @savoir/sdk에서 원하는 이름으로 변경하세요.

템플릿에는 스마트 복잡도 라우터도 포함되어 있습니다. 모든 질문은 복잡도에 따라 분류되어 적합한 모델로 라우팅됩니다. 단순한 질문은 빠르고 저렴한 모델로, 어려운 질문은 고성능 모델로 전달됩니다. 수동 규칙 없이 비용 최적화가 자동으로 이루어집니다.

Vercel AI Gateway를 통해 모든 AI SDK 모델 공급자와 호환됩니다.

내장 관리 도구

템플릿에는 사용량 통계, 오류 로그, 사용자 관리, 소스 설정, 콘텐츠 동기화 제어 등 완전한 관리자 인터페이스가 포함되어 있어 외부 옵저버빌리티 도구가 필요 없습니다.

AI 기반 관리 에이전트도 탑재되어 있습니다. "지난 24시간 동안 발생한 오류가 뭐야?", "사용자들이 자주 하는 질문은?" 같은 질문을 던지면, 내부 도구(query_stats, query_errors, run_sql, chart)를 활용해 직접 답변을 제공합니다. 에이전트를 에이전트로 디버깅하는 셈입니다.

시작하기

작동하는 지식 에이전트를 만드는 데 벡터 데이터베이스도, 임베딩 모델도, 청킹 파이프라인도 필요 없습니다. 파일 시스템, bash, 그리고 사용자가 이미 있는 곳에 에이전트를 배치할 수 있는 방법만 있으면 됩니다. 이것이 핵심 프리미티브입니다.

지식 에이전트 템플릿은 이 요소들을 하나로 연결해, 검색 방법이 아닌 에이전트가 무엇을 알아야 하는지에 집중할 수 있게 해줍니다.