{"id":49815511,"url":"https://github.com/leochame/OpenManus-Java","last_synced_at":"2026-05-29T21:00:55.968Z","repository":{"id":313438386,"uuid":"1013813505","full_name":"leochame/OpenManus-Java","owner":"leochame","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-16T02:45:39.000Z","size":2936,"stargazers_count":59,"open_issues_count":2,"forks_count":12,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-05-16T04:49:13.024Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leochame.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-07-04T14:03:09.000Z","updated_at":"2026-05-16T02:45:43.000Z","dependencies_parsed_at":"2025-10-02T13:17:34.115Z","dependency_job_id":null,"html_url":"https://github.com/leochame/OpenManus-Java","commit_stats":null,"previous_names":["leochame/openmanus-java"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/leochame/OpenManus-Java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leochame%2FOpenManus-Java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leochame%2FOpenManus-Java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leochame%2FOpenManus-Java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leochame%2FOpenManus-Java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leochame","download_url":"https://codeload.github.com/leochame/OpenManus-Java/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leochame%2FOpenManus-Java/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33670211,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-13T06:00:43.984Z","updated_at":"2026-05-29T21:00:55.961Z","avatar_url":"https://github.com/leochame.png","language":"Java","funding_links":[],"categories":["人工智能"],"sub_categories":["AI智能体"],"readme":"# OpenManusJava\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/img/logo.png\" alt=\"OpenManusJava Logo\" width=\"256\" height=\"256\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA Java-Powered AI Agent Framework with ReAct Reasoning\u003c/strong\u003e\n\u003c/p\u003e\n\n[![Java](https://img.shields.io/badge/Java-21+-orange)](https://openjdk.java.net/projects/jdk/21/)\n[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.0-green)](https://spring.io/projects/spring-boot)\n[![License](https://img.shields.io/badge/License-MIT-blue)](LICENSE)\n[![Docker](https://img.shields.io/badge/Docker-Ready-blue)](Dockerfile)\n\n[Quick Start](#-quick-start) ·\n[Features](#-features) ·\n[Architecture](#-architecture) ·\n[Tool System](#-tool-system) ·\n[Configuration](#-configuration) ·\n[API Reference](#-api-reference)\n\n## Project Overview\n\nOpenManusJava is an intelligent agent framework built with Spring Boot, featuring a single-agent ReAct (Reason-Act) loop architecture. It provides provider-agnostic LLM integration, a pluggable annotation-driven tool system, session-scoped sandboxed code execution, and a modern 3-column web workspace with real-time execution streaming.\n\n**Key design choices:**\n\n- **Single ReAct Loop** — One `AgentCoordinator` drives planning, tool invocation, and answer generation in a unified loop. No supervisor/sub-agent handoff or nested executor chains.\n- **Annotation-Driven Tools** — Declare tools with `@AiTool` / `@AiParam` annotations on plain Java methods; the `AiToolRegistry` auto-generates JSON Schema specifications and reflective invokers.\n- **Runtime-First AI Framework** — The `aiframework` layer abstracts LLM calls behind `AiChatModel`, with pluggable `ProviderRequestAssembler` / `ProviderResponseParser` pairs for OpenAI, Anthropic, and Gemini.\n- **Context Assembly** — Full chat history stays in memory, task-state cards are injected when needed, and oversized tool results are replaced with explicit stubs before the next model round.\n\n## Features\n\n### Unified Single-Agent Reasoning\n\n- **Single ReAct Loop**: `AgentCoordinator` orchestrates Thinking → Search → Code/File → Reflection in one loop\n- **No Agent Handoff**: No supervisor/sub-agent string handoff or nested executor loops\n- **Session Memory Continuity**: Full message history persisted by `ChatMemory` (file or in-memory store)\n- **Tool-Result Budget**: Oversized tool outputs are offloaded to sandbox files and replaced with explicit stubs before the next model round\n\n### Multi-Provider LLM Support\n\n- **OpenAI** (and all OpenAI-compatible APIs)\n- **Anthropic** (Claude)\n- **Google Gemini**\n\nEach provider has its own `RequestAssembler` + `ResponseParser` + `Client` triplet; swapping providers requires only a config change.\n\n### Tool Ecosystem\n\n| Tool | Name | Description |\n|------|------|-------------|\n| **Search** | `search_web` | Web search via Serper API |\n| **Web Fetch** | `browser_fetch_web` | Fetch and extract raw content from a URL |\n| **Browser** | `browser_open_url`, `browser_ensure_sandbox` | Control front-end browser and VNC sandbox |\n| **Python Execution** | `executePython`, `executePythonFile` | Execute Python code in a Docker sandbox |\n| **Shell** | `runShellCommand` | Run shell commands inside the session sandbox |\n| **Task Reflection** | `recordTask`, `reflectOnTask`, `getTaskHistory` | Record and analyze task execution history |\n| **MCP** | *(dynamic)* | Optional Model Context Protocol integration for external tool discovery |\n\n### Web Workspace\n\n- **Modern 3-Column Layout**:\n  - **Left**: Intelligent chat panel for core interaction\n  - **Middle**: Multi-purpose tool panel — structured search results, tool outputs, file previews\n  - **Right**: Browser workspace with multi-tab, address bar, and dual-mode (Web/VNC) rendering\n- **Real-time Execution Streaming**: WebSocket + STOMP delivers live thinking steps, tool calls, and logs\n- **Web Proxy Mode**: Backend proxy for sites that block iframe embedding via `X-Frame-Options` / CSP\n- **Responsive Design**: Adapts to desktop, tablet, and mobile devices\n\n### Frontend Preview\n\n![Frontend Workspace Preview](frontend/openmanus-frontend.png)\n\n\u003e Some websites block iframe embedding via `X-Frame-Options` or CSP `frame-ancestors`. If you see a preview error, enable the **\"Proxy\"** toggle in the address bar to load the page through the backend proxy.\n\n## Architecture\n\n### Core Architecture Diagram\n\n```mermaid\ngraph TD\n    User[User] --\u003e UI[Web Interface\u003cbr/\u003eReact + Vite]\n    UI --\u003e|HTTP / WebSocket| Controller[AgentController]\n\n    Controller --\u003e ConversationService[ConversationApplicationService]\n    Controller --\u003e StreamingService[ExecutionStreamingApplicationService]\n\n    ConversationService --\u003e AgentExecService[AgentExecutionService]\n    StreamingService --\u003e AgentExecService\n\n    AgentExecService --\u003e Coordinator[AgentCoordinator\u003cbr/\u003eSingle ReAct Loop]\n\n    subgraph \"aiframework Runtime\"\n        ChatModel[AiChatModel]\n        Memory[AiMemoryProvider]\n        Assembler[ProviderRequestAssembler]\n        Parser[ProviderResponseParser]\n        Transport[HttpTransport / SseTransport]\n    end\n\n    Coordinator --\u003e ChatModel\n    ChatModel --\u003e Assembler\n    Assembler --\u003e Transport\n    Transport --\u003e Parser\n    Parser --\u003e Coordinator\n    Coordinator --\u003e Memory\n\n    subgraph \"Tool Layer\"\n        SearchTool[search_web]\n        WebFetchTool[browser_fetch_web]\n        BrowserTool[browser_open_url / ensure_sandbox]\n        PythonTool[executePython / executePythonFile]\n        ShellTool[runShellCommand]\n        ReflectionTool[recordTask / reflectOnTask / getTaskHistory]\n        McpBridge[MCP Tool Bridge]\n    end\n\n    Coordinator --\u003e SearchTool\n    Coordinator --\u003e WebFetchTool\n    Coordinator --\u003e BrowserTool\n    Coordinator --\u003e PythonTool\n    Coordinator --\u003e ShellTool\n    Coordinator --\u003e ReflectionTool\n    Coordinator -.-\u003e|optional| McpBridge\n\n    subgraph \"Sandbox Layer\"\n        DockerSandbox[Docker Sandbox\u003cbr/\u003ePython / Shell Execution]\n        VncSandbox[VNC Sandbox\u003cbr/\u003eBrowser Workspace]\n    end\n\n    PythonTool --\u003e DockerSandbox\n    ShellTool --\u003e DockerSandbox\n    BrowserTool --\u003e VncSandbox\n\n    Coordinator --\u003e|WebSocket Events| UI\n```\n\n### Package Structure\n\n```\ncom.openmanus\n├── aiframework/                   # Provider-agnostic AI runtime layer\n│   ├── api/                       # AiProviderClient, StreamListener interfaces\n│   ├── assembler/                 # Per-provider request builders (OpenAI, Anthropic, Gemini)\n│   ├── client/                    # Per-provider HTTP clients\n│   ├── config/                    # AiProviderClientRegistry\n│   ├── model/                     # Shared DTOs: ChatMessage, ProviderConfig, AiProviderType\n│   ├── parser/                    # Per-provider response parsers\n│   ├── runtime/                   # Core runtime: AiChatModel, AiMemory, AiToolSpec, MCP bridge\n│   │   ├── mcp/                   # MCP client interface and stub\n│   │   └── model/                 # Runtime models: AiChatRequest/Response, AiToolCall/Result\n│   ├── tool/                      # @AiTool/@iParam annotations, AiToolRegistry, AiToolExecutor\n│   │   └── mcp/                   # MCP tool bridge (registry bootstrap + spec adapter)\n│   └── transport/                 # HttpTransport, SseTransport\n│\n├── agent/                         # Agent coordination and tool implementations\n│   ├── base/                      # AbstractAgent, AbstractAgentExecutor (ReAct loop)\n│   ├── context/                   # Context assembly and tool-result budgeting\n│   │   ├── assembly/              # ContextAssembler, TaskExecutionState\n│   │   └── ToolResultBudget.java  # Offloads oversized tool outputs to sandbox files\n│   ├── coordination/              # AgentCoordinator (single-agent entry point)\n│   ├── execution/                 # AgentExecutionService\n│   └── tool/                      # Built-in tools: Browser, Python, Search, Shell, WebFetch, Reflection\n│\n├── domain/                        # Domain layer (ports \u0026 application services)\n│   ├── model/                     # ExecutionRequest/Response, AgentExecutionEvent, error codes\n│   └── service/                   # ConversationApplicationService, ExecutionStreamingApplicationService, ports\n│\n├── infra/                         # Infrastructure adapters\n│   ├── config/                    # Spring config: OpenManusProperties, AgentArchitectureConfig, etc.\n│   ├── exception/                 # Domain-specific exceptions\n│   ├── execution/                 # AgentExecutionAdapter\n│   ├── log/                       # Log relay: WebSocketLogAppender, LogRelayBridge\n│   ├── memory/                    # ChatMemory stores: FileChatMemoryStore, InMemoryAiMemoryStore\n│   ├── monitoring/                # Execution event adapters, WebSocket stream publisher\n│   ├── sandbox/                   # Docker sandbox adapters, VNC sandbox client\n│   └── web/                       # Controllers: AgentController, WebProxyController, etc.\n│\n└── sandbox/                       # Sandbox bounded context\n    ├── application/               # SandboxSessionApplicationService\n    ├── domain/                    # SessionSandboxInfo, SandboxRuntimePort\n    ├── infra/                     # Docker adapters, lifecycle manager\n    └── support/                   # SandboxPathResolver\n```\n\n### Technology Stack\n\n| **Component** | **Technology** | **Purpose** |\n|---|---|---|\n| Backend Framework | Spring Boot 3.2.0 | Core application framework |\n| AI Runtime | aiframework (built-in) | Provider-agnostic LLM abstraction and ReAct execution |\n| LLM Providers | OpenAI / Anthropic / Gemini | Multi-provider chat completions |\n| Frontend | React 18 + TypeScript + Vite | Modern SPA workspace |\n| Real-time Comms | WebSocket + STOMP (SockJS) | Execution streaming and log relay |\n| Code Sandbox | Docker (docker-java) | Isolated Python / Shell execution |\n| Browser Sandbox | VNC (Docker) | Remote browser workspace |\n| API Docs | springdoc-openapi (Swagger) | Interactive API documentation |\n| Code Quality | Checkstyle + SpotBugs + OWASP + JaCoCo | Static analysis, security, coverage |\n| Containerization | Docker multi-stage build | Production deployment |\n\n## Tool System\n\n### Annotation-Driven Tool Registration\n\nTools are declared as plain Java methods annotated with `@AiTool` and `@AiParam`. The `AiToolRegistry` scans these methods at startup and auto-generates:\n\n- **JSON Schema** parameter specifications for the LLM\n- **Reflective invokers** that deserialize LLM tool-call arguments and invoke the method\n\n```java\n@AiTool(value = \"Search the web for information\", name = \"search_web\")\npublic String searchWeb(@AiParam(\"Search query keywords\") String query) {\n    // implementation\n}\n```\n\n### Custom Tool Development\n\nTo add a new tool:\n\n1. Create a class with `@AiTool`-annotated methods\n2. Register it in `AgentArchitectureConfig` via `builder.toolFromObject(yourTool)`\n3. The tool is automatically available to the ReAct loop\n\n### MCP Integration\n\nEnable external tool discovery via Model Context Protocol:\n\n```yaml\nopenmanus:\n  mcp:\n    enabled: true\n```\n\nMCP tools are discovered at startup via `McpToolRegistryBootstrap` and merged into the agent's tool registry alongside built-in tools.\n\n## ⚙️ Configuration\n\n### Environment Variables\n\nConfiguration follows a layered priority: **explicit config** \u003e **environment variable** \u003e **default value**.\n\n| Variable | Description | Default |\n|---|---|---|\n| `OPENMANUS_LLM_DEFAULT_LLM_API_TYPE` | LLM provider: `openai`, `anthropic`, `gemini` | `openai` |\n| `OPENMANUS_LLM_DEFAULT_LLM_BASE_URL` | API base URL | `https://api.openai.com/v1` |\n| `OPENMANUS_LLM_DEFAULT_LLM_API_KEY` | API key | *(required)* |\n| `OPENMANUS_LLM_DEFAULT_LLM_MODEL` | Model name | *(required)* |\n| `SERPER_API_KEY` | Serper search API key | *(optional)* |\n| `OPENMANUS_SANDBOX_IMAGE` | Docker sandbox image | `python:3.11-slim` |\n| `OPENMANUS_CHAT_MEMORY_STORE_TYPE` | Memory store: `file` or `in-memory` | `file` |\n| `OPENMANUS_CHAT_MEMORY_FILE_STORE_DIR` | File memory store directory | `/tmp/openmanus/chat-memory` |\n| `OPENMANUS_MCP_ENABLED` | Enable MCP tool integration | `false` |\n\nSee [`dotenv.example`](dotenv.example) for the full list.\n\n### Long-Context Tuning\n\nTo keep the ReAct loop running without local context trimming, adjust `openmanus.chat-memory`:\n\n- **Keep looping on tool calls** — Set `react-max-iterations: 0` (unlimited). Optionally add `react-max-execution-seconds` and `react-repeated-tool-call-threshold` as safety guards.\n- **Preserve full message history** — Chat memory is no longer locally windowed, summarized, or token-trimmed before provider requests.\n- **Handle large tool outputs** — Enable `tool-result-budget-enabled` so oversized outputs are written to sandbox files and replaced with explicit stubs.\n\n**A) Full tool output inline**:\n\n```yaml\nopenmanus:\n  chat-memory:\n    react-max-iterations: 0\n    tool-result-budget-enabled: false\n```\n\n**B) Balanced** (recommended):\n\n```yaml\nopenmanus:\n  chat-memory:\n    react-max-iterations: 0\n    react-max-execution-seconds: 600\n    react-repeated-tool-call-threshold: 8\n    tool-result-budget-enabled: true\n    tool-result-budget-min-chars: 12000\n    tool-result-budget-preview-head-chars: 240\n    tool-result-budget-preview-tail-chars: 160\n    tool-result-budget-decay-chars: 0\n```\n\n**C) Aggressive tool-result offload**:\n\n```yaml\nopenmanus:\n  chat-memory:\n    react-max-iterations: 0\n    react-max-execution-seconds: 300\n    react-repeated-tool-call-threshold: 6\n    tool-result-budget-enabled: true\n    tool-result-budget-min-chars: 8000\n    tool-result-budget-preview-head-chars: 200\n    tool-result-budget-preview-tail-chars: 120\n    tool-result-budget-decay-chars: 0\n```\n\n## Quick Start\n\n### Prerequisites\n\n- **Java 21+**\n- **Maven 3.9+**\n- **Docker** (optional, for sandboxed code execution)\n- An **OpenAI-compatible API Key** (or Anthropic / Gemini key)\n\n### Local Development\n\n1. **Clone the project**\n   ```bash\n   git clone https://github.com/OpenManus/OpenManus-Java.git\n   cd OpenManus-Java\n   ```\n\n2. **Configure environment**\n   ```bash\n   cp dotenv.example .env\n   # Edit .env and fill in your API key and model settings\n   ```\n\n3. **Start with the dev script** (auto-starts frontend Vite dev server + Spring Boot)\n   ```bash\n   ./start-dev.sh\n   ```\n\n   Or start Spring Boot directly:\n   ```bash\n   mvn spring-boot:run\n   ```\n\n4. **Access the workspace**: http://localhost:8089\n\n### Docker Deployment\n\n```bash\n# Build and start\ndocker compose up -d\n\n# Check health\ncurl http://localhost:8089/actuator/health\n```\n\nThe Docker image uses a multi-stage build: Maven build → JRE runtime with a non-root user, health checks, and configurable JVM options.\n\n### Frontend Development\n\nThe frontend is located in `frontend/` and built with React 18 + TypeScript + Vite:\n\n```bash\ncd frontend\nnpm install\nnpm run dev          # Dev server on :5173\nnpm run build        # Production build → frontend/dist/\nnpm run test         # Vitest unit tests\n```\n\nIn development mode, Spring Boot proxies frontend requests to the Vite dev server configured at `openmanus.frontend.dev-server-url`.\n\n## API Reference\n\n### Chat API (HTTP)\n\n```bash\ncurl -X POST http://localhost:8089/api/agent/chat \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\": \"Hello, what can you do?\"}'\n```\n\nStateful conversation with a `conversationId`:\n\n```bash\ncurl -X POST \"http://localhost:8089/api/agent/chat?stateful=true\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\": \"Analyze this data\", \"conversationId\": \"my-session-001\"}'\n```\n\n### Streaming Execution API\n\nSubmit a task and receive a WebSocket topic for real-time event streaming:\n\n```bash\ncurl -X POST http://localhost:8089/api/agent/workflow-stream \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"input\": \"Analyze the development trend of the tourism industry during the Spring Festival.\"}'\n```\n\nResponse:\n```json\n{\n  \"success\": true,\n  \"sessionId\": \"abc-123\",\n  \"topic\": \"/topic/executions/abc-123\"\n}\n```\n\nSubscribe to the WebSocket topic to receive real-time execution events (thinking steps, tool calls, logs).\n\n### Session \u0026 Sandbox API\n\n```bash\n# Get session info (including VNC sandbox URL)\ncurl http://localhost:8089/api/agent/session/{sessionId}\n\n# Explicitly start a session sandbox\ncurl -X POST http://localhost:8089/api/agent/session/{sessionId}/sandbox/start\n```\n\n### API Documentation\n\nSwagger UI: http://localhost:8089/swagger-ui.html\n\n## 🧪 Testing \u0026 Evaluation\n\nStart here: `./scripts/run-eval.sh bench`\n\n| Goal | Command | When to use |\n|---|---|---|\n| Local benchmark baseline | `./scripts/run-eval.sh bench` | Demos and daily regression |\n| End-to-end validation | `./scripts/run-eval.sh e2e` | API / WebSocket flow checks |\n| Real-provider smoke | `./scripts/run-eval.sh live` | Provider, TLS, and credential checks |\n| Coverage report | `./scripts/mvnw-local.sh -q verify` | JaCoCo report |\n\nSee [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) for the benchmark design notes.\n\n**Quality gates:**\n- **Checkstyle** — Google Java style (validate phase)\n- **SpotBugs** — Static bug detection (medium+ threshold)\n- **OWASP Dependency Check** — CVE scanning (CVSS 7+ fails build)\n- **JaCoCo** — Code coverage ≥ 70% instruction coverage\n\n## Contact\n\n- WeChat: leochame007\n- Email: liulch.cn@gmail.com\n\n## Acknowledgements\n\n- [Spring Boot](https://spring.io/projects/spring-boot)\n- [docker-java](https://github.com/docker-java/docker-java)\n- [SpringDoc OpenAPI](https://springdoc.org)\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**If this project is helpful to you, please give it a Star!**\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleochame%2FOpenManus-Java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleochame%2FOpenManus-Java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleochame%2FOpenManus-Java/lists"}