# jokyun/langmanus architecture

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

- Interactive diagram: https://gitdiagram.com/jokyun/langmanus
- Repository: https://github.com/jokyun/langmanus

## Overview

##### Project Type and Purpose
- LangManus is an open-source, community-driven AI automation framework focused on multi-agent coordination. It combines language models with specialized tools for tasks such as web search, crawling, Python code execution, and workflow management.
- The README emphasizes the academic research objectives as well as system experimentation for multi-agent collaboration (e.g., coordinator, planner, supervisor, researcher, coder, browser, and reporter roles).

##### File Structure for Architectural Clues
- Top-Level Components:
- Configuration and environment: Files like .env.example, conf.yaml.example, Dockerfile, docker-compose.yml, and pre-commit indicate environment management and deployment automation.
- Source code structure: The src folder is divided into sub-modules such as agents, api, config, crawler, graph, llms, prompts, service, tools, and utils. This organization points to a layered design, where agents handle specific tasks and integrate with API and tool modules.
- Entry points: main.py (likely for CLI or main workflow execution) and server.py (FastAPI-based API server for streaming chat interactions).
- Testing and Continuous Integration: The tests directory, Makefile, and GitHub workflows (build, lint, test) indicate automated quality checks.
- Prominent Patterns:
- Modular decomposition with clear separation for agents, configuration, tools, and API endpoints.
- Use of prompt files to define agent roles, suggesting a template-based behavioral system.
- Docker and docker-compose files indicate containerization and support for both backend and web UI (the latter is in a separate repo).

##### Key Components
a. Multi-Agent System:
- Agent Coordinator/Supervisor: Central entity that delegates tasks to and orchestrates other agents.
- Specialized Agents: Include Planner, Researcher, Coder, Browser, Reporter. Use the prompts (in src/prompts) and implementation (in src/agents) as references.

b. API Server:
- The FastAPI-based interface (server.py and src/api/app.py) that exposes endpoints (e.g., POST /api/chat/stream) for external interactions.

c. Supporting Modules:
- Configuration Module: (src/config) which holds settings, LLM model configurations, and environment variable integration.
- Web Crawling Module: (src/crawler) dealing with content extraction, web scraping, and interaction with Jina and Tavily.
- Graph Visualization: (src/graph) that possibly builds and maintains the workflow graph.
- LLM Integration: (src/llms) managing different models for reasoning, basic tasks, and vision-language tasks.
- Tooling and Utilities: (src/tools and src/utils) encapsulating common supporting functions (e.g., file management, bash tool, search utilities).

d. Infrastructure and Deployment Elements:
- Docker Configuration: Dockerfile and docker-compose.yml are used to containerize the application.
- Versioning and CI/CD: GitHub workflows and Makefile directives for linting, testing, and formatting.

##### Relationships and Data Flow
- How a client or web UI (which is provided via a separate repository) interacts with the API server.
- Interactions for external integrations such as online search (Tavily, Jina) and web browsing (using Playwright with browser configurations).

##### Architectural Patterns and Design Principles
- Multi-agent architectural pattern: Emphasize the hierarchical structure (with a coordinator/supervisor at the top level orchestrating various specialized agents).
- Separation of concerns: Distinct modules for API handling, configuration, crawling, intelligent reasoning (LLMs), and utility functions.
- Extensibility: The prompt system (markdown templates) encourages easy modifications to agent behaviors without deeply changing the codebase.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API & Client Layer
    subgraph "API & Client"
        Client["Client (Web UI/CLI)"]:::external
        APIServer["API Server (FastAPI)"]:::api
        APIEntry["API Entry"]:::api
        Workflow["Workflow Service"]:::service
    end

    %% Multi-Agent System
    subgraph "Multi-Agent System"
        AgentCoordinator["Agent Coordinator (Supervisor)"]:::agent
        SupervisorPrompt["Supervisor Prompt"]:::agent
        Planner["Planner Agent"]:::agent
        PlannerPrompt["Planner Prompt"]:::agent
        Researcher["Researcher Agent"]:::agent
        ResearcherPrompt["Researcher Prompt"]:::agent
        Coder["Coder Agent"]:::agent
        CoderPrompt["Coder Prompt"]:::agent
        Browser["Browser Agent"]:::agent
        BrowserPrompt["Browser Prompt"]:::agent
        BrowserUtility["Browser Utility"]:::agent
        Reporter["Reporter Agent"]:::agent
        ReporterPrompt["Reporter Prompt"]:::agent
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        Config["Configuration Module"]:::support
        Crawler["Web Crawling Module"]:::support
        Graph["Graph Visualization Module"]:::support
        LLM["LLM Integration Module"]:::support
        Tools["Tooling (src/tools)"]:::support
        Utils["Utilities (src/utils)"]:::support
    end

    %% Deployment & CI/CD
    Deployment["Deployment & CI/CD"]:::infra

    %% External Integrations
    External["External Services (Tavily, Jina, Playwright)"]:::external

    %% Connections - API & Client Flow
    Client -->|"sends request"| APIServer
    APIServer -->|"for processing"| Workflow
    APIEntry --- APIServer
    Workflow -->|"orchestrates"| AgentCoordinator

    %% Connections - Multi-Agent System
    AgentCoordinator -->|"delegates"| Planner
    AgentCoordinator -->|"delegates"| Researcher
    AgentCoordinator -->|"delegates"| Coder
    AgentCoordinator -->|"delegates"| Browser
    AgentCoordinator -->|"delegates"| Reporter

    %% Prompt connections for agents
    AgentCoordinator ---|"uses"| SupervisorPrompt
    Planner ---|"uses"| PlannerPrompt
    Researcher ---|"uses"| ResearcherPrompt
    Coder ---|"uses"| CoderPrompt
    Browser ---|"uses"| BrowserPrompt
    Browser ---|"utilizes"| BrowserUtility
    Reporter ---|"uses"| ReporterPrompt

    %% Supporting Modules dependencies from Workflow
    Workflow -->|"configures"| Config
    Workflow -->|"crawls"| Crawler
    Workflow -->|"builds"| Graph
    Workflow -->|"integrates"| LLM
    Workflow -->|"supports"| Tools
    Workflow -->|"supports"| Utils

    %% External integrations
    Browser -->|"controls"| External
    Researcher -->|"queries"| External

    %% Connections - Deployment
    APIServer -->|"packaged via"| Deployment

    %% Click Events for Multi-Agent Components
    click AgentCoordinator "https://github.com/jokyun/langmanus/blob/main/src/agents/agents.py"
    click SupervisorPrompt "https://github.com/jokyun/langmanus/blob/main/src/prompts/supervisor.md"
    click PlannerPrompt "https://github.com/jokyun/langmanus/blob/main/src/prompts/planner.md"
    click ResearcherPrompt "https://github.com/jokyun/langmanus/blob/main/src/prompts/researcher.md"
    click CoderPrompt "https://github.com/jokyun/langmanus/blob/main/src/prompts/coder.md"
    click BrowserPrompt "https://github.com/jokyun/langmanus/blob/main/src/prompts/browser.md"
    click BrowserUtility "https://github.com/jokyun/langmanus/blob/main/src/tools/browser.py"
    click ReporterPrompt "https://github.com/jokyun/langmanus/blob/main/src/prompts/reporter.md"

    %% Click Events for API Server
    click APIServer "https://github.com/jokyun/langmanus/blob/main/src/api/app.py"
    click APIEntry "https://github.com/jokyun/langmanus/blob/main/server.py"

    %% Click Events for Supporting Modules
    click Config "https://github.com/jokyun/langmanus/tree/main/src/config"
    click Crawler "https://github.com/jokyun/langmanus/tree/main/src/crawler"
    click Graph "https://github.com/jokyun/langmanus/tree/main/src/graph"
    click LLM "https://github.com/jokyun/langmanus/tree/main/src/llms"
    click Tools "https://github.com/jokyun/langmanus/tree/main/src/tools"
    click Utils "https://github.com/jokyun/langmanus/tree/main/src/utils"

    %% Click Event for Deployment
    click Deployment "https://github.com/jokyun/langmanus/blob/main/docker-compose.yml"

    %% Styles
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef service fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef agent fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef support fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef infra fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
