nullpointexception-i/agent-sphere

This project is an AI Agent orchestration platform. It uses an LLM-driven decision engine, combined with capabilities (built-in tools, MCP protocol, CLI execution, browser operations, etc.), to achieve a basic closed loop from perception → planning → execution → feedback.本项目是一个面向 AI Agent 编排平台。它通过 LLM 驱动的决策引擎，结合能力（内置工具、MCP 协议、CLI 执行、浏览器操作等）

What it solves

AgentSphere is an AI Agent orchestration platform that enables LLMs to move beyond simple chat by integrating them into a closed loop of perception, planning, execution, and feedback. It solves the challenge of connecting LLMs to real-world tools and environments—such as web browsers, command-line interfaces, and external APIs—while managing the complex state, memory, and error-handling required for autonomous task completion.

How it works

The platform uses a ReAct (Reasoning + Acting) engine called the SessionRunner. This engine manages a loop where the LLM reasons about a goal, selects a tool to act, observes the result, and learns from that observation to plan the next step.

Key technical components include:

  • Capability Layer: A modular system that connects the agent to MCP (Model Context Protocol) servers, built-in Java tools, a Chrome Extension for browser automation, and a CLI for shell execution.
  • Multi-level Memory: A tiered storage system (from fast in-memory caches to permanent PostgreSQL records) that handles context assembly and automatic "compaction" (compression) of long conversation histories to stay within LLM token limits.
  • Model Routing: A fault-tolerant system that can route requests across different providers (OpenAI, DeepSeek, Zhipu AI, etc.) with automatic fallback mechanisms.
  • Human-in-the-Loop: A "User Clarification" mechanism that allows the agent to pause execution and ask the user for confirmation or missing information before proceeding.

Who it’s for

  • Developers looking to build complex AI agents that can interact with the web and local systems.
  • Enterprise users needing an orchestration layer to manage multiple LLM providers and tool integrations.
  • System architects interested in implementing the ReAct pattern with robust memory management and observability.

Highlights

  • Browser Automation: Integrated Chrome Extension for DOM operations and real-time visual feedback.
  • MCP Support: Compatible with the Model Context Protocol for easy connection to tools like Jira, GitHub, and Slack.
  • Context Compaction: Intelligent token-budget-based compression of tool results and history to optimize LLM input.
  • High Concurrency: Built with Java 21 Virtual Threads to handle hundreds of concurrent streaming LLM sessions efficiently.
  • Observability: Real-time event streaming via SSE for tracking reasoning steps and tool execution status.