RTGS2017/NagaAgent

A simple yet powerful agent framework for personal assistants, designed to enable intelligent interaction, multi-agent collaboration, and seamless tool integration.

NagaAgent – 데스크톱 중심의 AI 어시스턴트

무엇인가요 – NagaAgent는 오픈소스이며 크로스플랫폼 데스크톱 애플리케이션(Windows/macOS/Linux)으로, 대규모 언어모델(LLM) 채팅 인터페이스와 풍부한 "에이전트 기능" 도구를 통합한 것입니다. Python 백엔드(FastAPI, Neo4j, LiteLLM)와 Electron/Vue 프론트엔드로 구축되었으며, 과거 대화를 기억하고 외부 도구를 호출하며 Live2D 아바타를 렌더링하고, 컴퓨터를 제어(앱 실행, 웹 탐색, 게임 재생 등)할 수 있는 개인용 AI 동반자를 원하는 사용자를 대상으로 합니다.

핵심 기능 (README에 기술됨)

영역	NagaAgent의 기능
채팅 및 도구 호출	모든 OpenAI 호환 제공자 또는 Anthropic에 대응하는 스트리밍 LLM 응답. 백엔드가 파싱하고 실행하는 사용자 정의 "`tool`" JSON 블록 구문을 지원. 1턴당 최대 5회 도구 호출 루프를 지원.
메모리 (GRAG)	대화에서 주어-서술-목적어 5항조 사실을 추출하고, 로컬 및 Neo4j 그래프에 저장하며, 이후 턴에서 관련 사실을 자동으로 검색(그래프-RAG).
Live2D 아바타	마우스 움직임, 발화, 도구 이벤트에 반응하는 2D 애니메이션 캐릭터(Live2D Cubism)를 표시. 사용자는 자체 모델 디렉터리를 업로드할 수 있음.
음성	음성 합성에는 Edge-TTS(문장 단위 스트리밍), 음성 인식에는 FunASR / Qwen-Omni를 사용하며, 리프싱크로 Live2D 얼굴을 제어.
MCP 도구 프레임워크	플러그인 시스템(Model Context Protocol)으로 날씨, 시스템 런처, 게임 가이드, 웹 검색, 웹 스크래핑, Playwright 자동화, 비전, MQTT, 문서 추출 등에 대응. 재시작 없이 새로운 에이전트 추가 가능.
OpenClaw 통합	임의의 Python/Playwright 작업을 실행하고 스케줄링하며 결과를 채팅에 보고할 수 있는 로컬 "에이전트 서버".
지식 그래프 UI	Neo4j 그래프의 3D "메모리 클라우드" 시각화(노드 = 엔티티, 엣지 = 서술어). 마우스 드래그 회전, 줌, 키워드 필터링 지원.
커뮤니티 기능	내장 포럼(娜迦网络), 포인트/친화도 시스템, 커뮤니티 제작 스킬 다운로드 마켓, 배경, 음악, 캐릭터 팩 마켓.
플로팅 볼 모드	가벼운 항상 위에 표시되는 창으로, 컴팩트, 플러스, 클래식 레이아웃 간 전환 가능하여 빠른 채팅 접근 가능.
음악 플레이어	플레이리스트 지원 통합 BGM 플레이어로 TTS 리프싱크와 동기화.

빠른 시작 (README에서)

클론 및 설치

git clone https://github.com/Xxiii8322766509/NagaAgent.git
cd NagaAgent
# 프론트엔드
cd frontend && npm install && cd ..
# 백엔드 (권장)
uv sync   # 또는 venv 생성 후 pip install -r requirements.txt

설정 – config.json.example을 config.json으로 복사하고 LLM API 키(DeepSeek, OpenAI, Anthropic, Ollama 등)를 입력.
실행 – 프론트엔드 스크립트 npm run dev를 실행하면 Electron 창이 열리고 Python 서비스가 자동으로 시작됩니다.

일반적인 사용 사례

개인용 AI 동반자 – 세션 간 사용자 선호를 기억하는 스타일리시한 아바타와 대화.
도구 보강 워크플로우 – 내장된 MCP 에이전트를 통해 웹 검색, 문서 가져오기, 앱 실행, IoT 장치 제어 등을 요청.
게임 지원 – game_guide 스킬을 사용해 전략 팁 얻기, 게임 화면 자동 인식, 외부 봇(MAA 등)과 연동해 자동 플레이.
지식 관리 – 대화에서 사실을 추출해 Neo4j 그래프에 저장하고, 이후 새로운 채팅의 컨텍스트로 질의 가능.
음성 우선 상호작용 – 아시스타트에게 말하고 음성으로 응답을 듣고, 아바타에 실시간 리프싱크 적용.

라이선스

이중 라이선스: AGPL-3.0 (오픈소스 부분) 및 상용 사용을 위한 독점적 "클로즈드소스" 라이선스(서면 허가 필요). 리포지토리에는 LICENSE(AGPL)와 LICENSE-CLOSED-SOURCE 파일이 모두 포함되어 있습니다.

결론

NagaAgent는 LLM 채팅, 도구 호출, 그래프 기반 메모리, Live2D 아바타 렌더링, 음성 I/O, 플러그인 생태계를 통합한 풀스택이며 데스크톱 중심의 AI 어시스턴트입니다. 단순한 튜토리얼이나 커스터마이즈된 목록이 아닌, 확장 가능하고 시각적으로 풍부한 AI 동반자를 원하는 사용자를 위한 진정한 소프트웨어 프로젝트입니다.