# mannaandpoem/openmanus architecture

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

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

## Overview

##### Project type and purpose
- OpenManus is an open‑source Python framework for building general AI agents (single‐agent or multi‑agent), orchestrating “flows” of prompts, LLM calls, tool invocations, and sandboxed execution.
- It provides a CLI interface (`main.py`, `run_flow.py`, `run_mcp.py`), a modular agent toolkit (`app/agent`), prompt templates (`app/prompt`), LLM wrappers (`app/llm`), a sandboxed execution environment (`app/sandbox`), and a library of tools (`app/tool`).

##### File structure
Top‑level:
- `main.py`, `run_flow.py`, `run_mcp.py`: entrypoints
- `app/`: core framework
- `agent/`: base and specialized agent classes
- `flow/`: flow definitions and factory
- `llm.py`: interface to external LLM APIs
- `prompt/`: prompt‐template modules
- `sandbox/`: client, core manager, terminal, exceptions
- `tool/`: abstraction and concrete tool implementations (search, file ops, Python execution, etc.)
- `config/`: TOML/JSON examples for API keys and settings
- `tests/`: unit tests for sandbox
- `examples/`: usage examples

##### README insights
- CLI usage is primary.
- Supports multiple LLM providers (OpenAI, Anthropic, Azure, etc.).
- Optional browser automation (Playwright).
- Encourages configuration via `config/config.toml`.

We recommend producing two views:
A. System Context (C4 Level 1)

- External System: “Cloud Browser Automation” (optional)
- External System: “File System / Local Shell”

- Developer → OpenManus CLI (“runs commands, inputs ideas”)
- OpenManus CLI → LLM API Provider (“HTTP requests for completions”)
- OpenManus CLI → Cloud Browser Automation (“Playwright calls if enabled”)
- OpenManus CLI → File System / Local Shell (“reads/writes files, runs Python”)

1. CLI Application (main.py, run_flow.py, run_mcp.py)
- Responsibilities: parse commands, load config, bootstrap agent/flow
2. Configuration Loader (app/config.py)
- Parses TOML/JSON into runtime settings
3. Agent Orchestrator (app/agent/*)
- BaseAgent + specialized agents (browser, mcp, swe, react, toolcall, manus)
- Factory to instantiate based on CLI flags
4. Flow Engine (app/flow/*)
- Defines flow patterns (planning, base) and flow_factory
- Manages multi‑step interaction logic
5. Prompt Module (app/prompt/*)
- Templates for each agent/flow
6. LLM Client (app/llm.py)
- Wraps HTTP calls to configured LLM provider
7. Sandbox Manager (app/sandbox/core/manager.py)
- Creates/tears down ephemeral Docker or in‑process sandboxes
8. Sandbox Terminal (app/sandbox/core/terminal.py)
- Executes shell commands in sandbox
9. Tool Runner (app/tool/*)
- Abstract base plus tool_collection for Python exec, searches, file ops, etc.

- CLI App → Config Loader → returns settings → CLI App
- CLI App → Agent Orchestrator → selects Flow Engine
- Flow Engine ↔ Prompt Module (generates prompts)
- Flow Engine → LLM Client → returns LLM response
- LLM Client → External LLM API
- Flow Engine → Tool Runner / Sandbox Manager → executes external code/actions
- Tool Runner → External Browser Automation (if browser tool used)
- Sandbox Manager → Local Docker / OS Shell → returns execution result

##### Architectural Patterns & Design Principles
- Modular containers for separation of concerns (CLI, config, agent, flow, llm, sandbox, tools)
- Factory pattern for agent and flow instantiation (`flow_factory`, agent base factory)
- Strategy pattern for tools and prompts (each tool/prompt is a pluggable module)
- Dependency injection via config loader

##### Elements to Capture
- Clear component names matching code (e.g., “app/agent/browser.py”)
- Configurable integration points (LLM APIs, browser, Docker)
- Factories and pluggable modules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% System Context (C4 Level 1)
    subgraph "System Context"
        direction TB
        Developer["Developer / End‑User"]:::person
        OpenManusCLI["OpenManus CLI"]:::external
        LLMAPI["LLM API Provider"]:::external
        CloudBrowser["Cloud Browser Automation"]:::external
        FileSystem["File System / Local Shell"]:::external
    end

    Developer -->|"runs commands, inputs ideas"| OpenManusCLI
    OpenManusCLI -->|"HTTP requests for completions"| LLMAPI
    OpenManusCLI -->|"Playwright calls if enabled"| CloudBrowser
    OpenManusCLI -->|"reads/writes files, runs Python"| FileSystem

    %% Container Diagram (C4 Level 2)
    subgraph "OpenManus" 
        direction TB
        CLIApp["CLI Application\n(main.py, run_flow.py,\nrun_mcp.py, run_mcp_server.py)"]:::cliConfig
        ConfigLoader["Configuration Loader\n(app/config.py)"]:::cliConfig
        AgentOrchestrator["Agent Orchestrator\n(app/agent/base.py\n+ specialized agents)"]:::agentFlow
        FlowEngine["Flow Engine\n(app/flow/base.py,\nflow_factory.py,\nplanning.py)"]:::agentFlow
        PromptModule["Prompt Module\n(app/prompt/*)"]:::llmPrompt
        LLMClient["LLM Client\n(app/llm.py,\napp/bedrock.py)"]:::llmPrompt
        SandboxManager["Sandbox Manager\n(app/sandbox/core/manager.py)"]:::sandboxTools
        SandboxTerminal["Sandbox Terminal\n(app/sandbox/core/terminal.py)"]:::sandboxTools
        ToolRunner["Tool Runner\n(app/tool/base.py,\ntool_collection.py)"]:::sandboxTools
        MCPServer["MCP Server\n(app/mcp/server.py)"]:::agentFlow
    end

    CLIApp -->|"loads config"| ConfigLoader
    CLIApp -->|"bootstrap agent/flow"| AgentOrchestrator
    AgentOrchestrator -->|"selects flow"| FlowEngine
    FlowEngine -->|"generates prompt"| PromptModule
    PromptModule -->|"template"| FlowEngine
    FlowEngine -->|"calls"| LLMClient
    LLMClient -->|"HTTP request"| LLMAPI
    FlowEngine -->|"executes tool"| ToolRunner
    FlowEngine -->|"manages sandbox"| SandboxManager
    SandboxManager -->|"executes in shell"| SandboxTerminal
    ToolRunner -->|"optional browser tool"| CloudBrowser
    SandboxManager -->|"uses local shell/docker"| FileSystem

    %% Click Events
    click CLIApp "https://github.com/mannaandpoem/openmanus/blob/main/main.py"
    click ConfigLoader "https://github.com/mannaandpoem/openmanus/blob/main/app/config.py"
    click AgentOrchestrator "https://github.com/mannaandpoem/openmanus/blob/main/app/agent/base.py"
    click FlowEngine "https://github.com/mannaandpoem/openmanus/blob/main/app/flow/base.py"
    click PromptModule "https://github.com/mannaandpoem/openmanus/tree/main/app/prompt/"
    click LLMClient "https://github.com/mannaandpoem/openmanus/blob/main/app/llm.py"
    click SandboxManager "https://github.com/mannaandpoem/openmanus/blob/main/app/sandbox/core/manager.py"
    click SandboxTerminal "https://github.com/mannaandpoem/openmanus/blob/main/app/sandbox/core/terminal.py"
    click ToolRunner "https://github.com/mannaandpoem/openmanus/blob/main/app/tool/base.py"
    click MCPServer "https://github.com/mannaandpoem/openmanus/blob/main/app/mcp/server.py"

    %% Styles
    classDef person fill:#CCCCFF,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef cliConfig fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef agentFlow fill:#90EE90,stroke:#000,stroke-width:1px
    classDef llmPrompt fill:#FFFF99,stroke:#000,stroke-width:1px
    classDef sandboxTools fill:#FFCC99,stroke:#000,stroke-width:1px
```
