ZJU-REAL/HugAgentOS

HugAgentOS – 엔터프라이즈급 에이전트 운영 체제

개요 – HugAgentOS는 정보 검색, 파일 조작, 코드 실행 및 엔드투엔드 작업 수행이 가능한 AI 에이전트를 실행할 수 있는 오픈소스 자가 호스팅 플랫폼입니다. 제어 평면 역할을 하는 도메인 온톨로지를 중심으로 구축되어, 시스템이 비즈니스 규칙을 강제하고 의사결정을 추적하며 권한을 관리할 수 있도록 합니다.

주요 기능

기능	내용
채팅 및 계획	실시간 SSE 스트리밍, ReAct 스타일의 도구 오케스트레이션, 인용문이 포함된 계획 모드 실행 및 재개 가능한 실행.
개인 RAG	문서 청킹, 하이브리드 벡터-키워드 검색, 선택적 리랭킹, 사용자별 격리.
하위 에이전트	라우팅이나 @ 멘션을 통해 접근 가능한 고유한 역할을 가진 개인용 '어시스턴트' 에이전트.
MCP 도구 생태계	내장 웹 검색, 페이지 가져오기, 지식 검색, 배치 실행, 자동화 및 스킬 마켓플레이스.
에이전트 스킬	Python/TS로 작성된 재사용 가능한 스킬 정의로 핵심 에이전트 확장.
자동화 / 배치	자연어 작업 예약, 스프레드시트, Word 문서 또는 파일 목록에 대한 프로세스 실행.
그룹 채팅 봇	Feishu, DingTalk, WeCom에 연결하여 팀 채널에서 읽기 및 답장 가능.
샌드박스 실행	하위 프로세스나 경량 컨테이너에서 코드를 실행하여 차트, 보고서, 웹 페이지 등을 생성.
3계층 메모리	관계형 DB에 저장된 프로필, 선택적 Milvus 벡터 메모리, 선택적 Neo4j 그래프 메모리.
개인 진화	메모리, 스킬 또는 온톨로지 변경 사항은 버전 관리되며, 사람의 승인이 필요하고 롤백이 가능.
워크스페이스 및 데이터 캔버스	프로젝트, 폴더, 아티팩트 센터 및 대화 내 데이터 편집기.

실행 방법

• 단일 명령 설치 프로그램 (Linux/macOS/WSL2) – 리포지토리를 가져오고, 가상 환경을 생성하며, React 프론트엔드를 빌드하고 127.0.0.1:3001에서 서비스를 시작합니다. SQLite와 프로세스 내 샌드박스를 사용하여 개인용으로 적합합니다.
• Docker-Compose – PostgreSQL, Redis, 선택적 Milvus/Neo4j 및 프로덕션급 격리와 지속성을 위한 샌드박스 컨테이너를 실행합니다. http://localhost:3002에서 접근 가능합니다.

두 방법 모두 OpenAI 호환 또는 로컬 호스팅 LLM이 필요하며, UI의 Settings → System → Model services에서 모델을 설정할 수 있습니다.

아키텍처 개요

• 에이전트 런타임 – AgentScope 2.0, ReAct 및 Model Context Protocol (MCP) 기반.
• 백엔드 – FastAPI + SQLAlchemy + Alembic (Python).
• 프론트엔드 – React 19 + TypeScript + Vite + Ant Design.
• 상태 및 저장소 – SQLite 또는 PostgreSQL, 선택적으로 Redis, Milvus, Neo4j 또는 벡터/그래프 메모리용 mem0.
• 배포 – 단일 바이너리 설치 프로그램, Docker Compose 또는 사용자 지정 Nginx 프론트엔드 배포.

중요한 이유

• 모델 독립성 – 코드 변경 없이 클라우드 또는 온프레미스 LLM 간 전환 가능.
• 신뢰할 수 있는 실행 – 계획은 온톨로지 정의 규칙에 따라 검사되며, 위반 시 조용히 실행되는 대신 증거와 함께 보고됩니다.
• 추적성 – 모든 승인, 거부 및 결과가 기록되어 버전 관리된 온톨로지 업데이트 및 롤백이 가능합니다.
• 데이터 온프레미스 유지 – 모든 데이터베이스와 파일 저장소는 자체 인프라에서 실행됩니다.

에디션

• 커뮤니티 에디션 (본 리포지토리) – 전체 개인 에이전트 스택, Apache 2.0 라이선스 기반 오픈소스.
• 엔터프라이즈 에디션 – 멀티 테넌트 거버넌스, SSO, 조직 전체 스킬 검토, 지속적 샌드박스, 결제 및 협업 도구 추가(소스 코드는 여기에 포함되지 않음).

시작하기

# 단일 명령 설치 (Linux/macOS/WSL2)
curl -fsSL https://raw.githubusercontent.com/ZJU-REAL/HugAgentOS/main/install.sh | bash
# 이후 시작
~/.hugagent/venv/bin/hugagent

또는 Docker Compose 사용:

git clone https://github.com/ZJU-REAL/HugAgentOS.git
cd HugAgentOS
cp .env.example .env
mkdir -p data/storage
docker compose up -d --build

문서 및 커뮤니티 – 영어 및 중국어 가이드가 소개, 빠른 시작, 배포, 아키텍처, 온톨로지 구축 및 모듈 개발을 다룹니다. Issues, Discussions 또는 pull requests를 통한 기여를 환영합니다(문서 및 예제만 해당, 핵심 코드는 업스트림 리포지토리에서 생성됨).

---

모든 세부 정보는 리포지토리의 README에서 직접 가져왔으며, 외부 가정은 추가되지 않았습니다.