nullpointexception-i/agent-sphere

AgentSphere – an LLM‑driven AI‑agent orchestration platform

What it is

• A full‑stack web application that lets you run ReAct‑style AI agents (LLM + tools) in a closed loop: Perception → Planning → Execution → Feedback.
• Agents can call built‑in tools, remote MCP services, a Chrome extension for real‑world browser automation, CLI commands, or custom composite skills.
• Supports multi‑agent orchestration: a parent run can delegate sub‑tasks to child agents, and you can define DAG‑like task graphs with dependencies and parallel lanes.

Key capabilities

Feature	What it does
LLM ReAct engine (SessionRunner)	Runs a Plan → Act → Observe → Learn loop with per‑turn timeout, cancellation, and automatic context compaction.
Multi‑agent sub‑runs (SessionSubRunner)	Parent runs can delegate work to sub‑agents; supports DAG orchestration, bounded retries and result reconciliation.
Model routing	Choose among OpenAI, DeepSeek, Zhipu AI, QuickRouter, LiteLLM, OrcaRouter with primary/fallback chains and graceful degradation.
Unified capability layer	MCP servers, built‑in SPI tools, CLI execution, Chrome‑extension browser automation, and composite skills are all invoked through a single ToolExecutor.
Real browser automation	A Manifest‑V3 Chrome extension can navigate, click, type, run JS, take viewport/full‑page screenshots, and perform pixel‑accurate clickAt.
Vision‑enabled agents	Screenshots are sent back to the LLM as visual observations; agents can reason over page images.
Image‑in‑chat	Upload images via /api/v1/files/upload; they appear as thumbnails in the chat UI and are fed to models that support attachments.
Multi‑level memory	Persistent run logs, tool‑call records (JSON‑compressed) and token‑budget based context compaction keep the conversation coherent.
Human‑in‑the‑loop	The LLM can pause with an ask_clarification tool; the UI lets a user answer, choose, or input before the run resumes.
Non‑blocking wait tool	Puts a run into a WAITING state without occupying a thread; a timer or cron wakes it later.
Loop budget	Per‑run turn limit that survives pauses; the model is informed each turn and receives a “hard‑close” nudge near the cap.
OIDC SSO & RBAC	PKCE‑based login from any identity provider, just‑in‑time user provisioning, row‑level isolation of private resources.
Skill Hub	Users can publish skills (structured LLM prompts) as public templates; others can install them, getting a forked copy that can auto‑update.
Embeddable chat widget	A single IIFE script mounts a shadow‑DOM widget that talks to the backend via REST + SSE, with bearer‑token auth – no CopilotKit dependency.
Capability Open API	External systems can call /api/v1/api/completions and /api/v1/api/tasks with fine‑grained ownership checks and callback URLs.

Technology stack

• Backend: Java 21, Spring Boot 3.4, MyBatis‑Plus, PostgreSQL 14, Redis 7.
• Frontend: React 19, UmiJS 4, Ant Design 6, TypeScript 6.
• Browser bridge: Chrome Manifest‑V3 extension using native ES modules, Chrome Debugging Protocol for screenshots and executeJS.
• LLM integration: Abstracted via a model provider layer; supports OpenAI, DeepSeek, Zhipu AI, LiteLLM, OrcaRouter, and custom relay stations.

Typical use cases

• Web‑assistant bots that can browse, fill forms, and scrape data while reasoning with an LLM.
• Enterprise workflow automation: combine LLM planning with MCP‑backed tools (Jira, GitHub, Slack, databases) to orchestrate multi‑step processes.
• Custom AI agents: define a skill (prompt template) that decomposes a business task; publish it for teammates to reuse.
• Embedded AI chat: drop the widget on a SaaS portal to give users an LLM‑powered assistant that can see the page and act on it.

Getting started

1. Clone the repo and follow the Quick Start guide in QUICK_START.md (Docker compose for PostgreSQL/Redis, Maven build, npm install for the UI).
2. Run the backend (./mvnw spring-boot:run) and the UI (npm run dev).
3. Open the live demo at as.buukle.top and log in with the demo account demo001 / demo001 to explore the UI, multi‑agent chat, and the embeddable widget.

Documentation & demos

• Architecture diagram (agentsphere-architecture-v2.png).
• UI screenshots and a video demo on Bilibili (linked in the README).
• Detailed design notes on the ReAct loop, loop‑budget handling, skill‑hub versioning, and Chrome‑extension internals are embedded in the README.

License: MIT – you can freely modify, self‑host, or extend the platform.

---

All information above is taken directly from the repository’s README; no additional features have been inferred.