Branch Agent: Git-Style Branching for LLM Conversations

개요

Branch Agent는 Git의 브랜치 모델을 LLM 대화에 적용하여, 다양한 모델, 프롬프트, 제공자를 각 병렬 타임라인에서 실험하고 관리할 수 있는 시스템입니다.

주요 내용

* 문제점: 기존 LLM 실험은 프롬프트 수정, 결과 비교, 수동 복사/붙여넣기 반복으로 비효율적이고 재현 불가능하며 버전 관리가 되지 않습니다.
* 핵심 아이디어: 대화를 목록이 아닌 트리 구조로 보고, 각 메시지를 분기점(fork point)으로 활용합니다. 새로운 브랜치는 이전 대화의 전체 컨텍스트를 O(1) 포인터 참조로 상속받으며, 각 브랜치는 독립적인 에이전트 설정(시스템 프롬프트, 모델, 제공자, 온도 등)을 가집니다. 브랜치는 나란히 비교하고 AI "Judge Agent"를 통해 병합할 수 있습니다.
* 아키텍처:
* 프론트엔드: React 19 기반의 Next.js UI가 Convex Database와 통신하며, SSE 스트림으로 실시간 대화 응답을 처리합니다.
* 백엔드: Convex Database는 워크스페이스, 브랜치, 메시지 등을 저장하며, 반응형 쿼리와 ACID 트랜잭션을 지원합니다.
* 에이전트 서비스: Python FastAPI 기반의 Agno Agent SDK를 사용하여 요청별로 에이전트를 생성하고 OpenAI 호환 API를 통해 다양한 LLM 제공자(OpenAI, Together, Groq, Ollama 등)와 연동됩니다.
* Convex 사용 이유: 반응형 쿼리(실시간 UI 업데이트), ACID 트랜잭션(원자적이고 격리된 작업), 결정론적 액션, 타입 안전성 등을 제공합니다.
* Agno 사용 이유: Python 네이티브 에이전트 프레임워크로, 여러 모델 제공자를 통합 인터페이스로 지원하고, Tool 통합, 중간 이벤트(Tool 호출, 추론 단계) 스트리밍, Pydantic 스키마를 통한 구조화된 출력을 지원합니다.
* 데이터베이스 스키마: branches 테이블은 workspaceId, name, parentBranchId, snapshotMessageId (분기점 메시지 ID), agentConfig (시스템 프롬프트, 모델, 제공자 URL, API 키, 도구, 온도 등)를 포함하며, messages 테이블은 branchId, parentMessageId, role, content 등을 저장합니다. snapshotMessageId를 통해 O(1) 스토리지가 가능합니다.
* 포크(Fork) 기능: forkBranch 뮤테이션은 새로운 브랜치를 생성하며, 이전 브랜치와 snapshotMessageId를 참조하여 메시지를 복사하지 않고 O(1) 비용으로 포크를 구현합니다.
* 히스토리 탐색: internalGetBranchHistory 쿼리는 브랜치 트리를 거슬러 올라가 parentBranchId와 snapshotMessageId를 이용하여 전체 컨텍스트를 재구성합니다.
* 스트리밍 에이전트 응답: chatWithAgent 액션은 전체 히스토리를 Python Agno 서비스로 보내고, SSE를 통해 토큰별 응답을 실시간으로 스트리밍하여 Convex 문서 업데이트를 트리거하고 프론트엔드 UI에 부드럽게 표시합니다.
* Agno Python 서비스: 각 요청마다 새로운 에이전트를 생성하여 상태 누수를 방지하며, 각 브랜치는 다른 제공자를 가리킬 수 있습니다.
* UI 비교 보기: 두 개의 브랜치를 동시에 표시하여 시스템 프롬프트나 모델 변경 사항을 비교하기 용이합니다.
* Judge Agent를 통한 병합: 브랜치의 질문이 완료되면, mergeWithJudge 액션은 두 브랜치의 히스토리를 "Judge Agent"에게 보내 핵심 학습 내용, 차이점, 인사이트를 요약하도록 하여 대상 브랜치에 시스템 메시지로 삽입합니다.
* 프로젝트 실행: Convex 백엔드, Agno Python 서비스, Next.js 프론트엔드를 각각 또는 ./start.sh 스크립트로 실행할 수 있습니다.
* 향후 확장 아이디어: Diff 보기, 프롬프트 플레이그라운드, 브랜치 내보내기/가져오기, 자동 병합 충돌 해결, 브랜치 템플릿 등을 제안합니다.
* 기술 스택: Convex (데이터베이스), Agno (Agent SDK, Python), Next.js 15 + React 19 (프론트엔드), Tailwind CSS v4 + shadcn/ui (스타일링), OpenAI 호환 API (AI 제공자).

시사점

Branch Agent는 LLM 대화의 실험, 관리, 재현성을 획기적으로 개선하며, Git과 유사한 브랜치 워크플로우를 통해 복잡한 LLM 기반 프로젝트의 개발 및 탐색을 효율화할 수 있는 실용적인 솔루션을 제공합니다.