nullpointexception-i/agent-sphere

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

무엇인가요

• 대규모 언어 모델(LLM)로 구동되는 자율 AI 에이전트를 실행할 수 있는 풀스택 웹 애플리케이션입니다. 핵심 엔진은 ReAct 패턴(계획 → 행동 → 관찰 → 학습)을 따르며, 각각 고유한 도구 세트를 가진 서브 에이전트 를 오케스트레이션할 수 있습니다.
• 결정 엔진, 통합 기능 레이어(브라우저 자동화, CLI, 내장 도구, MCP 프로토콜), 지속적인 다중 레벨 메모리, 사용자 친화적 UI(React + Ant Design) 및 임베디드 챗 위젯을 통합하고 있습니다.

주요 기능

기능	기능 설명
LLM ReAct 오케스트레이션	SessionRunner 는 시간 제한 및 취소 가능한 루프를 실행하여 추론, 도구 호출, 결과 관찰, 자동 컨텍스트 압축을 수행합니다.
멀티에이전트 서브런	부모 런은 자식 에이전트(SessionSubRunner) 를 생성하여 제한된 도구 호출을 실행할 수 있습니다. 그 진행 상황은 채팅 UI 및 위젯 내 인라인 카드로 표시됩니다.
모델 라우팅 및 백업	OpenAI, DeepSeek, Zhipu AI(BigModel), QuickRouter, LiteLLM, OrcaRouter를 지원합니다. 주요 및 백업 경로는 구성 가능하며, 제공자가 실패해도 시스템은 점진적으로 저하됩니다.
통합 기능 레이어	MCP 서버, 내장 SPI 도구, Chrome 확장 프로그램 브리지를 통한 실제 브라우저 자동화, CLI 실행, 단일 ToolExecutor 를 통한 복합 '스킬'을 제공합니다.
실제 브라우저 자동화	Manifest-V3 Chrome 확장 프로그램은 SSE를 통해 browser_operation 명령을 수신하고, 페이지의 메인 월드에서 탐색, 클릭, 입력, 임의의 JavaScript를 실행할 수 있습니다.
다중 레벨 메모리	런 중에는 메모리 내(L1-L2)에 컨텍스트를 저장하고 PostgreSQL(L3-L6)에 지속적으로 저장합니다. 자동 토큰 예산 기반 컨텍스트 압축으로 프롬프트가 모델 제한 내에 유지됩니다.
사람이 루프에 개입하는 명확화	LLM은 ask_clarification 도구로 일시 중지할 수 있으며, UI는 명확화 카드(확인/선택/입력)를 표시하고 사용자가 응답하면 다시 시작합니다.
OIDC SSO 및 RBAC	어떤 IdP에서도 PKCE 기반 OpenID Connect 로그인, 즉시 사용자 프로비저닝, 리소스의 행 수준 격리, 감사 로그 포함 완전한 역할 기반 접근 제어를 지원합니다.
사용자별 개인 리소스	첫 로그인 시 사용자 전용 모델/제공자 자격 증명, 도구 정의, 문서 저장소 복사본이 프로비저닝되어 격리가 보장됩니다.
외부 시스템용 오픈 API	/api/v1/api/* 엔드포인트는 completions 및 tasks 를 노출하며, 아이덴티티 스코프 소유권 검사와 선택적 콜백 URL을 지원합니다.
임베디드 챗 위젯	단일 IIFE 스크립트가 Shadow DOM 위젯을 마운트하고, 타입 지정된 REST + SSE를 통해 백엔드와 통신하며 자체 Bearer 토큰을 처리하므로 외부 런타임이 필요 없습니다.

기술 스택

• 백엔드: Java 21, Spring Boot 3.4, MyBatis-Plus, PostgreSQL 14, Redis 7(분산 락, 취소 플래그, SSE 브로드캐스팅용).
• 프론트엔드: React 19, UmiJS 4, Ant Design 6, TypeScript 6.
• 브라우저 브리지: 현대 ES 모듈로 작성된 Chrome Manifest-V3 확장 프로그램; SSE를 통해 서버와 통신.
• 라이선스: MIT.

일반적인 사용 사례

• 웹을 탐색하거나 폼을 채우거나 쉘 명령어를 실행해야 하는 AI 어시스턴트 구축.
• LLM이 MCP 프로토콜을 통해 내부 도구(Jira, GitHub, 데이터베이스)와 상호작용해야 하는 기업 워크플로우.
• 실시간 도구 실행과 선택적 인간 명확화가 필요한 고객 대상 챗 위젯.
• 고수준 플래너가 전문 에이전트에게 하위 작업을 위임하는 멀티에이전트 조율.

시작하기

1. 리포지토리 복제 후 QUICK_START.md 가이드를 따르세요 (Java, Node, PostgreSQL, Redis 설정).
2. Spring Boot 서비스 실행 (./mvnw spring-boot:run).
3. React UI 시작 (npm install && npm start).
4. 제공된 소스에서 Chrome 확장 프로그램 설치; 사용자별 SSE 스트림을 통해 자동으로 백엔드에 연결됩니다.
5. as.buukle.top 에서 라이브 데모 열고, 데모 계정 demo001 / demo001 로 로그인하여 UI, 멀티에이전트 채팅, 임베디드 위젯을 탐색하세요.

왜 중요한가요 AgentSphere는 일반적으로 별도로 구축되는 LLM 기반 에이전트의 요소들을 통합합니다: 견고한 ReAct 루프, 도구 실행, 메모리 관리, 모델 라우팅, 프로덕션 수준의 UI. 깔끔한 REST + SSE API와 임베디드 위젯을 공개함으로써, 어떤 웹 페이지에도 기능이 풍부한 AI 어시스턴트를 쉽게 도입할 수 있으며, 동시에 복잡한 다단계 도구 기반 워크플로우를 백엔드에서 지원할 수 있습니다.