# xiguazhiprince/openmanus architecture

> Architecture diagram of the GitHub repository xiguazhiprince/openmanus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xiguazhiprince/openmanus
- Repository: https://github.com/xiguazhiprince/openmanus

## Overview

##### Project Type and Purpose
- OpenManus is an agent-based system built to let users “achieve any ideas” by interacting with a self-operating agent via terminal input. It leverages large language model (LLM) APIs for its core functionality.
- Its purpose is to enable multiple agent components – such as planning, reactive tasks, tool calls, and other strategies – to work together, providing an accessible interface for users to experiment with intelligent agent workflows.

##### File Structure for Architectural Insights
- Top-level Directories/Files:
– The repository contains project configuration files and scripts like main.py, run_flow.py, and setup.py, which are key entry points.
– The “app” directory holds the core application logic, organized into submodules such as:
▪ agent: Implements different types of agents (base, planning, react, swe, manus, toolcall), which likely represent different decision-making or response strategies.
▪ flow: Contains modules that manage and instantiate various “flows” or execution pipelines for the agent.
▪ prompt: Manages prompt templates for different scenarios (manus, planning, swe, toolcall), tying into the agent’s interactions.
▪ tool: Provides implementations for additional capabilities (bash execution, browser use, file saver, etc.) and tool collections that can be used by the agent.
– Other modules include config, exceptions, schema, llm, and logger to support configuration, error handling, data validation, LLM interfacing, and logging.
- Configuration:
– The “config” folder with a configuration example (in TOML) shows that the system is designed to work with external LLM APIs like OpenAI.
- Testing/Extra:
– Although test directories aren’t present, the clear separation among modules suggests a modular architecture that could be easily extended or isolated for testing.

##### Highlighting Key Components and Architecture
a. Main Components:
- User Interface / Entry Points: main.py and run_flow.py act as the application entry points, which set up the environment and start the interaction with the agent.
- Agent Module: Located in app/agent and app/prompt, these files handle the logic for different agent behaviors (e.g., planning, reactive strategies, tool call handling, and manual input).
- Flow Module: In app/flow, which creates and manages the flow of operations, determining how tasks are orchestrated.
- LLM Interface: app/llm provides the abstraction for communication with the LLM APIs, factoring in configuration provided via the config files.
- Tool Module: app/tool encapsulates various utilities (e.g., browser automation, file saving, command execution) which the agent can invoke as part of its operations.
- Configuration and Logging: Separate components handle runtime configuration-read (via app/config.py and config files) and logging (via app/logger.py).
- Exception Handling and Schemas: Components like app/exceptions.py and app/schema.py ensure the system is robust, providing error handling and data validation.

b. Relationships and Interactions:
- At startup (via main.py or run_flow.py), the system loads configurations and initializes the logger.
- The central “Agent” module coordinates with the “Flow” module, determining what actions to take.
- For each task, the agent retrieves relevant prompt templates from the “Prompt” module, then uses the “LLM” module to communicate with the external API.
- If the LLM processing or agent logic determines that an external operation is needed, it dispatches a request to one or more components in the “Tool” module.
- Throughout this, error handling and schema validation ensure that inputs, outputs, and operations are correctly processed.

c. Architectural Patterns/Design Principles:
- Modular design: Each functional domain (agent, flow, llm, prompt, tool) is isolated in its own module.
- Separation of Concerns: The clear separation between logic handling, configuration management, LLM communications, and tool execution.
- Extensibility: The use of a “flow_factory” and “tool_collection” indicates that the design anticipates additional flows or tools, making the system easy to extend.

d. Key Technologies, Frameworks, and Libraries:
- Python 3.12 is the target.
- External API integration with OpenAI’s API (LLM functionality) configured via a TOML file.
- Dependency management via pip (as detailed in requirements.txt).

- A “Prompt Manager” node that shows how different sets of prompt templates (manus, planning, etc.) are maintained and fetched.
- An “LLM Interface” component responsible for all communications with external LLM APIs.
- A “Tool Executor” block containing different tools (bash, browser, file saver, etc.) used by the agent.
– From user input → Entry Points
– From the agent to the LLM Interface and back
– From the agent to the Tool Executor when external actions are needed.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% User Interface / Entry Points
    subgraph "User Interface / Entry Points"
        UI1["main.py"]:::entry
        UI2["run_flow.py"]:::entry
    end

    %% Agent Engine
    subgraph "Agent Engine"
        A_main["Base Agent"]:::agent
        A_manus["Manus Agent"]:::agent
        A_planning["Planning Agent"]:::agent
        A_react["React Agent"]:::agent
        A_swe["SWE Agent"]:::agent
        A_toolcall["Toolcall Agent"]:::agent
    end

    %% Flow Manager
    subgraph "Flow Manager"
        FL_base["Flow Base"]:::flow
        FL_factory["Flow Factory"]:::flow
        FL_planning["Flow Planning"]:::flow
    end

    %% Prompt Manager
    subgraph "Prompt Manager"
        PM_manus["Manus Prompt"]:::prompt
        PM_planning["Planning Prompt"]:::prompt
        PM_swe["SWE Prompt"]:::prompt
        PM_toolcall["Toolcall Prompt"]:::prompt
    end

    %% LLM Interface
    LLM["LLM Interface"]:::llm

    %% Tool Executor
    subgraph "Tool Executor"
        T_base["Tool Base"]:::tool
        T_bash["Bash Tool"]:::tool
        T_browser["Browser Tool"]:::tool
        T_chat["Chat Completion"]:::tool
        T_file["File Saver"]:::tool
        T_google["Google Search"]:::tool
        T_planning["Planning Tool"]:::tool
        T_python["Python Execute"]:::tool
        T_run["Run Tool"]:::tool
        T_str["String Replace Editor"]:::tool
        T_terminate["Terminate Tool"]:::tool
        T_collection["Tool Collection"]:::tool
    end

    %% Configuration
    subgraph "Configuration"
        CONF_file["Config File"]:::config
        CONF_app["App Config"]:::config
    end

    %% Logging & Exception Handling
    subgraph "Logging & Exception Handling"
        LOG_logger["Logger"]:::log
        LOG_exceptions["Exceptions"]:::log
    end

    %% Schema Validation
    SCHEMA["Schema Validation"]:::schema

    %% Data Flow
    UI1 -->|"start"| A_main
    UI2 -->|"start"| A_main

    A_main -->|"fetch_prompt"| PM_manus
    A_planning -->|"fetch_prompt"| PM_planning
    A_react -->|"fetch_prompt"| PM_swe
    A_toolcall -->|"fetch_prompt"| PM_toolcall

    A_main -->|"calls"| LLM
    LLM -->|"response"| A_main

    A_main -->|"invokes_tool"| T_base
    A_toolcall -->|"uses"| T_collection

    A_main -->|"orchestrates"| FL_base
    FL_factory -->|"orchestrates"| A_planning

    A_main -->|"validates"| SCHEMA

    %% Configuration to Modules
    CONF_file -->|"configures"| A_main
    CONF_file -->|"configures"| FL_base
    CONF_app -->|"configures"| LLM
    CONF_app -->|"configures"| T_base

    %% Logging from Modules
    A_main -->|"logs_to"| LOG_logger
    FL_base -->|"logs_to"| LOG_logger
    LLM -->|"logs_to"| LOG_logger
    T_base -->|"logs_to"| LOG_logger

    %% Click Events
    click UI1 "https://github.com/xiguazhiprince/openmanus/blob/main/main.py"
    click UI2 "https://github.com/xiguazhiprince/openmanus/blob/main/run_flow.py"

    click A_main "https://github.com/xiguazhiprince/openmanus/blob/main/app/agent/base.py"
    click A_manus "https://github.com/xiguazhiprince/openmanus/blob/main/app/agent/manus.py"
    click A_planning "https://github.com/xiguazhiprince/openmanus/blob/main/app/agent/planning.py"
    click A_react "https://github.com/xiguazhiprince/openmanus/blob/main/app/agent/react.py"
    click A_swe "https://github.com/xiguazhiprince/openmanus/blob/main/app/agent/swe.py"
    click A_toolcall "https://github.com/xiguazhiprince/openmanus/blob/main/app/agent/toolcall.py"

    click FL_base "https://github.com/xiguazhiprince/openmanus/blob/main/app/flow/base.py"
    click FL_factory "https://github.com/xiguazhiprince/openmanus/blob/main/app/flow/flow_factory.py"
    click FL_planning "https://github.com/xiguazhiprince/openmanus/blob/main/app/flow/planning.py"

    click PM_manus "https://github.com/xiguazhiprince/openmanus/blob/main/app/prompt/manus.py"
    click PM_planning "https://github.com/xiguazhiprince/openmanus/blob/main/app/prompt/planning.py"
    click PM_swe "https://github.com/xiguazhiprince/openmanus/blob/main/app/prompt/swe.py"
    click PM_toolcall "https://github.com/xiguazhiprince/openmanus/blob/main/app/prompt/toolcall.py"

    click LLM "https://github.com/xiguazhiprince/openmanus/blob/main/app/llm.py"

    click T_base "https://github.com/xiguazhiprince/openmanus/blob/main/app/tool/base.py"
    click T_bash "https://github.com/xiguazhiprince/openmanus/blob/main/app/tool/bash.py"
    click T_browser "https://github.com/xiguazhiprince/openmanus/blob/main/app/tool/browser_use_tool.py"
    click T_chat "https://github.com/xiguazhiprince/openmanus/blob/main/app/tool/create_chat_completion.py"
    click T_file "https://github.com/xiguazhiprince/openmanus/blob/main/app/tool/file_saver.py"
    click T_google "https://github.com/xiguazhiprince/openmanus/blob/main/app/tool/google_search.py"
    click T_planning "https://github.com/xiguazhiprince/openmanus/blob/main/app/tool/planning.py"
    click T_python "https://github.com/xiguazhiprince/openmanus/blob/main/app/tool/python_execute.py"
    click T_run "https://github.com/xiguazhiprince/openmanus/blob/main/app/tool/run.py"
    click T_str "https://github.com/xiguazhiprince/openmanus/blob/main/app/tool/str_replace_editor.py"
    click T_terminate "https://github.com/xiguazhiprince/openmanus/blob/main/app/tool/terminate.py"
    click T_collection "https://github.com/xiguazhiprince/openmanus/blob/main/app/tool/tool_collection.py"

    click CONF_file "https://github.com/xiguazhiprince/openmanus/blob/main/config/config.example.toml"
    click CONF_app "https://github.com/xiguazhiprince/openmanus/blob/main/app/config.py"

    click LOG_logger "https://github.com/xiguazhiprince/openmanus/blob/main/app/logger.py"
    click LOG_exceptions "https://github.com/xiguazhiprince/openmanus/blob/main/app/exceptions.py"

    click SCHEMA "https://github.com/xiguazhiprince/openmanus/blob/main/app/schema.py"

    %% Styles
    classDef entry fill:#f9c,stroke:#333,stroke-width:2px;
    classDef agent fill:#bbf,stroke:#333,stroke-width:2px;
    classDef flow fill:#bfb,stroke:#333,stroke-width:2px;
    classDef prompt fill:#ff9,stroke:#333,stroke-width:2px;
    classDef llm fill:#f99,stroke:#333,stroke-width:2px;
    classDef tool fill:#9cf,stroke:#333,stroke-width:2px;
    classDef config fill:#cfc,stroke:#333,stroke-width:2px;
    classDef log fill:#fc9,stroke:#333,stroke-width:2px;
    classDef schema fill:#cff,stroke:#333,stroke-width:2px;
```
