nullpointexception-i/agent-sphere

AgentSphere – LLM 기반 AI 에이전트 오케스트레이션 플랫폼

개요

• ReAct 스타일 AI 에이전트(LLM + 도구)를 폐쇄 루프로 실행하는 풀스택 웹 애플리케이션: 인식 → 계획 → 실행 → 피드백.
• 에이전트는 내장 도구, 원격 MCP 서비스, 실제 브라우저 자동화를 위한 Chrome 확장 프로그램, CLI 명령, 또는 사용자 정의 복합 스킬을 호출할 수 있습니다.
• 멀티 에이전트 오케스트레이션 지원: 상위 실행은 하위 에이전트에 하위 작업을 위임할 수 있으며, 종속성과 병렬 레인을 가진 DAG 유사 작업 그래프를 정의할 수 있습니다.

주요 기능

기능	설명
LLM ReAct 엔진 (SessionRunner)	Plan → Act → Observe → Learn 루프를 실행하며, 턴별 타임아웃, 취소, 자동 컨텍스트 압축을 제공합니다.
멀티 에이전트 하위 실행 (SessionSubRunner)	상위 실행은 하위 에이전트에 작업을 delegate할 수 있으며, DAG 오케스트레이션, 제한된 재시도, 결과 조정을 지원합니다.
모델 라우팅	OpenAI, DeepSeek, Zhipu AI, QuickRouter, LiteLLM, OrcaRouter 중 선택 가능, 기본/대체 체인 및 원활한 성능 저하 지원.
통합 기능 레이어	MCP 서버, 내장 SPI 도구, CLI 실행, Chrome 확장 프로그램 브라우저 자동화, 복합 스킬은 모두 단일 ToolExecutor를 통해 호출됩니다.
실제 브라우저 자동화	Manifest-V3 Chrome 확장 프로그램은 탐색, 클릭, 입력, JS 실행, 뷰포트/전체 페이지 스크린샷, 픽셀 정확한 clickAt을 수행할 수 있습니다.
비전 지원 에이전트	스크린샷은 시각적 관찰로 LLM에 다시 전송되며, 에이전트는 페이지 이미지에 대해 추론할 수 있습니다.
채팅 내 이미지	/api/v1/files/upload를 통해 이미지를 업로드하면 채팅 UI에 썸네일로 표시되고 첨부 파일을 지원하는 모델에 전달됩니다.
다중 레벨 메모리	영구 실행 로그, 도구 호출 기록(JSON 압축), 토큰 예산 기반 컨텍스트 압축으로 대화 일관성 유지.
휴먼 인 더 루프	LLM은 ask_clarification 도구로 일시 중지할 수 있으며, UI에서 사용자가 답변, 선택 또는 입력하고 실행을 재개할 수 있습니다.
비차단 wait 도구	스레드를 점유하지 않고 실행을 WAITING 상태로 전환, 타이머 또는 cron으로 나중에 깨움.
루프 예산	일시 중지를 견디는 턴 제한, 모델은 매 턴 통보되며 한도에 가까워지면 “하드 클로즈” 알림을 받음.
OIDC SSO 및 RBAC	모든 ID 공급자에서 PKCE 기반 로그인, 적시 사용자 프로비저닝, 개인 리소스의 행 수준 격리.
스킬 허브	사용자는 스킬(구조화된 LLM 프롬프트)을 공개 템플릿으로 게시할 수 있으며, 다른 사용자는 자동 업데이트되는 포크 복사본을 설치할 수 있습니다.
임베드 가능한 채팅 위젯	단일 IIFE 스크립트가 REST + SSE를 통해 백엔드와 통신하는 shadow-DOM 위젯을 마운트하며, Bearer 토큰 인증 사용 – CopilotKit 의존성 없음.
기능 공개 API	외부 시스템은 /api/v1/api/completions 및 /api/v1/api/tasks를 세분화된 소유권 검사 및 콜백 URL로 호출할 수 있습니다.

기술 스택

• 백엔드: Java 21, Spring Boot 3.4, MyBatis-Plus, PostgreSQL 14, Redis 7.
• 프론트엔드: React 19, UmiJS 4, Ant Design 6, TypeScript 6.
• 브라우저 브리지: 네이티브 ES 모듈을 사용하는 Chrome Manifest-V3 확장 프로그램, 스크린샷 및 executeJS용 Chrome 디버깅 프로토콜.
• LLM 통합: 모델 제공자 레이어로 추상화되어 OpenAI, DeepSeek, Zhipu AI, LiteLLM, OrcaRouter 및 사용자 정의 릴레이 스테이션을 지원합니다.

일반적인 사용 사례

• 웹 어시스턴트 봇: LLM으로 추론하면서 탐색, 양식 작성, 데이터 스크래핑 가능.
• 엔터프라이즈 워크플로 자동화: LLM 계획과 MCP 기반 도구(Jira, GitHub, Slack, 데이터베이스)를 결합하여 다단계 프로세스 오케스트레이션.
• 사용자 정의 AI 에이전트: 비즈니스 작업을 분해하는 스킬(프롬프트 템플릿)을 정의하고 팀원이 재사용할 수 있도록 게시.
• 임베디드 AI 채팅: SaaS 포털에 위젯을 배치하여 페이지를 보고 조치할 수 있는 LLM 기반 어시스턴트를 사용자에게 제공.

시작하기

1. 리포지토리를 클론하고 QUICK_START.md의 빠른 시작 가이드를 따릅니다(PostgreSQL/Redis용 Docker compose, Maven 빌드, UI용 npm install).
2. 백엔드(./mvnw spring-boot:run)와 UI(npm run dev)를 실행합니다.
3. 라이브 데모를 as.buukle.top에서 열고 데모 계정 demo001 / demo001으로 로그인하여 UI, 멀티 에이전트 채팅, 임베드 가능한 위젯을 탐색합니다.

문서 및 데모

• 아키텍처 다이어그램(agentsphere-architecture-v2.png).
• Bilibili의 UI 스크린샷 및 비디오 데모(README에 링크).
• ReAct 루프, 루프 예산 처리, 스킬 허브 버전 관리, Chrome 확장 프로그램 내부에 대한 자세한 설계 노트는 README에 포함되어 있습니다.

라이선스: MIT – 자유롭게 수정, 자체 호스팅 또는 확장할 수 있습니다.

---

위의 모든 정보는 리포지토리의 README에서 직접 가져온 것이며 추가 기능은 추측되지 않았습니다.