nullpointexception-i/agent-sphere

AgentSphere – An LLM‑driven AI‑agent orchestration platform

What it is

• A full‑stack web application that lets users run autonomous AI agents powered by large language models (LLMs). The core engine follows the ReAct pattern (Plan → Act → Observe → Learn) and can orchestrate sub‑agents that each have their own tool set.
• The platform ties together a decision engine, a unified capability layer (browser automation, CLI, built‑in tools, MCP protocol), persistent multi‑level memory, and a user‑facing UI (React + Ant Design) plus an embeddable chat widget.

Key capabilities

Feature	What it does
LLM ReAct orchestration	SessionRunner runs a timed, cancellable loop that reasons, calls tools, observes results, and compacts context automatically.
Multi‑agent sub‑runs	A parent run can spawn child agents (SessionSubRunner) that execute restricted tool calls; their progress appears as inline cards in the chat UI and in the widget.
Model routing & fallback	Supports OpenAI, DeepSeek, Zhipu AI (BigModel), QuickRouter, LiteLLM, OrcaRouter. Primary and fallback routes are configurable; the system degrades gracefully when a provider fails.
Unified capability layer	Exposes MCP servers, built‑in SPI tools, a Chrome‑extension bridge for real browser automation, CLI execution, and composite “skills” through a single ToolExecutor.
Real browser automation	A Manifest‑V3 Chrome extension receives browser_operation commands via SSE and can navigate, click, type, or run arbitrary JavaScript in the page’s main world.
Multi‑level memory	Context is stored in‑memory (L1‑L2) during a run and persisted in PostgreSQL (L3‑L6). Automatic token‑budget‑based context compaction keeps prompts within model limits.
Human‑in‑the‑loop clarification	The LLM can pause with an ask_clarification tool; the UI shows a clarification card (confirm/choice/input) and resumes once the user replies.
OIDC SSO & RBAC	PKCE‑based OpenID Connect login from any IdP, just‑in‑time user provisioning, row‑level isolation of resources, and full role‑based access control with audit logs.
Per‑user private resources	On first login a private copy of model/provider credentials, tool definitions, and document stores is provisioned for the user, ensuring isolation.
Open API for external systems	/api/v1/api/* endpoints expose completions and tasks with identity‑scoped ownership checks and optional callback URLs.
Embeddable chat widget	A single IIFE script mounts a shadow‑DOM widget that talks to the backend via typed REST + SSE, handling its own Bearer token – no external runtimes required.

Technology stack

• Backend: Java 21, Spring Boot 3.4, MyBatis‑Plus, PostgreSQL 14, Redis 7 (for distributed locks, cancellation flags, and SSE broadcasting).
• Frontend: React 19, UmiJS 4, Ant Design 6, TypeScript 6.
• Browser bridge: Chrome Manifest‑V3 extension written in modern ES modules; communicates with the server over SSE.
• Licensing: MIT.

Typical use cases

• Building AI assistants that need to browse the web, fill forms, or run shell commands.
• Enterprise workflows where an LLM must interact with internal tools (Jira, GitHub, databases) via the MCP protocol.
• Customer‑facing chat widgets that require real‑time tool execution and optional human clarification.
• Multi‑agent coordination where a high‑level planner delegates subtasks to specialized agents.

Getting started

1. Clone the repo and follow the QUICK_START.md guide (sets up Java, Node, PostgreSQL, Redis).
2. Run the Spring Boot service (./mvnw spring-boot:run).
3. Start the React UI (npm install && npm start).
4. Install the Chrome extension from the provided source; it will automatically connect to the backend via the per‑user SSE stream.
5. Open the live demo at as.buukle.top and log in with the demo account demo001 / demo001 to explore the UI, multi‑agent chats, and the embeddable widget.

Why it matters AgentSphere bundles together the pieces that are often built separately for LLM‑powered agents: a robust ReAct loop, tool execution, memory management, model routing, and a production‑grade UI. By exposing a clean REST + SSE API and an embeddable widget, it makes it easy to drop a full‑featured AI assistant into any web page while still supporting complex, multi‑step, tool‑driven workflows behind the scenes.