Django로 68개의 에이전트를 갖춘 로컬 우선 AI 개발 어시스턴트를 구축하며 배운 점

저는 몇 달 동안 Tlamatini (나우아틀어로 "아는 자"라는 뜻)를 구축하는 데 시간을 보냈습니다. 이는 단순한 채팅창을 훨씬 뛰어넘는, 로컬에 배포되는 AI 개발 어시스턴트입니다. Ollama를 통해 사용자의 기기에서 실행되므로 코드가 기기를 절대 떠나지 않으며, 완전한 오픈 소스(GPL-3.0)입니다.

제가 무엇을 만들었는지, 그리고 무엇을 배웠는지 공유하고 싶습니다. 1인 개발자로서 로컬 우선(local-first) AI 도구를 구축하는 과정은 예상치 못한 많은 것들을 가르쳐 주었기 때문입니다.

Tlamatini가 하는 일

대부분의 AI 코딩 어시스턴트는 클라우드 우선(cloud-first) 채팅창 형태입니다. Tlamatini는 다릅니다:

코드베이스에 대한 하이브리드 RAG (Retrieval-Augmented Generation) — Reciprocal Rank Fusion(RRF) 및 컨텍스트 예산 책정(context budgeting)을 결합한 FAISS + BM25 검색을 사용합니다. 모델은 단순히 무작위 코드 조각을 보는 것이 아니라, 컨텍스트에 맞게 순위가 매겨지고 예산이 책정된 적절한 코드를 봅니다.

75개의 도구를 갖춘 멀티 턴 (Multi-Turn) 모드 — LLM이 운영자가 됩니다. 셸 명령(Shell commands), Python 실행, 파일 작업, Playwright를 이용한 브라우저 자동화, 스크린샷, 키보드/마우스 제어, 이메일, Telegram, WhatsApp 등이 하나의 대화 내에서 모두 체인(chain)으로 연결됩니다. 사용자가 원하는 작업을 말하면, 모델이 단계를 스스로 파악합니다.

ACPX (Agent Communication Protocol eXtension) — 이 부분은 제가 가장 자랑스럽게 생각하는 부분입니다. Tlamatini는 Claude Code, Cursor, Codex, Gemini CLI, Qwen과 같은 외부 코딩 에이전트 CLI를 자식 프로세스(child processes)로 생성하고, 작업을 전달하며, 그들 사이의 출력을 중계할 수 있습니다. 하나의 오케스트레이터(orchestrator)가 여러 코딩 에이전트를 제어하며 문제의 서로 다른 부분들을 동시에 해결합니다.

시각적 워크플로 디자이너 (Visual Workflow Designer) — 68가지 에이전트 유형을 지원하는 드래그 앤 드롭 캔버스입니다. 에이전트들을 서로 연결하고, 흐름을 검증하며, 무인(unattended)으로 실행합니다. 워크플로를 .flw 파일로 저장하고, 스케줄링하며, FlowHypervisor로 모니터링할 수 있습니다.

자기 인식 아키텍처 (Self-aware architecture) — Tlamatini는 자신의 아키텍처에 대한 1인칭 지식 지도(Tlamatini.md)를 보유하고 있으며, 이는 모든 LLM 프롬프트에 주입됩니다. 따라서 자신에 대한 질문에 정확하게 답변할 수 있습니다. --self-modify와 함께 패키징된 빌드는 자신의 소스 트리를 함께 전달하여, 스스로를 읽고, 검사하고, 수정할 수 있게 합니다.

기술 스택

Backend: Python 3.12, Django 5.2, Django Channels (Daphne ASGI)
AI/ML: LangChain 0.3, LangGraph 0.2, FAISS, rank-bm25
LLM backends: Ollama (로컬 기본값), Anthropic Claude (클라우드 선택 사항), Qwen (비전)
Communication: 실시간 스트리밍을 위한 WebSockets, MCP 서비스를 위한 gRPC
Database: SQLite
Packaging: PyInstaller → 원클릭 Windows .exe 설치 프로그램

이 프로젝트를 혼자 구축하며 배운 점

1. RAG는 보기보다 어렵다

모두가 5개의 문서로 RAG (Retrieval-Augmented Generation) 데모를 보여줍니다. 하지만 수천 개의 파일, 혼합된 언어, 설정 파일, 마이그레이션(migrations), 테스트 코드가 섞여 있는 실제 코드베이스로 시도해 보십시오. 단순한 접근 방식(모든 것을 청크로 나누고, 임베딩하고, 상위 k개를 검색하는 방식)은 즉시 무너집니다.

효과적이었던 방법: 하이브리드 검색 (FAISS를 통한 밀집 벡터 (dense vectors) + BM25를 통한 희소 매칭 (sparse matching)), 순위를 결합하기 위한 상호 순위 융합 (Reciprocal Rank Fusion), 검색기가 각 청크가 어떤 파일, 클래스, 함수에 속하는지 알 수 있도록 하는 코드 인식 메타데이터 추출, 그리고 모델의 컨텍스트 창 (context window)을 절대 초과하지 않도록 하는 컨텍스트 예산 관리 (context budgeting)입니다.

2. 멀티 에이전트 오케스트레이션에는 계약 (contracts)이 필요하다

어떤 조합으로든 서로 연결될 수 있는 68개의 에이전트 유형이 있을 때는, "무엇이 무엇에 연결될 수 있는가"에 대한 공식적인 시스템이 필요합니다. 저는 에이전트 계약 (Agent Contract) 레지스트리를 구축했습니다. 각 에이전트는 자신의 연결 필드, 파라미터 소스, 비밀 경로(secret paths), 그리고 검증 규칙을 선언합니다. 플로우 컴파일러 (Flow Compiler)는 실행 전에 모든 연결을 검증합니다.

이것이 없다면 사용자는 에이전트를 잘못된 방식으로 연결하게 되고 런타임 (runtime)에 모호한 오류를 마주하게 될 것입니다. 계약이 있으면 캔버스 상의 설계 단계 (design time)에서 검증이 이루어집니다.

3. Windows에서의 프로세스 관리는 가혹하다

Tlamatini는 에이전트, ACPX CLI, 그리고 도구 실행을 위해 자식 프로세스 (child processes)를 생성합니다. Windows에서는 모든 서브프로세스 (subprocess)가 conhost.exe 동반 프로세스를 갖게 됩니다. 이들은 쌓이게 되고 부모 프로세스가 종료될 때 고아 프로세스 (orphan)가 됩니다. 사용자들은 작업 관리자에서 수십 개의 Tlamatini 아이콘 프로세스를 보게 되었습니다.

저는 3단계 고아 프로세스 수거기 (orphan reaper)를 구축했습니다: 1단계는 모든 도구 호출 (tool call) 후에 실행되고, 2단계는 LLM 응답 후에 실행되며, 3단계는 종료 시 실행됩니다. 또한, subprocess.Popen에 CREATE_NO_WINDOW를 기본값으로 설정하는 몽키 패치 (monkey-patch)를 적용하여, 향후 추가될 도구들이 별도의 수정 없이 이 해결책을 적용받을 수 있도록 했습니다.

4. 로컬 우선 (Local-first)은 제약이 아니라 기능입니다

(Claude API나 OpenAI가 아닌) Ollama를 기본값으로 설정하기로 한 결정은 제 내부에서도 논쟁의 여지가 있었습니다. 클라우드 모델들이 더 똑똑하기 때문입니다. 하지만 로컬 우선 (local-first) 방식은 다음과 같은 의미를 갖습니다: 코드가 절대 사용자의 기기를 떠나지 않으며, 기본적인 사용에 대한 API 비용이 발생하지 않고, 오프라인에서 작동하며, 특정 벤더 종속성 (vendor lock-in)이 없습니다.

클라우드 수준의 품질을 원하는 사용자들은 요청별로 선택하여 사용할 수 있습니다. 하지만 기본값은 프라이버시 중심입니다. 2026년에는 이것이 중요한 요소가 될 것입니다.

체험해보기

GitHub: github.com/XAIHT/Tlamatini
1분 데모: youtube.com/watch?v=4MyRXBahHuU
기술 스택 (Stack): Django 5 + Channels, LangChain, FAISS, Ollama. GPL-3.0.

5분 설정법: clone, pip install, migrate, runserver. 그게 전부입니다.

피드백을 환영합니다 — 특히 RAG 아키텍처 (RAG architecture)와 ACPX 멀티 에이전트 오케스트레이션 (multi-agent orchestration)에 대해 궁금합니다. 여러분이라면 무엇을 추가하시겠습니까? 무엇을 다르게 하시겠습니까?