JManus Architecture Analysis: Spring Boot Multi-Agent Plan-Act Execution Platform

Key points

• Positioning: JManus is a Spring Boot-driven multi-agent Plan-Act execution platform, targeting enterprise environments that need deterministic, auditable AI workflow orchestration. The frontend uses Vue 3 + Ant Design Vue with a graphical interface for plan editing, execution, and monitoring.
• Overall shape: A monolithic Spring Boot application hosts all business APIs, the plan-execution kernel, the tool system, and persistence, and serves the built Vue frontend from static resources. Docker and GraalVM native image deployments are both supported.
• Core capabilities: Plan generation and scheduling in Plan-Act mode, tool invocation (database, browser, Bash, OCR, etc.), execution trace recording, conversational memory, MCP (Model Context Protocol) extensions, open HTTP APIs, and Cron scheduling.
• Runtime requirements: Java 17+, embedded H2 by default (switchable to MySQL/PostgreSQL), an external LLM service (e.g., DashScope), and optional Playwright/ChromeDriver.

Architecture blueprint

• UI layer: the ui-vue3 sub-project builds into src/main/resources/static and is served by Spring Boot.
• Service layer: REST APIs under /api/*; high-level APIs focus on plan execution (ManusController), plan templates, configuration, and tool orchestration.
• Execution kernel: the planning, runtime, agent, tool, and recorder packages form the chain from plan parsing, agent dispatch, and tool invocation to execution recording.
• Data & config layer: Spring Data JPA repositories plus Config/Recorder entities; the config package handles dynamic configuration, startup loading, and property mapping.
• External integrations: llm for LLM interaction, mcp for remote MCP tools, adapter for OpenAI-compatible protocols, deploy for containerization scripts.
• Events & scheduling: an event domain event bus and a cron package wrapping Spring Scheduling.

Backend execution pipeline

• PlanningFactory registers tool callbacks (browser, database, Cron, etc.) and dynamically extends the tool list from MCP services, wrapping each tool as a ToolCallBiFunctionDef or McpTool.
• PlanningCoordinator converts plans into ExecutionContext, delegates to an executor from PlanExecutorFactory, and passes results to PlanFinalizer for post-processing (summaries, direct responses, or interruption notices).
• AbstractPlanExecutor controls the step loop, agent execution, file syncing, result recording, and interruption, using LevelBasedExecutorPool for hierarchical thread-pool scheduling.
• PlanFinalizer decides whether to generate an LLM summary, respond directly, or report an interrupted task, while writing execution records and interacting with conversation memory.

Tool system

• All tools implement ToolCallBiFunctionDef, providing name, description, input schema, and execution callback aligned with function calling.
• Built-in tool families: browser automation (BrowserUseTool with Playwright/ChromeDriver), database read/write/metadata tools, file and OCR-to-Markdown tools, CronTool for scheduled plans, and ParallelExecutionTool for concurrent sub-plans.
• Extension: tool/howToCreateNewTool.md documents custom tool creation; MCP tools load remote capabilities dynamically via McpService.

Configuration, events, and persistence

• The config package maps application.yml properties (ManusProperties, etc.), exposes runtime configuration via ConfigController/ConfigService, and loads defaults through startup listeners.
• The event package defines JmanusEvent and PlanExceptionEvent; the cron package provides plan-level scheduled execution; TaskInterruptionManager coordinates execution interruption via database state.
• NewRepoPlanExecutionRecorder persists full execution traces (Plan → Agent → Think-Act hierarchy), supporting execution-tree rendering in the UI.

Frontend architecture

• Vue 3 (Composition API) + TypeScript + Vite + Pinia + Vue Router + Ant Design Vue; production builds are copied to the backend static/ui directory.
• Pinia stores (task, sidebar, memory, namespace) manage task submission, running state, stop operations, conversation memory, and namespace context, syncing across views via browser events and localStorage.
• The API layer wraps fetch calls against /api/*. The main flow: submit a task → obtain planId → track state in Pinia → poll /api/executor/details/{planId} for the execution tree → submit user input via /submit-input/{planId} when required. Task interruption calls /api/executor/stopTask/{planId}.

Key flows

• Plan creation to execution: ManusController.executeByToolNameAsync accepts tool names or template IDs, writes conversation memory, syncs uploaded files, and triggers PlanningCoordinator. Plan templates support <<param>> placeholder substitution.
• User input & interruption: UserInputService marks waiting states in RootTaskManagerEntity; submitted JSON forms wake the executor; interruption is confirmed through TaskInterruptionManager in both the executor loop and finalizer.

Extensibility

• Custom tools: implement ToolCallBiFunctionDef and register with Spring or MCP; PlanningFactory can register full or trimmed tool sets based on agent.init configuration.
• Dynamic agents: DynamicAgent, ConfigurableDynaAgent, and DynamicAgentDefinition assemble agent flows at runtime; the subplan module generates child plans dynamically, forming tree-shaped execution.
• LLM integration adapts Spring AI via LlmService, supporting multiple vendors, streaming responses, and memory strategies.

Deployment & operations

• Makefile and tools/make wrap Maven, frontend builds, Docker image creation, and CI checks (codespell, markdownlint, yamllint).
• deploy/Dockerfile is JDK17-based; deploy/start.sh provides the startup script; /api/config offers dynamic configuration; playwright-init pre-downloads browser kernels.
• Logging uses logback-spring.xml with a ManusProperties.debugDetail switch for LLM debugging.

Conclusion

JManus closes the loop from frontend orchestration → backend plan-execution kernel → tools and external services → execution recording and visual feedback. Developers can extend tooling, customize plan templates, or swap LLM providers while keeping the core execution pipeline stable.