# openmanus-ai/openmanus architecture

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

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

## Overview

##### Main Components
- Agent Module: Represented by the entire “app/agent” folder, which includes various agent components (base, planning, react, swe, and toolcall). This module encapsulates the logic that drives the AI agent’s decisions and interactions.
- Flow Module: Depicted as the “app/flow” directory where different flow strategies (including planning flows) are defined. This module orchestrates and manages the sequence of operations or tasks.
- Prompt Module: Illustrated by “app/prompt”, which handles prompt engineering for different agent behaviors (manus, planning, swe, toolcall). It forms part of the communication layer with the LLM.
- Tool Module: Shown via “app/tool”, which gathers several “tool” implementations handling diverse functionalities like bash commands, browser interactions, chat completions, file saving, Google Search, Python code execution, etc. These represent extension points where the agent can offload specific tasks.
- LLM Interface: The “app/llm.py” file is essential as it abstracts communication with the LLM API (e.g., GPT-4o).
- Core Configuration and Utility Code: Include components such as “app/config.py”, “app/exceptions.py”, and “app/logger.py” that manage configuration, error handling, and logging aspects of the system.
- External Configuration: The “config” directory (and its configuration file config.example.toml) shows how external parameters (like API keys, model settings, etc.) are loaded to tailor the behavior of the agent.

##### Relationships and Interactions
- The main execution entry point (main.py or run_flow.py) initializes the overall system.
- The central agent (from app/agent) leverages the llm module to interact with external LLM APIs, using prompt templates (from app/prompt) to structure the queries.
- The agent’s decision-making process is further enhanced through “flow” components which determine how tasks are sequenced, and “tool” modules are invoked to perform specialized operations.
- Configuration modules and external config files ensure that the system remains flexible to changes in API endpoints, keys, and other parameters.
- Error and logging modules encapsulate cross-cutting concerns, ensuring smooth debugging and monitoring.

##### Architectural Patterns and Design Principles
- Modularity: The project is segmented into distinct components (agent, flow, prompt, tool) which interact through well-defined interfaces.
- Separation of Concerns: There is a clear delineation between core agent logic, prompt handling, and tool executions which reinforces maintainability.
- Extensibility: The agent framework is designed for future enhancements, such as integration with reinforcement learning tuning (referenced in OpenManus-RL) or additional tools.

##### Relevant Technologies and Frameworks
- Python (with the use of virtual environments and dependency management via pip or uv)
- TOML for configuration
- LLM APIs (for example, OpenAI’s API, as referenced in the configuration)
- GitHub Actions (visible in the .github/workflows directory) for CI/CD processes
- Pre-commit hooks defined in .pre-commit-config.yaml for code quality

##### Elements
– the LLM Interface (for API calls),
– the Prompt Module (for preparing queries),
– the Tool Module (when delegated tasks are required),
– the Flow Module (for managing task orders).
– Core application logic (Agent, Flow),
– Utility modules (Config, Logger),
– External systems (LLM external API/service),
– Integration components (Tool, Prompt).
- Details like the external configuration file (config/config.example.toml) to demonstrate how the system is tuned at startup.
- Often, drawing separate layers (like a “Business Logic” layer for agent/flow and an “Integration” layer for tools and external APIs) can be helpful.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Main Execution Layer"
        A["Main Execution"]:::main
    end

    subgraph "Business Logic Layer"
        B1["Agent Module"]:::business
        B2["Flow Module"]:::business
    end

    subgraph "Integration Layer"
        I1["Prompt Module"]:::integration
        I2["Tool Module"]:::integration
        I3["LLM Interface"]:::integration
    end

    subgraph "Utilities"
        U1["Configuration"]:::util
        U2["Exceptions"]:::util
        U3["Logger"]:::util
        U4["External Config"]:::util
    end

    %% Main Execution triggers Business Logic components
    A -->|"triggers"| B1
    A -->|"triggers"| B2

    %% Agent Module interactions
    B1 -->|"calls"| I3
    B1 -->|"uses"| I1
    B1 -->|"invokes"| I2
    B1 -->|"orchestrates"| B2

    %% Utilities and configuration relationships
    U4 -->|"loads"| U1
    U1 -->|"configures"| B1
    U1 -->|"configures"| B2
    U1 -->|"configures"| I1
    U1 -->|"configures"| I2
    U1 -->|"configures"| I3

    %% Logging and error handling
    B1 -->|"logs"| U3
    I1 -->|"logs"| U3
    B1 -->|"handles_errors"| U2

    %% Click Events for component mappings
    click B1 "https://github.com/openmanus-ai/openmanus/tree/main/app/agent/"
    click B2 "https://github.com/openmanus-ai/openmanus/tree/main/app/flow/"
    click I1 "https://github.com/openmanus-ai/openmanus/tree/main/app/prompt/"
    click I2 "https://github.com/openmanus-ai/openmanus/tree/main/app/tool/"
    click I3 "https://github.com/openmanus-ai/openmanus/blob/main/app/llm.py"
    click U1 "https://github.com/openmanus-ai/openmanus/blob/main/app/config.py"
    click U2 "https://github.com/openmanus-ai/openmanus/blob/main/app/exceptions.py"
    click U3 "https://github.com/openmanus-ai/openmanus/blob/main/app/logger.py"
    click U4 "https://github.com/openmanus-ai/openmanus/blob/main/config/config.example.toml"

    %% Styles
    classDef main fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef business fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef integration fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef util fill:#FFFF99,stroke:#333,stroke-width:2px;
```
